异步视界博客
iaieye.com

最近更新

    ↑↓ 选择↵ 打开esc 关闭

    Skills 系统:把再次输入的指令变成可加载的能力

    一个 SKILL.md + 几行 frontmatter,5 分钟造一个本机即时生效的能力。走开放标准 agentskills.io,跨 AI 工具兼容。

    • Claude Code 功… · 5/16
    • 精读
    • 2026.05.13
    • 19 分钟
    • 9,209 字

    思思扬撰写 · AI 协作整理

    类型
    精读
    系列
    Claude Code 功能 + 集成生态调研(2026-05)
    位置
    第 5 篇 / 共 16 篇
    发布
    2026.05.13
    篇幅
    9,209 字 · 19 分钟
    章节
    8 节
    标签
    • claude-code
    • ai
    • skills

    原文:https://code.claude.com/docs/en/skills 官方定位:Extend Claude with skills — Create a SKILL.md file with instructions, and Claude adds it to its toolkit. 遵循的标准:agentskills.io(开放标准,跨 AI 工具)— Claude Code 在标准之外做了三项扩展:disable-model-invocation、context: fork、动态 context 注入

    🔥 影响力卡片

    维度数据
    跨 AI 工具兼容走 agentskills.io 开放标准 — 同一个 SKILL.md 理论上能在 Cursor / Gemini CLI / Copilot CLI / Claude Code 通用
    本机你已经在用的 skills~30 个(superpowers 套件 14 个:brainstorming, writing-skills, executing-plans, subagent-driven-development, dispatching-parallel-agents, test-driven-development, systematic-debugging, verification-before-completion, using-git-worktrees, using-superpowers, requesting-code-review, receiving-code-review, finishing-a-development-branch, writing-plans · understand-anything 套件 8 个 · ~/.claude/skills/ 个人 3 个(content-curation / content-curation-auto / gstack-game)· 系统 bundled / 其他 plugin ~10 个:loop / schedule / claude-api / init / review / security-review / simplify / fewer-permission-prompts / update-config / keybindings-help)
    内置 bundled skills(每个 session 自动有)/simplify, /batch, /debug, /loop, /claude-api, /init, /review, /security-review
    Custom commands 现状已合并到 skills(.claude/commands/*.md 还能用,但 skills 是新路径)
    你已经写过 skill 的痕迹~/.claude/skills/content-curation/SKILL.md + ~/.claude/skills/content-curation-auto/SKILL.md — 由我们自己沉淀出来

    🎯 为什么必读

    1. Skill 是 Claude Code 里”边际成本最低”的扩展。

    不像 plugin / MCP / Hook 那么重 — 一个 skill = 一个 SKILL.md 文件 + 几行 YAML frontmatter,5 分钟就能造一个,本机即时生效(live change detection 直接监听目录)。

    2. 它解决的痛点是真痛点

    “Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact.”

    回想你 CLAUDE.md 里有多少行是”流程类”:

    • 启动检查 (grep context/)
    • 隐私红线
    • 自治档位判断
    • 想法 → 拓展 → 竞品 → 定位 → 技术选型 → 0-1 上线

    后面那个执行链 应该是个 skill,不是 CLAUDE.md 里的静态文字 — 因为它是个流程,该按需加载。

    3. 它跟 CLAUDE.md 的根本区别:加载时机不同

    • CLAUDE.md:每次 session 启动都加载,全程占 context
    • Skill body:只有被调用时才加载,但调用后会一直留在 context 直到 session 结束(关键!)

    所以:短小高频的事实 → CLAUDE.md;长冗低频的流程 → skill。

    一句话总结

    Skill = 一个文件夹 + SKILL.md(YAML frontmatter 描述何时触发 + 正文写指令)。Claude 看 description 决定要不要自动加载;你也可以 /skill-name 主动调用。一旦加载就常驻 context,所以正文要短而精。

    💎 金句墙

    ★ “Keep SKILL.md under 500 lines. Move detailed reference material to separate files.” “SKILL.md 保持 500 行以下。详细参考资料放到独立文件,按需加载。” —— 🟢 这是 progressive disclosure 的核心 — SKILL.md 是入口,supporting files 是延伸

    ★ “Once a skill loads, its content stays in context across turns, so every line is a recurring token cost.” “一旦 skill 被加载,内容会跨 turn 留在 context 里 — 每一行都是循环 token 成本。” —— 🟢 决定了你不能把 skill 写得像 README — 每行都要”必要而充分”

    ★ “State what to do rather than narrating how or why.” “写’做什么’,不要写’怎么做’和’为什么这样做’。” —— 🟢 LLM 不需要 onboarding 解释,需要清晰指令 — 写 skill 时跟写给新员工的 SOP 完全不同

    ★ “After compaction, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each.” “压缩后,Claude Code 会把每个最近调用过的 skill 重新挂回(只保第 5000 tokens),最近用的优先。” —— 🟢 25k 总预算限制 — 调用太多 skill 会让早的 skill 在压缩时被丢

    📋 核心精读

    1. Skill 的最小例子

    ~/.claude/skills/hello/
    └── SKILL.md
    ---
    description: Greet the user named "$ARGUMENTS" warmly
    ---
    
    # Hello Skill
    
    Greet "$ARGUMENTS" by name and ask how you can help today.

    测试:claude → /hello Alex → Claude 用名字打招呼。

    完事。5 行 YAML + 几行 markdown = 一个 skill。

    2. 4 个存放位置 — 决定 skill 的可见范围

    位置路径适用范围
    企业managed settings整个组织
    个人~/.claude/skills/<name>/SKILL.md所有你的项目
    项目.claude/skills/<name>/SKILL.md单个项目
    Plugin<plugin>/skills/<name>/SKILL.mdplugin 装在哪就在哪

    优先级:enterprise > personal > project。Plugin 用 plugin-name:skill-name 命名空间,不冲突。

    .claude/commands/<name>.md 也算 skill(平等对待),但 skill 比 command 优先级高。

    3. 14 个 frontmatter 字段(精选最常用的 6 个)

    字段用途实例
    description ⭐必写 — Claude 看这个决定何时自动调用description: Reviews code for security issues. Use when reviewing PRs or analyzing auth flows.
    disable-model-invocationtrue = Claude 不会自动调,只能你 /name 触发适用于 /deploy、/commit 这种有副作用的
    user-invocablefalse = Claude 能自动调,你的 / 菜单看不见适用于”背景知识”型 skill,如 legacy-system-context
    allowed-tools这个 skill active 时 Claude 不需要每次问允许的工具allowed-tools: Bash(git add *) Bash(git commit *)
    context: fork + agent: <type>在隔离 subagent 里跑这个 skill,不污染主 session适合”深度调研类”
    pathsglob 匹配 — Claude 只在改这些文件时自动加载这个 skillpaths: ["src/api/**/*.ts"]

    其他次要字段:name、when_to_use、argument-hint、arguments、model、effort、hooks、shell。

    4. 动态 context 注入 — 真正强的功能

    skill 内容里可以用 !`<shell-command>` 在加载时执行 shell,输出会替换占位符:

    ---
    description: Summarizes uncommitted changes. Use when user asks what changed.
    ---
    
    ## Current changes
    
    !`git diff HEAD`
    
    ## Instructions
    
    Summarize the changes above in two-three bullet points. Flag risks like
    missing error handling or hardcoded values.

    加载时 git diff HEAD 先跑,输出直接插进 skill 正文,然后整体作为一条 message 进 Claude。这意味着:

    • skill 不再需要”教 Claude 怎么取数据” — 你直接预处理好喂进去
    • 比”让 Claude 调用 Bash tool 取数据”省 1-2 个 turn
    • 拼接的指令永远基于当前真实状态,不是过期记忆

    多行版本:

    ## Environment
    ```!
    node --version
    npm --version
    git status --short
    ```

    可用变量:

    变量含义
    $ARGUMENTS所有传入参数
    $ARGUMENTS[N] 或 $N第 N 个参数(0-indexed)
    $name(配合 arguments: [...])命名参数
    ${CLAUDE_SESSION_ID}当前 session ID
    ${CLAUDE_EFFORT}当前 effort 级别
    ${CLAUDE_SKILL_DIR}skill 目录的绝对路径 — 必背,用来引用 supporting files

    5. Progressive disclosure — 大 skill 的正确做法

    my-big-skill/
    ├── SKILL.md           # 入口 ~200 行 — 必读
    ├── reference.md       # API 详细参数 — 按需 Read
    ├── examples.md        # 示例 — 按需 Read
    └── scripts/
        └── helper.py      # 实际执行的脚本

    在 SKILL.md 里显式提示 Claude 这些文件存在:

    ## Additional resources
    
    - For complete API details, see [reference.md](reference.md)
    - For usage examples, see [examples.md](examples.md)

    这样:

    • 主流程 token 成本低(SKILL.md 才 200 行)
    • Claude 需要细节时自己 Read 加载
    • supporting files 不占 context 直到真要看

    6. context: fork — 隔离执行(高级用法)

    ---
    description: Research a topic thoroughly
    context: fork
    agent: Explore
    ---
    
    Research $ARGUMENTS thoroughly:
    
    1. Find relevant files using Glob and Grep
    2. Read and analyze the code
    3. Summarize findings with specific file references
    /research authentication-flow

    会:

    1. 开一个新的 subagent context(基于 Explore agent 类型 — read-only,优化于代码探索)
    2. SKILL.md 内容作为 subagent 的 prompt
    3. 干完后 Claude 把结果回总结到主 session
    4. 主 session 的 context 完全不被污染

    适合场景:深度调研、扫描整个 codebase、做单一的封闭任务。不适合:那种纯”知识/约定”型 skill(没具体 task,fork 出去无意义)。

    7. Skill 的生命周期 — 一旦加载就常驻

    [turn 1] 调用 /my-skill → SKILL.md 被注入 context
    [turn 2-N] 内容一直在 context 里
    [compaction] 保第 5000 tokens(总预算 25k,从最近的开始挤老的)
    [新 session] 重置

    这意味着:

    • 不能为了”安全”在 skill 里写一堆 caveat — 每次都会重读 → 浪费 token
    • 可以写 skill 来”改变 Claude 整个对话风格”(因为留着) — 比如 learning-output-style 那种
    • 不要在一个 session 里调 20 个 skill — 老的会在 compaction 后被挤掉

    8. /skills 菜单 + skillOverrides — 临时关掉某 skill

    > /skills
    # 高亮 skill,按 Space 循环 4 个状态,Enter 保存到 .claude/settings.local.json

    四种状态:

    状态Claude 能看到/ 菜单显示
    on(默认)名 + 描述是
    name-only只名是
    user-invocable-only不列是(只你能调)
    off不列否

    实际用例:你装了 22 个 skill,某段时间只在做前端 → 把 understand-anything、security-review 临时设 name-only,腾 context 给 frontend-design。

    9. 8 个 bundled skill 你应该知道

    Claude Code 内置的 prompt-based 命令(每个 session 自动可用):

    命令干啥
    /simplify找当前 diff 的可简化代码
    /batch把多个相关任务批量给 Claude 处理
    /debug启动结构化 debug 流程
    /loop你正在用的!循环跑 prompt
    /claude-api涉及 Anthropic API 代码时的开发指引
    /init给新 codebase 生成 CLAUDE.md
    /reviewreview 一个 PR
    /security-review安全审查当前分支改动

    它们就是 skill — 不是硬编码命令。这意味着你可以覆盖它们(同名 skill,personal scope 优先级更高)。

    10. 跟 plugin / subagent 的关系图

                          ┌─────────────────┐
                          │ plugin (容器)   │
                          │  skills/        │
                          │  agents/        │
                          │  hooks/         │
                          │  .mcp.json      │
                          └────────┬────────┘
                                   │
                           含 0-N 个 skill
                                   │
                  ┌────────────────┼────────────────┐
                  │                │                │
              独立 skill        skill + 隔离      skill 引用 subagent
           (主 session 跑)    (context: fork)    (用 Read 加载 agent.md)
                  │                │                │
                  ▼                ▼                ▼
            最常见用法          深度调研           跟 Claude 协作复杂任务

    🟢 译者总评 — 给独立开发者的实战建议

    1. 你已经在用很多 skills,但可能没意识到。

    打开 /help 或在输入框输 /,你能看到几十个 skill 列表(superpowers / understand-anything 这类常用 plugin 一装就十几个,加上 bundled 和个人 skill)。它们决定了 Claude 给你的每一个回答的质量 —— 比如这次调研用 content-curation-auto 控节奏,前几篇文章受 writing-skills 的写作纪律影响。

    2. 立即可以给自己写的两个 skill:

    a. 新项目脚手架 skill(new-project)

    ---
    description: Scaffold a new project under ~/code/ with my standard layout (README, docs/, src/, .gitignore, package.json)
    disable-model-invocation: true
    arguments: [project-name, project-type]
    ---
    
    Create a new project at ~/code/$0:
    
    1. mkdir + git init
    2. Write README.md with sections: Problem, Tech, Run, Status
    3. If $1 is "frontend": Vite + React + TS + Tailwind
       If $1 is "node": Bun + TS strict mode
       ...
    
    !`ls ~/code/`

    b. Deployment 检查 skill(deploy-check)

    ---
    description: Pre-deployment checklist for my projects.
    disable-model-invocation: true
    allowed-tools: Bash(git *)
    ---
    
    ## Current state
    - Branch: !`git branch --show-current`
    - Uncommitted: !`git status --short`
    - Last commit: !`git log -1 --pretty=oneline`
    
    ## Checklist
    1. CI passing?
    2. README up to date?
    3. Env vars documented?
    4. License set?
    5. ...

    3. 警惕的反模式:

    • ❌ skill 写得跟 README 一样长 — 每行都进 context,500 行已经太多
    • ❌ skill 重复 CLAUDE.md 的内容 — CLAUDE.md 已经在 context 里了
    • ❌ skill 当文档用 — 那是 supporting files 的事
    • ❌ 20+ skill 同时活跃 — 占满 context budget,压缩时丢
    • ❌ allowed-tools 给太多 — skill 一加载就放权;在恶意 skill 里这是后门

    4. Skill 系统是 Anthropic 在押注”AI 工作流的 npm”

    agentskills.io 是个开放标准。Anthropic 在试图让 skill 成为跨 AI 工具的能力分发单位 — 你写一个 skill,理论上 Cursor / Gemini CLI / Copilot CLI 都能用。这个野心很大,而且如果成,Claude Code 就是事实上的”包管理”参考实现。

    值得关注的下一波动作:

    • skill 加 version 字段(目前是 plugin 携带版本,skill 单独还没)
    • 公开的 skill registry(目前要走 plugin marketplace)
    • 跨工具兼容性认证

    🔗 延伸阅读

    3 条
    • 同系列:04-plugins-marketplace.md(skill 的分发容器)、06-hooks.md(skill 配合 hook 做强制约束)
    • 官方:/en/sub-agents — context: fork 的另一边
    • 官方:/en/commands — 内置命令一览,bundled skill 用 Skill 标记
    • 标准:agentskills.io — 开放标准本体

    🔗 调研来源(可校验)

    • 主原文:https://code.claude.com/docs/en/skills
    • 本地自己写的 skill 通常放 ~/.claude/skills/<skill-name>/SKILL.md
    • bundled skill 验证:在 Claude Code 输入框输入 / 应能看到 /simplify、/batch、/debug、/loop 等
    • 开放标准:agentskills.io(撰文时已注册,内容可能仍在迭代)
    系列全部 16 篇
    1. 01Agent View:一个窗口管所有 Claude Code sessions13 分钟
    2. 02Remote Control:用浏览器和手机驱动本机的 Claude Code16 分钟
    3. 03Claude in Chrome:让 Claude Code 直接驾驶你的浏览器14 分钟
    4. 04Plugins + Marketplace:Claude Code 一切扩展的载体20 分钟
    5. 05Skills 系统:把再次输入的指令变成可加载的能力19 分钟
    6. 06Hooks:在 Claude Code 生命周期上挂触发器18 分钟
    7. 07MCP 客户端 + 第三方服务器生态18 分钟
    8. 08Subagents:Agent tool 调度专家小队20 分钟
    9. 09Routines / Scheduled Tasks / /loop:三层调度栈16 分钟
    10. 10GitHub Actions 集成:让 Claude 在 CI 里跑17 分钟
    11. 11Memory 系统:CLAUDE.md + auto memory19 分钟
    12. 12Channels:把外部事件推进活跃 session15 分钟
    13. 13IDE 集成:VSCode + JetBrains 扩展16 分钟
    14. 14Computer Use:让 Claude 真的操作你的电脑18 分钟
    15. 15Claude Code 概念全集 / 关键词速查表36 分钟
    16. 99附录:Claude 全产品矩阵中 Claude Code 的位置12 分钟