Back to Details

skill-master

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Master

Skill 创作总览

This skill is the entry point for creating and maintaining Agent Skills.
Language requirement: all skills MUST be authored in English.
本Skill是创建和维护Agent Skills的入口。
语言要求： 所有Skill必须使用英文创作。

Quick Navigation

快速导航

  • New to skills? Read: 
    references/specification.md
  • SKILL.md templates? See: 
    assets/skill-templates.md
  • Advanced features (context, agents, hooks)? Read: 
    references/advanced-features.md
  • Creating from docs? Read: 
    references/docs-ingestion.md
  • Validation & packaging? See 
    scripts/
  • 刚接触Skill？请阅读：
    references/specification.md
  • SKILL.md模板？请查看：
    assets/skill-templates.md
  • 高级功能（上下文、Agent、钩子）？请阅读：
    references/advanced-features.md
  • 通过文档创建Skill？请阅读：
    references/docs-ingestion.md
  • 验证与打包？请查看
    scripts/
    目录

When to Use

适用场景

  • Creating a new skill from scratch
  • Updating an existing skill
  • Creating a skill by ingesting external documentation
  • Validating or packaging a skill for distribution
  • 从零开始创建新Skill
  • 更新现有Skill
  • 通过摄取外部文档创建Skill
  • 验证或打包Skill用于分发

Skill Structure (Required)

Skill结构（必填）

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── README.md         # Optional: human-readable description
├── metadata.json     # Optional: extended metadata for publishing
├── references/       # Optional: documentation, guides, API references
├── examples/         # Optional: sample outputs, usage examples
├── scripts/          # Optional: executable code
└── assets/           # Optional: templates, images, data files
my-skill/
├── SKILL.md          # 必填：说明文档 + 元数据
├── README.md         # 可选：面向人类的可读性描述
├── metadata.json     # 可选：用于发布的扩展元数据
├── references/       # 可选：文档、指南、API参考
├── examples/         # 可选：示例输出、使用案例
├── scripts/          # 可选：可执行代码
└── assets/           # 可选：模板、图片、数据文件

Folder Purposes (CRITICAL)

文件夹用途（至关重要）

FolderPurposeExamples
references/
Documentation for agents to readGuides, API docs, concept explanations, troubleshooting
examples/
Sample outputs showing expected formatOutput examples, usage demonstrations
assets/
Static resources to copy/useDocument templates, config templates, images, schemas
scripts/
Executable code to runPython scripts, shell scripts, validators
文件夹用途示例
references/
供Agent阅读的文档指南、API文档、概念解释、故障排查
examples/
展示预期格式的示例输出输出示例、使用演示
assets/
可复制/使用的静态资源文档模板、配置模板、图片、模式
scripts/
可执行代码Python脚本、Shell脚本、验证器

When to Use Each

各文件夹适用场景

Use 
references/
for:
  • Detailed documentation about concepts
  • API references and usage guides
  • Troubleshooting and FAQ
  • Anything the agent needs to read and understand
Use 
examples/
for:
  • Sample outputs showing expected format
  • Usage demonstrations
  • Before/after comparisons
  • Anything showing what the result should look like
Use 
assets/
for:
  • Document templates (markdown files to copy as starting point)
  • Configuration file templates
  • Schema files, lookup tables
  • Images and diagrams
  • Anything the agent needs to copy or reference verbatim
IMPORTANT: Templates belong in 
assets/
, examples in 
examples/
, documentation in 
references/
.
使用
references/
的场景：
  • 关于概念的详细文档
  • API参考和使用指南
  • 故障排查与常见问题
  • 任何Agent需要阅读并理解的内容
使用
examples/
的场景：
  • 展示预期格式的示例输出
  • 使用演示
  • 前后对比
  • 任何展示结果应呈现样式的内容
使用
assets/
的场景：
  • 文档模板（可复制作为起点的Markdown文件）
  • 配置文件模板
  • 模式文件、查找表
  • 图片与图表
  • 任何Agent需要直接复制或引用的内容
重要提示：模板应放在
assets/
，示例放在
examples/
，文档放在
references/
。

Frontmatter Schema

Frontmatter 结构

Every 
SKILL.md
MUST start with YAML frontmatter:
yaml
---
name: skill-name
description: "What it does. Keywords: term1, term2."
metadata:
  author: your-name
  version: "1.0.0"
---
Field order: 
name
→ 
description
→ 
license
→ 
compatibility
→ 
metadata
→ other fields
每个
SKILL.md
必须以YAML frontmatter开头：
yaml
---
name: skill-name
description: "What it does. Keywords: term1, term2."
metadata:
  author: your-name
  version: "1.0.0"
