Creating Skills

创建技能

Guide for creating Claude Code skills following Anthropic's official best practices.

遵循Anthropic官方最佳实践的Claude Code技能创建指南。

Quick Start

快速开始

bash

undefined

bash

undefined

1. Create skill directory

mkdir -p ~/.claude/skills/<skill-name>/references

2. Create SKILL.md with frontmatter

cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'

name: <skill-name> description: <what it does>. Use when <trigger phrases>. <key capabilities>.

cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'

name: <skill-name> description: <what it does>. Use when <trigger phrases>. <key capabilities>.

<Skill Title>

<One-line description>

Quick Start

Core Workflow

<Step-by-step instructions>

Important Rules

<Critical constraints and requirements> EOF

3. Add helper scripts if value-add

4. Add reference files for detailed docs

undefined

undefined

SKILL.md Structure

SKILL.md 结构

Frontmatter (REQUIRED)

前置元数据（必填）

yaml

---
name: skill-name          # lowercase, hyphens, no spaces
description: <desc>       # CRITICAL for discovery (max 1024 chars)
---

yaml

---
name: skill-name          # lowercase, hyphens, no spaces
description: <desc>       # CRITICAL for discovery (max 1024 chars)
---

Description Formula

描述撰写公式

<What it does>. Use when <trigger phrases>. <Key capabilities>.

Example:

Creates GitHub Pull Requests with automated validation. Use when user wants
to create PR, open pull request, or merge feature. Validates tasks, runs
tests, generates Conventional Commits format.

Trigger phrases to include:

Action verbs: "create", "handle", "manage", "process"
User intent: "wants to", "needs to", "asks for"
Keywords users would say: "PR", "pull request", "review comments"

<What it does>. Use when <trigger phrases>. <Key capabilities>.

示例：

Creates GitHub Pull Requests with automated validation. Use when user wants
to create PR, open pull request, or merge feature. Validates tasks, runs
tests, generates Conventional Commits format.

需包含的触发短语：

动作动词: "create", "handle", "manage", "process"
用户意图: "wants to", "needs to", "asks for"
用户可能使用的关键词: "PR", "pull request", "review comments"

Body Sections (ORDER MATTERS)

正文章节（顺序重要）

Title -
```
# Skill Name
```
One-liner - Single sentence summary
Quick Start - Minimal steps (copy-paste ready)
Core Workflow - Numbered steps with code blocks
Helper Scripts (if any) - Table with purpose
Important Rules - Critical constraints (bold ALWAYS/NEVER)

标题 -
```
# Skill Name
```
一句话概述 - 单句总结
快速开始 - 最简步骤（可直接复制粘贴使用）
核心工作流 - 带代码块的分步说明
辅助脚本（如有）- 含用途说明的表格
重要规则 - 关键约束条件（用粗体 ALWAYS/NEVER 标记）

Naming Conventions

命名约定

Format Options

格式选项

Style	Example	When to Use
Gerund (verb-ing)	`processing-pdfs`	Action-focused
Noun phrase	`github-pr-creation`	Entity-focused
Prefixed group	`github-pr-*`	Related skills

风格	示例	使用场景
动名词（verb-ing）	`processing-pdfs`	以动作为核心
名词短语	`github-pr-creation`	以实体为核心
前缀分组	`github-pr-*`	相关技能组

Rules

规则

Lowercase only
Hyphens between words (no underscores)
No spaces
Descriptive but concise (2-4 words)

仅使用小写字母
单词间用连字符连接（不使用下划线）
无空格
描述性强且简洁（2-4个单词）

Token Budget

令牌预算

Component	Limit	Notes
SKILL.md body	< 500 lines	Split if approaching
Description	< 1024 chars	Quality over quantity
Quick Start	< 30 lines	Minimal viable example

If approaching 500 lines:

Move detailed examples to
```
references/examples.md
```
Move troubleshooting to
```
references/troubleshooting.md
```
Keep SKILL.md focused on workflow

组件	限制	说明
SKILL.md 正文	< 500行	接近限制时拆分内容
描述	< 1024字符	质量优先于长度
快速开始	< 30行	最简可行示例

如果接近500行限制：

将详细示例移至
```
references/examples.md
```
将故障排除内容移至
```
references/troubleshooting.md
```
保持SKILL.md聚焦于工作流

Helper Scripts Guidelines

