skills-best-practices — 技能s-best-practices

技能s Best Practices

Comprehensive reference for building 代理 技能s that follow Anthropic's official 图形界面delines. 技能s are folders contAIning instructions, scripts, and resources that teach Claude how to handle specific tasks. They follow the 代理 技能s open standard.

Quick 启动

A minimal 技能 is a directory with a 技能.md file:

my-技能/ ├── 技能.md # Required - instructions with YAML frontmatter ├── references/ # Optional - detAIled docs loaded on demand ├── scripts/ # Optional - executable code └── as设置s/ # Optional - templates, fonts, icons

Minimal 技能.md:

---

name: my-技能-name description: What it does. Use when [specific triggers].

---

# My 技能 Name

[Instructions here]

Only name and description are required in frontmatter.

Core De签名 Principles 进度ive Disclosure (Most 导入ant)

技能s load in格式化ion in three levels to minimize 令牌 usage:

Level When Loaded 令牌 Cost Content 1: Metadata Always (启动up) ~100 令牌s name + description from frontmatter 2: Instructions When 技能 triggers <5k 令牌s 技能.md body 3: Resources As needed Effectively unlimited Bundled files, scripts

Keep 技能.md under 500 lines. Move detAIled docs to separate files and reference them:

Advanced features

• Form filling: See FORMS.md
• API reference: See reference.md

Claude reads referenced files only when the task requires them.

Composability

技能s work alongside other 技能s. Don't assume yours is the only one loaded.

Portability

技能s work across Claude.AI, Claude Code, API, and 代理 SDK without modification (if dependencies are avAIlable).

Writing the Description (Critical)

The description is the single most 导入ant field - it determines when your 技能 activates. Claude uses it to decide relevance from potentially 100+ avAIlable 技能s.

Rules Write in third person ("Processes files..." not "I help you process files...") Include WHAT it does + WHEN to use it Max 1024 characters, no XML angle brackets Be slightly "pushy" - Claude tends to undertrigger rather than overtrigger Include specific trigger phrases users would naturally say Good vs Bad # GOOD - specific, actionable, includes triggers description: 提取 text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document 提取ion.

# BAD - too vague description: Helps with documents.

# BAD - missing triggers description: 创建s sophisticated multi-page documentation 系统s.

More examples in references/description-图形界面de.md.

Frontmatter Reference Required Fields Field Rules name Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No "claude" or "anthropic" description Non-empty, max 1024 chars, no XML tags. WHAT + WHEN Optional Fields (Claude Code) Field Purpose argument-hint Autocomplete hint, e.g. [issue-number] disable-模型-invocation true = only user can invoke (for 部署, commit) user-invocable false = hidden from / menu (background knowledge) allowed-工具s 工具s allowed without 权限, e.g. Read, Grep, Glob 模型 Override 模型 for this 技能 effort Override effort level: low, medium, high, max 上下文 fork = 运行 in isolated sub代理 代理 Sub代理 type when 上下文: fork (e.g. Explore, Plan) paths Glob patterns limiting when 技能 activates Naming Conventions

Prefer ge运行d form for clarity:

processing-pdfs, analyzing-spreadsheets, managing-databases Also acceptable: pdf-processing, process-pdfs Avoid: 辅助工具, utils, 工具s, documents Structuring Instructions Be Concise

Claude is smart. Only 添加 上下文 it doesn't already have:

# GOOD (~50 令牌s)

提取 PDF text

Use pdfplumber for text 提取ion:

导入 pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].提取_text()
BAD (~150 令牌s)
提取 PDF text
PDF files are a common file 格式化 contAIning text and images. To 提取 text, you need a 库. There are many avAIlable...

设置 Degrees of Freedom
High freedom (text 图形界面delines): Multiple 应用roaches valid, 上下文-dependent
Medium freedom (pseudocode/templates): Preferred pattern exists, some variation OK
Low freedom (exact scripts): Operations are fragile, consistency critical
Recommended 技能.md Structure

markdown # 技能 Name

Quick 启动

[Minimal working example]

工作流 Decision Tree

[路由 to the right 应用roach based on task type]

DetAIled Instructions

[Step-by-step for each 工作流]

Examples

[Concrete 输入/输出 pAIrs]

Troubleshooting

[Common errors and fixes]

Reference Files

Keep references one level deep from 技能.md. Avoid nested chAIns:

# BAD: Too deep 技能.md -> advanced.md -> detAIls.md -> actual 信息

# GOOD: One level 技能.md -> advanced.md (contAIns the 信息 directly) 技能.md -> reference.md (contAIns the 信息 directly)

For reference files >100 lines, include a table of contents at the top.

Patterns