---
字段顺序： 
name
→ 
description
→ 
license
→ 
compatibility
→ 
metadata
→ 其他字段

Required Fields

必填字段

FieldConstraints
name1-64 chars, lowercase 
a-z0-9-
, no 
--
, no leading/trailing 
-
, must match folder name
description1-1024 chars (target: 80-150), describes what skill does + when to use it, include keywords
字段约束条件
name1-64字符，仅包含小写
a-z0-9-
，无连续
--
，首尾无
-
，必须与文件夹名称匹配
description1-1024字符（目标：80-150字符），描述Skill功能及适用场景，包含关键词

Optional Fields (Top Level)

顶层可选字段

FieldPurpose
licenseLicense name or reference to bundled LICENSE file
compatibilityEnvironment requirements (max 500 chars)
metadataObject for arbitrary key-value pairs (see below)
字段用途
license许可证名称或指向捆绑LICENSE文件的引用
compatibility环境要求（最多500字符）
metadata用于存储任意键值对的对象（见下文）

metadata Object (Common Fields)

metadata对象（常见字段）

FieldPurpose
authorAuthor name or organization
versionSkill version (semver format, e.g., "1.0.0")
argument-hintHint for autocomplete, e.g., 
[issue-number]
IMPORTANT: 
version
in 
metadata
is the skill version. If you reference external product docs, track that version separately (e.g., in README.md or metadata.json).
字段用途
author作者姓名或组织
versionSkill版本（语义化版本格式，例如："1.0.0"）
argument-hint自动补全提示，例如：
[issue-number]
重要提示：
metadata
中的
version
是Skill版本。如果引用外部产品文档，请单独跟踪该版本（例如在README.md或metadata.json中）。

Optional Fields (Claude Code / Advanced)

可选字段（Claude Code / 高级功能）

FieldPurpose
disable-model-invocation
true
= only user can invoke (via 
/name
). Default: 
false
user-invocable
false
= hidden from 
/
menu, only agent can load. Default: 
true
allowed-toolsSpace-delimited tools agent can use without asking, e.g., 
Read Grep Glob
modelSpecific model to use when skill is active
contextSet to 
fork
to run in a forked subagent context
agentSubagent type when 
context: fork
, e.g., 
Explore
, 
Plan
hooksHooks scoped to skill's lifecycle (see agent documentation)
字段用途
disable-model-invocation
true
= 仅用户可调用（通过
/name
）。默认值：
false
user-invocable
false
= 在
/
菜单中隐藏，仅Agent可加载。默认值：
true
allowed-toolsAgent无需询问即可使用的工具（空格分隔），例如：
Read Grep Glob
modelSkill激活时使用的特定模型
context设置为
fork
时，在分叉子Agent上下文中运行
agent当
context: fork
时的子Agent类型，例如：
Explore
, 
Plan
hooks作用于Skill生命周期的钩子（见Agent文档）

Invocation Control Matrix

调用控制矩阵

FrontmatterUser can invokeAgent can invokeNotes
(default)✅ Yes✅ YesDescription in context, loads when used
disable-model-invocation: true
✅ Yes❌ NoFor manual workflows with side effects
user-invocable: false
❌ No✅ YesBackground knowledge, not a command
Frontmatter配置用户可调用Agent可调用说明
（默认）✅ 是✅ 是上下文包含描述，使用时加载
disable-model-invocation: true
✅ 是❌ 否适用于有副作用的手动工作流
user-invocable: false
❌ 否✅ 是背景知识，非命令

Variable Substitutions

变量替换

Available placeholders in skill content:
VariableDescription
$ARGUMENTS
All arguments passed when invoking the skill
${CLAUDE_SESSION_ID}
Current session ID for logging or session-specific files
If 
$ARGUMENTS
is not in content, arguments are appended as 
ARGUMENTS: <value>
.
Example:
yaml
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.
Skill内容中可用的占位符：
变量描述
$ARGUMENTS
调用Skill时传递的所有参数
${CLAUDE_SESSION_ID}
当前会话ID，用于日志或会话特定文件
如果内容中未包含
$ARGUMENTS
，参数将以
ARGUMENTS: <value>
的形式追加。
示例：
yaml
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.

Dynamic Context Injection

动态上下文注入

Use 
!
command`` syntax to run shell commands before skill content is sent to the agent:
markdown
undefined
使用
!
command``语法可在Skill内容发送给Agent前执行Shell命令：
markdown
undefined