辅助脚本指南

When to Create Scripts

何时创建脚本

DO create scripts for:

Complex logic (severity classification, commit analysis)
Multi-step processing with JSON output
Reusable utilities across invocations

DON'T create scripts for:

Single command wrappers (
```
gh api ...
```
)
Simple operations Claude can do inline
One-line bash commands

建议创建脚本的场景：

复杂逻辑（严重程度分类、提交分析）
生成JSON输出的多步骤处理
可跨调用复用的工具

不建议创建脚本的场景：

单命令包装器（
```
gh api ...
```
）
Claude可直接内联完成的简单操作
单行bash命令

Script Requirements

脚本要求

python

#!/usr/bin/env python3
"""Script description."""

import json
import sys

def main():
    # Read from stdin or args
    # Process data
    # Output JSON to stdout
    print(json.dumps(result))

if __name__ == "__main__":
    main()

Output JSON for structured data
Use stdin/stdout for piping
Include clear error messages
Keep focused on single responsibility

python

#!/usr/bin/env python3
"""Script description."""

import json
import sys

def main():
    # Read from stdin or args
    # Process data
    # Output JSON to stdout
    print(json.dumps(result))

if __name__ == "__main__":
    main()

输出采用JSON格式以实现结构化数据
使用标准输入/输出进行管道操作
包含清晰的错误提示信息
保持单一职责

Directory Structure

目录结构

~/.claude/skills/<skill-name>/
├── SKILL.md              # Main skill file (< 500 lines)
├── scripts/              # Optional helper scripts
│   └── helper.py         # Only if value-add
└── references/           # Optional detailed docs
    ├── examples.md       # Extended examples
    └── guide.md          # Deep-dive documentation

~/.claude/skills/<skill-name>/
├── SKILL.md              # Main skill file (< 500 lines)
├── scripts/              # Optional helper scripts
│   └── helper.py         # Only if value-add
└── references/           # Optional detailed docs
    ├── examples.md       # Extended examples
    └── guide.md          # Deep-dive documentation

Core Principles

核心原则

1. Claude is Already Smart

1. Claude 已具备强大能力

"Default assumption: Claude is already very smart. Only add context Claude doesn't already have."

Challenge each line:

Does Claude really need this explanation?
Can I assume Claude knows this?
Does this paragraph justify its token cost?

"默认假设：Claude已经非常智能。仅添加Claude尚不具备的上下文信息。"

对每一行内容提出质疑：

Claude真的需要这个解释吗？
我能否假设Claude已经知道这些内容？
这段内容是否值得消耗令牌？

2. Progressive Disclosure

2. 渐进式披露

SKILL.md (primary)
    ↓ references/ (when needed)
        ↓ external links (rarely)

Start minimal, expand as needed
Don't front-load all information
Let Claude discover details when relevant

SKILL.md（核心）
    ↓ references/（必要时）
        ↓ 外部链接（极少使用）

从最简内容开始，按需扩展
不要一次性加载所有信息
让Claude在相关时自行发现详细内容

3. User Confirmation for Critical Actions

3. 关键操作需用户确认

markdown

**ALWAYS** confirm before:
- Modifying files
- Running destructive commands
- Creating external resources (PRs, issues)

markdown

**ALWAYS** confirm before:
- Modifying files
- Running destructive commands
- Creating external resources (PRs, issues)

4. Structured Output

4. 结构化输出

Prefer JSON for script output:

bash

undefined

脚本输出优先使用JSON格式：

bash

undefined

Good: Structured, parseable

python3 script.py | jq '.result'

Bad: Unstructured text

python3 script.py | grep "Result:"

undefined

python3 script.py | grep "Result:"

undefined

Quality Checklist

质量检查清单

Before finalizing a skill:

Frontmatter: name + description present
Description: includes WHAT + WHEN triggers + capabilities
Naming: lowercase, hyphens, descriptive
Quick Start: copy-paste ready, < 30 lines
Line count: SKILL.md < 500 lines
Scripts: only value-add, no wrappers
Rules: critical constraints marked with bold
Test: skill triggers on expected phrases

在完成技能创建前：

前置元数据：包含名称和描述
描述：包含功能（WHAT）+ 触发场景（WHEN）+ 核心能力
命名：小写、连字符连接、描述性强
快速开始：可直接复制粘贴，少于30行
行数限制：SKILL.md少于500行
脚本：仅添加有实际价值的脚本，避免包装器
规则：关键约束条件用粗体标记
测试：技能可被预期短语触发

