Skill，把重复任务沉淀成能力单元

启动时只加载 Skill 摘要。
任务匹配时再加载完整 Skill。
执行过程中再按需读取参考资料或脚本。

Tool 是“能做什么动作”。
Skill 是“遇到这类任务时，应该怎么做”。

code-review/
└── SKILL.md

research-brief/
├── SKILL.md
└── references/
    └── report-template.md

---
name: code-review
description: Use this skill when reviewing TypeScript code changes for correctness, regressions, missing tests, risky edge cases, or pull request feedback.
---

# Code Review Skill
 
Use this skill when the user asks for a code review, patch review, pull request review, or risk check.
 
## Workflow
 
1. Read the changed code before judging it.
2. Focus on bugs, regressions, missing tests, data loss, security risks, and edge cases.
3. Prefer concrete findings over general advice.
4. For each finding, include the file path, the relevant line if available, and why the behavior can fail.
5. If no issues are found, say that clearly and mention any remaining test gap.
 
## Output Format
 
Put findings first.
 
Use this order:
 
1. Findings
2. Open questions or assumptions
3. Brief summary

启动时：
  只加载每个 Skill 的 name 和 description
 
任务匹配时：
  加载完整 SKILL.md
 
执行过程中：
  按需读取 references / scripts / assets

available skills:
- code-review: Use this skill when reviewing TypeScript code changes...
- research-brief: Use this skill when turning technical research into a concise brief...

examples/09-skill/skills/code-review/SKILL.md

examples/09-skill/
├── README.md
├── skill-agent.ts
└── skills/
    ├── code-review/
    │   └── SKILL.md
    └── research-brief/
        ├── SKILL.md
        └── references/
            └── report-template.md

pnpm example examples/09-skill/skill-agent.ts

pnpm example examples/09-skill/skill-agent.ts "把 Skill 和 Tool 的区别整理成一份技术调研 brief"

OPENAI_MODEL=gpt-5-mini

加载 Skill Catalog
-> 让模型选择是否激活 Skill
-> 读取完整 SKILL.md 并继续生成回答

type SkillSummary = {
  name: string;
  description: string;
  directory: string;
  skillFile: string;
};

async function loadSkillCatalog(): Promise<SkillSummary[]> {
  const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
  const skills: SkillSummary[] = [];
 
  for (const entry of entries) {
    if (!entry.isDirectory()) {
      continue;
    }
 
    const directory = path.join(skillsRoot, entry.name);
    const skillFile = path.join(directory, "SKILL.md");
    const markdown = await fs.readFile(skillFile, "utf8");
    const frontmatter = parseFrontmatter(markdown);
 
    skills.push({
      name: frontmatter.name,
      description: frontmatter.description,
      directory,
      skillFile,
    });
  }
 
  return skills;
}

function parseFrontmatter(markdown: string) {
  const match = markdown.match(/^---\n([\s\S]*?)\n---/);
 
  if (!match) {
    throw new Error("SKILL.md 缺少 frontmatter。");
  }
 
  const fields = new Map<string, string>();
 
  for (const line of match[1]?.split("\n") ?? []) {
    const separator = line.indexOf(":");
 
    if (separator === -1) {
      continue;
    }
 
    const key = line.slice(0, separator).trim();
    const value = line.slice(separator + 1).trim();
 
    fields.set(key, value);
  }
 
  const name = fields.get("name");
  const description = fields.get("description");
 
  if (!name || !description) {
    throw new Error("SKILL.md frontmatter 需要 name 和 description。");
  }
 
  return { name, description };
}

function formatSkillCatalog(skills: SkillSummary[]) {
  return skills
    .map((skill) => `- ${skill.name}: ${skill.description}`)
    .join("\n");
}

const messages: Message[] = [
  {
    role: "system",
    content: [
      "你是一个 TypeScript Agent 教程里的工程助手。",
      "你可以看到 available skills，但现在还没有看到完整 Skill 内容。",
      "如果用户任务明显匹配某个 Skill 的 description，请先调用 activateSkill。",
      "如果没有匹配的 Skill，请直接回答，不要强行激活。",
      "",
      "available skills:",
      formatSkillCatalog(skills),
    ].join("\n"),
  },
  {
    role: "user",
    content: userInput,
  },
];

请 review 下面这个 TypeScript patch，重点找 correctness、regression 和 missing tests 风险：
 
diff --git a/src/permissions.ts b/src/permissions.ts
--- a/src/permissions.ts
+++ b/src/permissions.ts
@@
 type User = {
   id: string;
   name: string;
   isAdmin: boolean;
 };
 
 export function canEditProject(user: User | undefined) {
-  return user?.isAdmin === true;
+  return user!.isAdmin;
 }

- code-review: Use this skill when reviewing TypeScript code changes for correctness...
- research-brief: Use this skill when turning technical research into a concise brief...

activateSkill({ "name": "code-review" })

const tools = [
  {
    type: "function" as const,
    function: {
      name: "activateSkill",
      description:
        "Load the full SKILL.md instructions for a skill when the user's task matches that skill description.",
      parameters: {
        type: "object",
        properties: {
          name: {
            type: "string",
            description: "The skill name from the available skills catalog.",
          },
        },
        required: ["name"],
        additionalProperties: false,
      },
    },
  },
];

async function activateSkill(name: string, skills: SkillSummary[]) {
  const skill = skills.find((candidate) => candidate.name === name);
 
  if (!skill) {
    return `没有找到名为 ${name} 的 Skill。`;
  }
 
  const markdown = await fs.readFile(skill.skillFile, "utf8");
 
  return [
    `Activated skill: ${skill.name}`,
    `Directory: ${path.relative(repositoryRoot, skill.directory)}`,
    "",
    markdown,
  ].join("\n");
}

messages.push({
  role: "tool",
  tool_call_id: call.id,
  content: skillContent,
});

tool_choice: "none"

description: Helps with code review.

description: Use this skill when reviewing TypeScript code changes for correctness, regressions, missing tests, risky edge cases, or pull request feedback.

description: Use this skill when turning technical research into a concise brief with context, findings, tradeoffs, recommendation, and next steps.

## References
 
If the brief needs a more formal structure, read:
 
- `references/report-template.md`

scripts/check-links.ts
scripts/validate-frontmatter.ts
scripts/build-preview.ts

Before finalizing, run scripts/check-links.ts.

帮我 review 这个 TypeScript patch
看一下这个 PR 有没有明显风险
检查这段工具调用代码可能有什么 bug

解释一下 tool calling 是什么
帮我把这段话翻译成英文
总结 README 里的安装步骤

扫描 skills 目录
-> 解析每个 SKILL.md 的 name 和 description
-> 把 Skill catalog 放进上下文
-> 模型调用 activateSkill
-> 程序读取完整 SKILL.md
-> 模型按 Skill 完成任务

Tool：执行动作
MCP：标准化接入外部能力
RAG：补充外部知识
Context Engineering：决定放什么进上下文
Skill：把重复任务的过程经验按需加载