Pull request context

Pull request context

  • PR diff: !
    gh pr diff
  • Changed files: !
    gh pr diff --name-only
  • PR diff: !
    gh pr diff
  • Changed files: !
    gh pr diff --name-only

Your task

Your task

Review this pull request...

The command output replaces the placeholder, so the agent receives actual data.
Review this pull request...

命令输出将替换占位符，因此Agent会收到实际数据。

metadata.json (Optional)

metadata.json（可选）

For publishing or extended metadata, create 
metadata.json
:
json
{
  "version": "1.0.0",
  "organization": "Your Org",
  "date": "January 2026",
  "abstract": "Brief description of what this skill provides...",
  "references": ["https://docs.example.com", "https://github.com/org/repo"]
}
Fields:
  • version
    — Skill version (semver)
  • organization
    — Author or organization
  • date
    — Publication date
  • abstract
    — Extended description (can be longer than frontmatter)
  • references
    — List of source documentation URLs
如需发布或扩展元数据，创建
metadata.json
：
json
{
  "version": "1.0.0",
  "organization": "Your Org",
  "date": "January 2026",
  "abstract": "Brief description of what this skill provides...",
  "references": ["https://docs.example.com", "https://github.com/org/repo"]
}
字段：
  • version
    — Skill版本（语义化版本）
  • organization
    — 作者或组织
  • date
    — 发布日期
  • abstract
    — 扩展描述（可长于frontmatter中的描述）
  • references
    — 源文档URL列表

Name Validation Examples

名称验证示例

yaml
undefined
yaml
undefined

Valid

有效

name: pdf-processing name: data-analysis name: code-review
name: pdf-processing name: data-analysis name: code-review

Invalid

无效

name: PDF-Processing # uppercase not allowed name: -pdf # cannot start with hyphen name: pdf--processing # consecutive hyphens not allowed
undefined
name: PDF-Processing # 不允许大写 name: -pdf # 不能以连字符开头 name: pdf--processing # 不允许连续连字符
undefined

Description Rules

描述规则

Purpose: Tell the LLM what the skill does and when to activate it. Minimize tokens — just enough for activation decision.
Formula:
[Product] [core function]. Covers [2-3 key topics]. Keywords: [terms].
Constraints:
  • Target: 80-150 chars
  • Max: 300 chars
  • No marketing ("powerful", "comprehensive", "modern")
  • No filler ("this skill", "use this for", "helps with")
  • No redundant context (skip "for apps", "for developers")
Good examples:
yaml
description: "Turso SQLite database. Covers encryption, sync, agent patterns. Keywords: Turso, libSQL, SQLite."

description: "Base UI unstyled React components. Covers forms, menus, overlays. Keywords: @base-ui/react, render props."

description: "Inworld TTS API. Covers voice cloning, audio markups, timestamps. Keywords: Inworld, TTS, visemes."
Poor examples:
yaml
undefined
目的： 告知大语言模型（LLM）该Skill的功能及激活时机。尽量减少token数——仅需足够用于激活决策的内容。
公式：
[产品] [核心功能]。涵盖[2-3个关键主题]。关键词：[术语]。
约束条件：
  • 目标长度：80-150字符
  • 最大长度：300字符
  • 无营销用语（如"强大的"、"全面的"、"现代化的"）
  • 无冗余填充（如"本Skill"、"使用本Skill"、"有助于"）
  • 无多余上下文（省略"适用于应用"、"面向开发者"等）
优秀示例：
yaml
description: "Turso SQLite database. Covers encryption, sync, agent patterns. Keywords: Turso, libSQL, SQLite."

description: "Base UI unstyled React components. Covers forms, menus, overlays. Keywords: @base-ui/react, render props."

description: "Inworld TTS API. Covers voice cloning, audio markups, timestamps. Keywords: Inworld, TTS, visemes."
不佳示例：
yaml
undefined

Too vague

过于模糊

description: "Helps with PDFs."
description: "Helps with PDFs."

Too verbose

过于冗长

description: "Turso embedded SQLite database for modern apps and AI agents. Covers encryption, authorization, sync, partial sync, and agent database patterns."
description: "Turso embedded SQLite database for modern apps and AI agents. Covers encryption, authorization, sync, partial sync, and agent database patterns."

Marketing

营销用语

description: "A powerful solution for all your database needs."

**Keywords:** product name, package name, 3-5 terms max.
description: "A powerful solution for all your database needs."

