skills

Skills 并不是简单的“能力扩展机制”，它本质上是一种按需加载的认知结构。与其把所有知识常驻在上下文中，不如把它们封装成可独立触发的能力单元。当模型判断当前任务涉及某个特定领域时，再加载对应的知识与操作流程。

Skills 是一种可被语义触发的能力包，它包含领域知识、执行步骤、输出规范与约束条件，并在需要时渐进式加载到主 Agent 的认知空间中。

alt text

Skills 解决的核心问题是，在有限的上下文窗口中，让 Agent 在正确的时刻拥有正确的领域知识。

如果把 Claude Code 的技术栈映射到企业组织结构，我们会发现一种高度对称的关系。Tools 对应员工的操作工具；SubAgents 对应岗位分工；Hooks 对应质量与合规流程；CLAUDE.md 类似企业文化与通用规章；MCP Servers 像外部合作伙伴；Plugins 是对外打包的解决方案。

而 Skills，正是企业的 SOP 体系

alt text

两大类型的Skills：参考型和任务型

alt text

api-conventions （这我可以建一个）

.claude/skills/api-conventions/     # skill 目录，名称即 skill 名
└── SKILL.md                        # 主文件（必需）
---
name: api-conventions
description: API design patterns and conventions for this project. Covers RESTful URL naming, response format standards, error handling, and authentication requirements. Use when writing or reviewing API endpoints, designing new APIs, or making decisions about request/response formats.
allowed-tools:
  - Read
  - Grep
  - Glob
---

# API Design Conventions

These are the API design standards for our project. Apply these conventions whenever working with API endpoints.

##  12. <a name='URLNaming'></a>URL Naming

- Use plural nouns for resources: `/users`, `/orders`, `/products`
- Use kebab-case for multi-word resources: `/order-items`, `/user-profiles`
- Nested resources for belongsTo relationships: `/users/{id}/orders`
- Maximum two levels of nesting; beyond that, use query parameters
- Use query parameters for filtering: `/orders?status=active&limit=20`

##  13. <a name='ResponseFormat'></a>Response Format

All API responses must follow this structure:

{
  "data": {},        // 成功时返回的数据
  "error": null,     // 错误时返回错误对象 { code, message, details }
  "meta": {          // 分页和元信息
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

##  14. <a name='HTTPStatusCodes'></a>HTTP Status Codes

- 200: 成功返回数据
- 201: 成功创建资源
- 400: 请求参数错误
- 401: 未认证
- 403: 无权限
- 404: 资源不存在
- 422: 业务逻辑错误
- 500: 服务器内部错误

##  15. <a name='Authentication'></a>Authentication

- All endpoints require Bearer token unless explicitly marked as public
- Public endpoints must be documented with `@public` annotation
- Token format: `Authorization: Bearer <jwt-token>`

##  16. <a name='Versioning'></a>Versioning

- API version in URL path: `/api/v1/users`
- Breaking changes require new version

description = [做什么] + [怎么做] + [什么时候用]

代码审查 Skill

description: Review code for quality, security, and best practices. Checks for bugs, performance issues, and style violations. Use when the user asks for code review, wants feedback on their code, mentions reviewing changes, or asks about code quality.

API 文档 Skill

description: Generate API documentation from code. Extracts endpoints, parameters, and response schemas. Use when the user wants to document APIs, create API reference, generate endpoint documentation, or needs help with OpenAPI/Swagger specs.

数据库查询 Skill

description: Query databases and analyze results. Supports SQL generation, query optimization, and result interpretation. Use when the user asks about data, wants to run queries, needs database information, or mentions tables/schemas.

---
name: my-skill-name                # 可选：Skill 标识符（省略则用目录名）
description: What this does        # 推荐：触发器（最重要！）
argument-hint: "[issue-number]"    # 可选：自动补全时的参数提示
disable-model-invocation: true     # 可选：禁止 Claude 自动触发
user-invocable: false              # 可选：对用户隐藏 /skill-name
allowed-tools:                     # 可选：限制可用工具
  - Read
  - Grep
  - Glob
model: sonnet                      # 可选：指定执行模型
context: fork                      # 可选：在子代理中隔离执行
agent: Explore                     # 可选：context: fork 时的代理类型
hooks:                             # 可选：作用域为此 Skill 的 Hooks
  PreToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: "echo 'Write called in skill'"
---

disable-model-invocation 和 user-invocable这两个字段组合起来控制“谁能触发这个 Skill”。

alt text

任务型skills

在 Claude Code 里，令行禁止几乎可以直接翻译为：disable-model-invocation: true

任务型 Skill 的价值：把重复的对话模式，变成可复用的快捷方式。

alt text

任务型 Skill 设计方法论

动作是什么？ → 命名（commit、deplo，y、review）
谁能触发？ → disable-model-invocation: true
需要什么权限？→ allowed-tools 精确到命令级
启动时需要什么上下文？→ !command 预注入
执行过程需要什么安全网？→ hooks
输出量大不大？→ 大则 context: fork
用什么模型？ → model（简单 haiku，复杂 sonnet）

命令一：智能提交 /commit

---
description: Quick git commit with auto-generated or specified message
argument-hint: [optional: commit message]
disable-model-invocation: true
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*), Bash(git diff:*)
model: haiku
---

Create a git commit.

If a message is provided: $ARGUMENTS
- Use that as the commit message

If no message is provided:
- Analyze the changes with `git diff --staged` (or `git diff` if nothing staged)
- Generate a concise, meaningful commit message

##  17. <a name='Steps'></a>Steps

1. Check `git status` to see current state
2. If nothing staged, run `git add .` to stage all changes
3. Review what will be committed with `git diff --staged`
4. Create commit:
   - If `$ARGUMENTS` is provided, use it as the message
   - Otherwise, generate a message based on the diff
5. Show the commit result

##  18. <a name='CommitMessageFormat'></a>Commit Message Format

- Start with type: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- Be concise but descriptive (max 72 chars for first line)
- Example: `feat: add user authentication with JWT`

##  19. <a name='Output'></a>Output

Show a brief confirmation:
✓ Committed: [commit message] [number] files changed

alt text

渐进式披露

Skill 的渐进式披露设计也是一样：第一层只扫描 description 作为“目录”，第二层在触发时加载 SKILL.md 主文件作为“章节”，第三层再按需加载被引用的具体文件作为“附录”。结构化分层替代信息堆叠，让系统在规模变大时依然高效、可控。

alt text

因为所有 Skill 的 description 共享 15,000 字符的总预算

仔细观察上面的 SKILL.md 设计，你会发现它本质上是一个路由器——根据用户请求的类型，将 Claude 导向不同的资源文件：

用户请求 → SKILL.md（路由判断） → 目标资源 │ ├─ "收入相关" → reference/revenue.md ├─ "成本相关" → reference/costs.md ├─ "利润相关" → reference/profitability.md ├─ "要报告" → templates/analysis_report.md └─ "要计算" → scripts/calculate_ratios.py

首先，先介绍一个技巧，在会话内部，你可以通过/context 命令来查看当前所消耗的Token和上下文内存的具体情况。

alt text

SKILL.md 是路由器，通过Quick Reference 表格用最少 token 完成路由判断。引用文件的“契约式”写法，即契约式引用会告诉 Claude 何时加载、加载什么、得到什么。这里有一个 500 行法则，超过就该重构——把参考、模板、示例移到辅助文件。通过脚本封装来确定性逻辑用脚本，Claude 执行但不需要理解脚本中的内容。

alt text

Skills 与 SubAgent 的配合实战

之前我们讲过了，Skills 解决的是“怎么做”的问题，本质是知识注入——它让同一个 Agent 学会新的能力，就像给一个员工发了一本操作手册，员工还是那个人，只是掌握了更多方法与规范。SubAgents 解决的是“谁来做”的问题，本质是任务委托——它创建一个独立的执行者去完成某件事，就像把任务交给另一位同事，对方拥有自己的上下文、职责边界和决策空间。

alt text

一个生产级的 Skill 的完整架构应该包含这些组件：

.claude/skills/api-generating/          # 标准 Skill 目录
├── SKILL.md                            # 入口：路由 + 核心逻辑
├── PATTERNS.md                         # 知识：框架识别模式
├── STANDARDS.md                        # 规范：文档编写标准
├── EXAMPLES.md                         # 示例：输入输出案例
├── templates/
│   ├── index.md                       # 模板：API 索引页
│   ├── endpoint.md                    # 模板：端点文档
│   └── openapi.yaml                   # 模板：OpenAPI 规范
└── scripts/
    ├── detect_routes.py               # 脚本：路由检测
    └── validate_openapi.sh            # 脚本：规范验证

alt text

SubAgent 预加载 Skills（方向 A 的单次应用）

而同一个 Agent，注入不同的 Skill，就变成不同的专家。这就是组合的力量。

alt text

模式二：Skill + context: fork（方向 B 的直接应用）

alt text

Skills 在 Claude Code 五层架构中的定位

alt text Skills 处于知识层这个“承上启下”的位置——工具层（能做什么）之上，智能体层（谁来做）之下。这个位置不是偶然的，它揭示了 Skills 的本质角色：

alt text

Skill 设计的四种模式

alt text

结构： ├── SKILL.md（入口：重构流程 + 检查清单） ├── reference/ │ ├── naming-conventions.md （命名规范） │ ├── package-structure.md （包结构标准） │ ├── error-handling-patterns.md（异常处理模式） │ └── api-design-guidelines.md （API 设计规范） └── templates/ ├── refactor-plan.md （重构方案模板） └── review-checklist.md （审查清单模板）

skills ​

两大类型的Skills：参考型和任务型 ​

代码审查 Skill ​

API 文档 Skill ​

数据库查询 Skill ​

任务型skills ​

任务型 Skill 设计方法论 ​

渐进式披露 ​

Skills 与 SubAgent 的配合实战 ​

SubAgent 预加载 Skills（方向 A 的单次应用） ​

模式二：Skill + context: fork（方向 B 的直接应用） ​

Skills 在 Claude Code 五层架构中的定位 ​

Skill 设计的四种模式 ​

skills

两大类型的Skills：参考型和任务型

代码审查 Skill

API 文档 Skill

数据库查询 Skill

任务型skills

任务型 Skill 设计方法论

渐进式披露

Skills 与 SubAgent 的配合实战

SubAgent 预加载 Skills（方向 A 的单次应用）

模式二：Skill + context: fork（方向 B 的直接应用）

Skills 在 Claude Code 五层架构中的定位

Skill 设计的四种模式