name: claude-code-skills description: 用于创建Claude Code技能的全面参考，涵盖渐进式披露、SKILL.md结构、references/组织、frontmatter规范和模块化能力开发的最佳实践。

Claude Code技能 - 元参考

此技能提供了创建、组织和管理Claude Code技能的权威参考。在构建新技能或改进现有技能架构时使用。

快速参考

组件	用途	是否必需
`SKILL.md`	主要参考文件，包含frontmatter	是
`scripts/`	可执行代码（运行时不加载）	可选
`references/`	按需加载的文档	推荐
`assets/`	输出文件（模板、图标）	可选
`data/sources.json`	精选外部链接	推荐

跨平台: Agent技能标准被Claude Code、Codex CLI、Gemini CLI和VS Code Copilot采用。技能可跨平台移植。

技能结构

skills/
└── skill-name/
    ├── SKILL.md           # 主要参考（必需）
    ├── scripts/           # 可执行代码（Python/Bash）- 运行时不加载
    │   └── validate.py
    ├── references/        # 按需加载的文档
    │   ├── patterns.md
    │   └── examples.md
    ├── assets/            # 用于生成的输出文件（模板、图标、字体）
    │   └── template.html
    └── data/
        └── sources.json   # 外部参考

目录用途:

scripts/ - 可执行代码；输出被消耗，代码从不加载到上下文中
references/ - 文档在代理需要时加载到上下文中
assets/ - 用于生成输出的文件（不加载到上下文中）

SKILL.md模板

---
name: skill-name
description: 一行描述此技能提供什么以及何时使用
---

# 技能名称 - 快速参考

技能目的和价值的简要概述。

## 快速参考

| 任务 | 工具/方法 | 何时使用 |
|------|-------------|-------------|
| 任务1 | 工具A | 使用上下文 |

## 何时使用此技能

当用户请求时，助手应调用此技能：

- 用例1
- 用例2
- 用例3

## 核心概念

### 概念1

带代码示例的解释：

\`\`\`语言
代码示例
\`\`\`

### 概念2

其他模式...

## 导航

**资源**
- [references/skill-patterns.md](references/skill-patterns.md) - 常见模式
- [references/skill-validation.md](references/skill-validation.md) - 验证标准

**相关技能**
- [../claude-code-agents/SKILL.md](../claude-code-agents/SKILL.md) - 代理创建
- [../claude-code-commands/SKILL.md](../claude-code-commands/SKILL.md) - 命令创建
- [../claude-code-hooks/SKILL.md](../claude-code-hooks/SKILL.md) - 钩子自动化

渐进式披露

技能使用渐进式披露来优化令牌使用：

层	内容	令牌成本
发现	仅名称和描述	~50令牌
激活	完整SKILL.md正文	2K-5K令牌
执行	scripts/、references/、assets/	按需

模式: SKILL.md提供概述 -> 资源仅在需要时加载

限制: 保持SKILL.md在500行以内（<5K令牌）

何时拆分内容

保留在SKILL.md中	移动到references/
决策树	完整API参考
快速命令	分步教程
常见模式	边缘情况处理
1-2个代码示例	完整实现

Frontmatter规范

---
name: string                        # 必需：小写短横线命名，匹配文件夹名称
description: string                 # 必需：主要触发机制（50-300字符）
disable-model-invocation: boolean   # 可选：仅用户可调用（用于/deploy、/commit、/send-slack）
user-invocable: boolean             # 可选：false = 仅背景知识
---

名称规则:

使用短横线命名：ai-llm，而不是AI_LLM_Engineering
精确匹配文件夹名称
具体：software-backend而不是backend

描述规则（主要触发）：

描述是主要触发机制 - 运行时使用它来决定何时调用
在此包含“何时使用”上下文，而不是在正文中
单行，50-300字符
包含关键技术/概念作为触发关键词

可选frontmatter:

disable-model-invocation: true - 仅用户可调用（用于有副作用的流程：/commit、/deploy、/send-slack）
user-invocable: false - 用户不可调用（仅背景知识；运行时相关）

技能类别

类别	前缀	示例
AI/ML	`ai-`	`ai-llm`、`ai-ml-data-science`
软件	`software-`	`software-backend`、`software-frontend`
运维	`ops-`	`ops-devops-platform`
数据	`data-`	`data-lake-platform`、`data-sql-optimization`
质量	`qa-`	`qa-debugging`、`qa-docs-coverage`
开发者工具	`dev-`、`git-`	`dev-api-design`、`git-commit-message`、`dev-workflow-planning`
产品	`product-`	`product-management`、`docs-ai-prd`
文档	`document-`	`document-pdf`、`document-xlsx`
测试	`testing-`、`qa-testing-`	`qa-testing-playwright`、`qa-testing-strategy`
营销	`marketing-`	`marketing-social-media`、`marketing-seo-complete`
Claude Code	`claude-code-`	`claude-code-agents`、`claude-code-skills`

sources.json模式

{
  "metadata": {
    "title": "技能名称 - 来源",
    "description": "简要描述",
    "last_updated": "YYYY-MM-DD",
    "skill": "skill-name"
  },
  "category_name": [
    {
      "name": "资源名称",
      "url": "https://example.com/docs",
      "description": "覆盖内容",
      "add_as_web_search": true
    }
  ]
}

类别应逻辑分组：

official_documentation
tutorials
community_resources
tools_and_libraries

质量检查清单

技能验证检查清单

Frontmatter:
[ ] 名称匹配文件夹名称（短横线命名）
[ ] 描述简洁且可操作

结构:
[ ] SKILL.md在500行以内（如需，拆分到references/）
[ ] references/用于详细内容
[ ] data/sources.json包含精选链接

内容:
[ ] 顶部有快速参考表
[ ] “何时使用”部分存在
[ ] 代码示例可直接复制粘贴
[ ] 底部链接相关技能

质量:
[ ] >40%操作内容（代码、表格、检查清单）
[ ] <50%散文段落
[ ] 所有URL有效（无404）
[ ] 来源在6个月内更新

多技术 vs 单技术技能

单技术技能

software-backend/
├── SKILL.md              # Node.js重点
└── references/
    └── nodejs-patterns.md

多技术技能

software-backend/
├── SKILL.md              # 概述 + 决策树
├── references/
│   ├── nodejs-patterns.md
│   ├── go-patterns.md
│   ├── rust-patterns.md
│   └── python-patterns.md
└── assets/
    ├── nodejs/
    ├── go/
    ├── rust/
    └── python/