Anti-Patterns to Avoid

需避免的反模式

Anti-Pattern	Why Bad	Instead
Wrapper scripts	No value-add	Inline commands
Explaining basics	Claude already knows	Skip or brief
Multiple workflows	Confusing	One clear path
Verbose examples	Token waste	Minimal examples
Custom systems	Non-standard	Use official patterns

反模式	弊端	替代方案
包装器脚本	无实际价值	内联命令
基础内容解释	Claude已掌握相关知识	跳过或简要提及
多工作流	易混淆	提供清晰的单一路径
冗长示例	浪费令牌	最简示例
自定义系统	不符合标准	使用官方规范

Examples

示例

Good Description

优秀描述示例

Handles PR review comments with severity classification. Use when user
wants to resolve PR comments, handle review feedback, or fix review
comments. Fetches via GitHub CLI, classifies by severity, proposes fixes.

Handles PR review comments with severity classification. Use when user
wants to resolve PR comments, handle review feedback, or fix review
comments. Fetches via GitHub CLI, classifies by severity, proposes fixes.

Good Quick Start

优秀快速开始示例

bash

undefined

bash

undefined

1. Get PR number

PR=$(gh pr view --json number -q '.number')

2. Fetch and classify comments

gh api repos/{owner}/{repo}/pulls/$PR/comments |
python3 ~/.claude/skills/github-pr-review/scripts/classify_comments.py

3. Process each comment: show → propose → confirm → apply

4. Commit: git commit -m "fix(scope): address review - [desc]"

5. Reply and push

undefined

undefined

Good Important Rules

优秀重要规则示例

markdown

undefined

markdown

undefined

Important Rules

ALWAYS confirm before modifying files
ALWAYS verify ALL issues in multi-issue comments
NEVER skip user confirmation for file changes
Group related changes → single commit

undefined

ALWAYS confirm before modifying files
ALWAYS verify ALL issues in multi-issue comments
NEVER skip user confirmation for file changes
Group related changes → single commit

undefined

References

参考资料

```
references/official_best_practices.md
```
- Full Anthropic documentation
```
references/skill_examples.md
```
- Complete skill examples

```
references/official_best_practices.md
```
- 完整Anthropic文档
```
references/skill_examples.md
```
- 完整技能示例

creating-skills

Original

Translation

Creating Skills

创建技能

Quick Start

快速开始

1. Create skill directory

1. Create skill directory

2. Create SKILL.md with frontmatter

2. Create SKILL.md with frontmatter

cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'

name: <skill-name> description: <what it does>. Use when <trigger phrases>. <key capabilities>.

cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'

name: <skill-name> description: <what it does>. Use when <trigger phrases>. <key capabilities>.

<Skill Title>

<Skill Title>

Quick Start

Quick Start

Core Workflow

Core Workflow

Important Rules

Important Rules

3. Add helper scripts if value-add

3. Add helper scripts if value-add

4. Add reference files for detailed docs

4. Add reference files for detailed docs

SKILL.md Structure

SKILL.md 结构

Frontmatter (REQUIRED)

前置元数据（必填）

Description Formula

描述撰写公式

Body Sections (ORDER MATTERS)

正文章节（顺序重要）

Naming Conventions

命名约定

Format Options

格式选项

Rules

规则

Token Budget

令牌预算

Helper Scripts Guidelines

辅助脚本指南

When to Create Scripts

何时创建脚本

Script Requirements

脚本要求

Directory Structure

目录结构

Core Principles

核心原则

1. Claude is Already Smart

1. Claude 已具备强大能力

2. Progressive Disclosure

2. 渐进式披露

3. User Confirmation for Critical Actions

3. 关键操作需用户确认

4. Structured Output

4. 结构化输出

Good: Structured, parseable

Good: Structured, parseable

Bad: Unstructured text

Bad: Unstructured text

Quality Checklist

质量检查清单

Anti-Patterns to Avoid

需避免的反模式

Examples

示例

Good Description

优秀描述示例

Good Quick Start

优秀快速开始示例

1. Get PR number

1. Get PR number

2. Fetch and classify comments

2. Fetch and classify comments

3. Process each comment: show → propose → confirm → apply