Skill Loader

核心功能

1. 技能发现

class SkillLoader {
  private SKILL_DIRS = [
    '.skills/',              // 项目级
    '.claude/skills/',       // Claude 兼容
    '~/.skills/',            // 用户级
    '~/.claude/skills/'      // Claude 用户级
  ];

  getSearchPaths(): SkillPath[] {
    const paths: SkillPath[] = [];

    for (const skillDir of this.SKILL_DIRS) {
      // 解析 ~ 路径
      const fullPath = skillDir.startsWith('~')
        ? skillDir.replace('~', os.homedir())
        : path.join(process.cwd(), skillDir);

      if (fs.existsSync(fullPath)) {
        paths.push({
          path: fullPath,
          priority: this.getPriority(skillDir)
        });
      }
    }

    return paths.sort((a, b) => a.priority - b.priority);
  }

  private getPriority(dir: string): number {
    const priorityMap: Record<string, number> = {
      '.skills/': 1,
      '.claude/skills/': 2,
      '~/.skills/': 3,
      '~/.claude/skills/': 4
    };
    return priorityMap[dir] ?? 999;
  }
}

2. 技能解析

interface Skill {
  name: string;
  description: string;
  version: string;
  license?: string;
  category?: string;
  content: string;
  path: string;
  location: 'project' | 'user';
  metadata: Record<string, any>;
}

class SkillLoader {
  async parseSkill(skillDir: string): Promise<Skill | null> {
    const skillPath = path.join(skillDir, 'SKILL.md');

    if (!fs.existsSync(skillPath)) {
      console.warn(`SKILL.md not found in ${skillDir}`);
      return null;
    }

    const content = await fs.readFile(skillPath, 'utf-8');

    // 解析 frontmatter
    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
    if (!frontmatterMatch) {
      console.warn(`Invalid frontmatter in ${skillPath}`);
      return null;
    }

    const frontmatter = frontmatterMatch[1];
    const body = content.slice(frontmatterMatch[0].length);

    // 解析 YAML frontmatter
    const metadata = yaml.parse(frontmatter);

    return {
      name: metadata.name,
      description: metadata.description,
      version: metadata.version ?? '1.0.0',
      license: metadata.license,
      category: metadata.category,
      content: body,
      path: skillDir,
      location: skillDir.includes(process.cwd()) ? 'project' : 'user',
      metadata
    };
  }
}

3. 技能注册表

class SkillRegistry {
  private _skills: Map<string, Skill> = new Map();

  register(skill: Skill): boolean {
    // 同名技能：高优先级覆盖低优先级
    const existing = this._skills.get(skill.name);
    if (existing) {
      const priority = { project: 0, user: 1 };
      if (priority[skill.location] >= priority[existing.location]) {
        console.warn(`Skipping ${skill.name}: existing skill has higher priority`);
        return false;
      }
    }

    this._skills.set(skill.name, skill);
    console.log(`Registered skill: ${skill.name} (${skill.location})`);
    return true;
  }

  get(name: string): Skill | undefined {
    return this._skills.get(name);
  }

  listAll(): Skill[] {
    return Array.from(this._skills.values());
  }

  listByCategory(category: string): Skill[] {
    return this.listAll().filter(s => s.category === category);
  }

  search(query: string): Skill[] {
    const lowerQuery = query.toLowerCase();
    return this.listAll().filter(s =>
      s.name.toLowerCase().includes(lowerQuery) ||
      s.description.toLowerCase().includes(lowerQuery)
    );
  }
}

4. 技能执行器

class SkillExecutor {
  constructor(private registry: SkillRegistry) {}

  async execute(skillName: string, context: any): Promise<SkillResult> {
    const skill = this.registry.get(skillName);

    if (!skill) {
      return {
        success: false,
        error: `Unknown skill: ${skillName}`,
        availableSkills: this.registry.listAll().map(s => ({
          name: s.name,
          description: s.description
        }))
      };
    }

    try {
      // 获取技能指令
      const prompt = this.generateSkillPrompt(skill, context);

      // 执行技能逻辑（这里可以集成到 AI 系统）
      const result = await this.runSkillLogic(skill, prompt, context);

      return {
        success: true,
        skillName,
        prompt,
        result
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : String(error)
      };
    }
  }

  private generateSkillPrompt(skill: Skill, context: any): string {
    return `
Loading skill: ${skill.name}
Version: ${skill.version}
Description: ${skill.description}

## Skill Instructions
${skill.content}

## Current Context
${JSON.stringify(context, null, 2)}
    `.trim();
  }