**关键词：** 产品名称、包名称，最多3-5个术语。

How Skills Work (Progressive Disclosure)

Skill工作原理（渐进式披露）

  1. Discovery: Agent loads only 
    name
    + 
    description
    of each skill (~50-100 tokens)
  2. Activation: When task matches, agent reads full 
    SKILL.md
    into context
  3. Execution: Agent follows instructions, loads referenced files as needed
Key rule: Keep 
SKILL.md
under 500 lines. Move details to 
references/
.
  1. 发现阶段：Agent仅加载每个Skill的
    name
    + 
    description
    （约50-100个token）
  2. 激活阶段：当任务匹配时，Agent将完整的
    SKILL.md
    加载到上下文中
  3. 执行阶段：Agent遵循说明，按需加载引用文件
核心规则： 保持
SKILL.md
不超过500行。将细节内容移至
references/
目录。

Creating a New Skill

创建新Skill

Step 1: Scaffold

步骤1：搭建脚手架

bash
python scripts/init_skill.py <skill-name>
bash
python scripts/init_skill.py <skill-name>

Or specify custom directory:

或指定自定义目录：

python scripts/init_skill.py <skill-name> --skills-dir skills

Or manually create:
<skills-folder>/<skill-name>/ ├── SKILL.md ├── references/ # For documentation, guides └── assets/ # For templates, static files
undefined
python scripts/init_skill.py <skill-name> --skills-dir skills

或手动创建：
<skills-folder>/<skill-name>/ ├── SKILL.md ├── references/ # 用于存放文档、指南 └── assets/ # 用于存放模板、静态文件
undefined

Step 2: Write Frontmatter

步骤2：编写Frontmatter

yaml
---
name: <skill-name>
description: "[Purpose] + [Triggers/Keywords]"
---
yaml
---
name: <skill-name>
description: "[用途] + [触发条件/关键词]"
---

Step 3: Write Body

步骤3：编写正文

Recommended sections:
  • When to use (triggers, situations)
  • Quick navigation (router to references and assets)
  • Steps / Recipes / Checklists
  • Critical prohibitions
  • Links
推荐章节：
  • 适用场景（触发条件、应用情境）
  • 快速导航（指向参考文档和资源的链接）
  • 步骤/流程/检查清单
  • 关键禁忌
  • 链接

Step 4: Add References (documentation)

步骤4：添加参考文档（文档）

For each major topic, create 
references/<topic>.md
with:
  • Actionable takeaways (5-15 bullets)
  • Gotchas / prohibitions
  • Practical examples
针对每个主要主题，创建
references/<topic>.md
，包含：
  • 可操作要点（5-15个项目符号）
  • 注意事项/禁忌
  • 实用示例

Step 5: Add Assets (if needed)

步骤5：添加资源（如有需要）

For templates or static resources, create 
assets/<resource>
:
  • Document templates
  • Configuration templates
  • Schema files
如需模板或静态资源，创建
assets/<resource>
：
  • 文档模板
  • 配置模板
  • 模式文件

Step 6: Validate

步骤6：验证

bash
python scripts/quick_validate_skill.py <skill-path>
bash
python scripts/quick_validate_skill.py <skill-path>

Creating a Skill from Documentation

从文档创建Skill

When building a skill from external docs, use the autonomous ingestion workflow:
当基于外部文档构建Skill时，使用自主摄取工作流：

Phase 1: Scaffold

阶段1：搭建脚手架

  1. Create skill folder with 
    SKILL.md
    skeleton
  2. Create 
    plan.md
    for progress tracking
  3. Create 
    references/
    directory
  1. 创建包含
    SKILL.md
    框架的Skill文件夹
  2. 创建
    plan.md
    用于进度跟踪
  3. 创建
    references/
    目录

Phase 2: Build Queue

阶段2：构建任务队列

For each doc link:
  • Fetch the page
  • Extract internal doc links (avoid nav duplicates)
  • Prioritize: concepts → API → operations → troubleshooting
针对每个文档链接：
  • 获取页面内容
  • 提取内部文档链接（避免导航重复）
  • 优先级排序：概念 → API → 操作 → 故障排查

Phase 3: Ingest Loop

阶段3：摄取循环

For each page:
  1. Fetch one page
  2. Create 
    references/<topic>.md
    with actionable summary
  3. Update 
    plan.md
    checkbox
  4. Update 
    SKILL.md
    if it adds a useful recipe/rule
Do not ask user after each page — continue autonomously.
针对每个页面：
  1. 获取单个页面
  2. 创建
    references/<topic>.md
    ，包含可操作摘要
  3. 更新
    plan.md
    中的复选框
  4. 如果添加了有用的流程/规则，更新
    SKILL.md
请勿在每个页面后询问用户 —— 自主继续执行。

Phase 4: Finalize

阶段4：最终完善

  • Review 
    SKILL.md
    for completeness
  • Ensure practical recipes, not docs mirror
  • plan.md
    may be deleted manually after ingestion
  • 检查
    SKILL.md
    的完整性
  • 确保包含实用流程，而非文档镜像
  • 完成摄取后可手动删除
    plan.md

Critical Prohibitions

关键禁忌

  • Do NOT copy large verbatim chunks from vendor docs (summarize in own words)
  • Do NOT write skills in languages other than English
  • Do NOT include project-specific secrets, paths, or assumptions
  • Do NOT keep 
    SKILL.md
    over 500 lines
  • Do NOT skip 
    name
    validation (must match folder name)
  • Do NOT use poor descriptions that lack trigger keywords
  • Do NOT omit product version when creating skills from documentation
  • 请勿从供应商文档中复制大段原文（用自己的话总结）
  • 请勿使用英文以外的语言创作Skill
  • 请勿包含项目特定的密钥、路径或假设
  • 请勿让
    SKILL.md
    超过500行
  • 请勿跳过
    name
    验证（必须与文件夹名称匹配）
  • 请勿使用缺乏触发关键词的描述
  • 从文档创建Skill时，请勿遗漏产品版本

Version Tracking

版本跟踪

When creating or updating a skill from external documentation:
  1. Add 
    version
    field in frontmatter for product version:
    yaml
    ---
name: my-skill
description: "..."
version: "1.2.3"
---
  2. Optionally add 
    release_date
    if known:
    yaml
    ---
name: my-skill
description: "..."
version: "1.2.3"
release_date: "2025-01-21"
---
  3. Create 
    README.md
    with:
    • Skill overview (1-2 sentences)
    • Usage section (when to use)
    • Links section (standardized format)
README.md Links section format:
markdown
undefined
当基于外部文档创建或更新Skill时：
  1. 在frontmatter中添加
    version
    字段以记录产品版本：
    yaml
    ---
name: my-skill
description: "..."
version: "1.2.3"
---
  2. 如有需要，添加
    release_date
    字段：
    yaml
    ---
name: my-skill
description: "..."
version: "1.2.3"
release_date: "2025-01-21"
---
  3. 创建
    README.md
    ，包含：
    • Skill概述（1-2句话）
    • 使用部分（适用场景）
    • 链接部分（标准化格式）
README.md链接部分格式：
markdown
undefined

Links

Links


Include only applicable links. Order: Documentation → Changelog/Releases → GitHub → Package registry.

Example frontmatter:

```yaml
---
name: turso
description: "Turso embedded SQLite database..."
version: "0.4.0"
release_date: "2025-01-05"
---
This helps track when the skill was last updated and against which product version.

仅包含适用的链接。顺序：文档 → 变更日志/发布记录 → GitHub → 包注册表。

示例frontmatter：

```yaml
---
name: turso
description: "Turso embedded SQLite database..."
version: "0.4.0"
release_date: "2025-01-05"
---
这有助于跟踪Skill最后更新时间及对应的产品版本。

Validation Checklist

验证检查清单

  • name
    matches folder name
  • name
    is 1-64 chars, lowercase, no 
    --
  • description
    is 1-1024 chars, includes keywords
  • SKILL.md
    under 500 lines
  • Documentation in 
    references/
    , templates in 
    assets/
  • All text in English
  • name
    与文件夹名称匹配
  • name
    长度为1-64字符，小写，无连续
    --
  • description
    长度为1-1024字符，包含关键词
  • SKILL.md
    不超过500行
  • 文档存于
    references/
    ，模板存于
    assets/
  • 所有文本使用英文

Scripts

脚本

ScriptPurpose
init_skill.py
Scaffold new Agent Skill (agentskills.io)
init_copilot_asset.py
Scaffold Copilot-specific assets (instructions, agents)
quick_validate_skill.py
Validate skill structure
package_skill.py
Package skill into distributable zip
脚本用途
init_skill.py
搭建新Agent Skill脚手架（agentskills.io）
init_copilot_asset.py
搭建Copilot特定资源（说明、Agent）
quick_validate_skill.py
验证Skill结构
package_skill.py
将Skill打包为可分发的Zip文件

Links

链接