  private async runSkillLogic(skill: Skill, prompt: string, context: any): Promise<any> {
    // 这里实现技能的具体逻辑
    // 可以调用相关的 TypeScript 函数、API 等

    // 示例：data-import 技能
    if (skill.name === 'data-import') {
      return this.executeDataImport(context);
    }

    // 示例：kpi-calculation 技能
    if (skill.name === 'kpi-calculation') {
      return this.executeKPICalculation(context);
    }

    // 默认：返回技能内容供 AI 使用
    return { instructions: prompt };
  }

  private async executeDataImport(context: any): Promise<any> {
    // 调用 src/services/loaders.ts 中的函数
    const { parseMonthlyCsv, loadOrgs } = await import('@/services/loaders');

    const csvText = context.csvText;
    const data = parseMonthlyCsv(csvText);
    const orgs = await loadOrgs();

    // 验证数据...
    // 保存到 localStorage...

    return { imported: data.length, orgs: orgs.length };
  }

  private async executeKPICalculation(context: any): Promise<any> {
    // 调用 src/domain/ 中的函数
    const { calculateGrowthMetrics } = await import('@/domain/growth');
    const { safeDivide } = await import('@/domain/achievement');

    const { current, baseline } = context;
    const metrics = calculateGrowthMetrics(current, baseline);

    return { metrics };
  }
}

完整集成

在 Next.js 中使用

// src/lib/skill-loader.ts
import { SkillLoader, SkillRegistry, SkillExecutor } from './skill-loader';

// 单例模式
let loaderInstance: SkillLoader | null = null;
let registryInstance: SkillRegistry | null = null;
let executorInstance: SkillExecutor | null = null;

export async function getSkillLoader(): Promise<SkillLoader> {
  if (!loaderInstance) {
    loaderInstance = new SkillLoader();
  }
  return loaderInstance;
}

export async function getSkillRegistry(): Promise<SkillRegistry> {
  if (!registryInstance) {
    const loader = await getSkillLoader();
    registryInstance = new SkillRegistry();

    // 加载所有技能
    const skills = await loader.loadAll();
    skills.forEach(skill => registryInstance!.register(skill));
  }
  return registryInstance;
}

export async function getSkillExecutor(): Promise<SkillExecutor> {
  if (!executorInstance) {
    const registry = await getSkillRegistry();
    executorInstance = new SkillExecutor(registry);
  }
  return executorInstance;
}

// React Hook
export function useSkills() {
  const [skills, setSkills] = useState<Skill[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    getSkillRegistry().then(registry => {
      setSkills(registry.listAll());
      setLoading(false);
    });
  }, []);

  return { skills, loading };
}

export function useSkill(name: string) {
  const [skill, setSkill] = useState<Skill | undefined>();
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    getSkillRegistry().then(registry => {
      setSkill(registry.get(name));
      setLoading(false);
    });
  }, [name]);

  return { skill, loading };
}

React 组件集成

// src/components/SkillSelector.tsx
import { useSkills, useSkill } from '@/lib/skill-loader';

export function SkillSelector() {
  const { skills, loading } = useSkills();
  const [selectedSkill, setSelectedSkill] = useState<string | null>(null);

  if (loading) return <div>Loading skills...</div>;

  return (
    <div>
      <h2>Available Skills</h2>
      <select onChange={(e) => setSelectedSkill(e.target.value)}>
        <option value="">Select a skill...</option>
        {skills.map(skill => (
          <option key={skill.name} value={skill.name}>
            {skill.name} - {skill.description}
          </option>
        ))}
      </select>

      {selectedSkill && <SkillDetail skillName={selectedSkill} />}
    </div>
  );
}

function SkillDetail({ skillName }: { skillName: string }) {
  const { skill } = useSkill(skillName);

  if (!skill) return null;

  return (
    <div>
      <h3>{skill.name}</h3>
      <p>{skill.description}</p>
      <pre>{skill.content}</pre>
    </div>
  );
}

API 参考

SkillLoader

SkillRegistry

SkillExecutor

最佳实践

1. 延迟加载：只在需要时加载技能，避免影响启动性能
2. 缓存机制：缓存已加载的技能，减少重复解析
3. 错误处理：技能加载失败时不影响系统其他功能
4. 日志记录：记录技能加载和执行过程，便于调试
5. 版本管理：支持技能版本，避免兼容性问题

参考文档

• @code .skills/data-import/SKILL.md
• @code .skills/kpi-calculation/SKILL.md
• @code .skills/chart-visualization/SKILL.md