Back to Details

skill-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Writer

Skill 编写助手

This Skill helps you create well-structured Agent Skills for Claude Code that follow best practices and validation requirements.
本Skill可帮助你创建结构规范、符合最佳实践和验证要求的Claude Code Agent Skills。

When to use this Skill

何时使用本Skill

Use this Skill when:
  • Creating a new Agent Skill
  • Writing or updating SKILL.md files
  • Designing skill structure and frontmatter
  • Troubleshooting skill discovery issues
  • Converting existing prompts or workflows into Skills
在以下场景使用本Skill：
  • 创建新的Agent Skill
  • 编写或更新SKILL.md文件
  • 设计Skill结构与frontmatter
  • 排查Skill发现相关问题
  • 将现有提示词或工作流转换为Skills

Instructions

操作步骤

Step 1: Determine Skill scope

步骤1：确定Skill范围

First, understand what the Skill should do:
  1. Ask clarifying questions:
    • What specific capability should this Skill provide?
    • When should Claude use this Skill?
    • What tools or resources does it need?
    • Is this for personal use or team sharing?
  2. Keep it focused: One Skill = one capability
    • Good: "PDF form filling", "Excel data analysis"
    • Too broad: "Document processing", "Data tools"
首先明确本Skill的功能：
  1. 提出澄清问题：
    • 本Skill应提供哪些具体能力？
    • Claude应在何时使用本Skill？
    • 它需要哪些工具或资源？
    • 这是用于个人使用还是团队共享？
  2. 保持聚焦：一个Skill对应一项能力
    • 合理示例："PDF表单填写"、"Excel数据分析"
    • 范围过宽："文档处理"、"数据工具"

Step 2: Choose Skill location

步骤2：选择Skill存放位置

Determine where to create the Skill:
Personal Skills (
~/.claude/skills/
):
  • Individual workflows and preferences
  • Experimental Skills
  • Personal productivity tools
Project Skills (
.claude/skills/
):
  • Team workflows and conventions
  • Project-specific expertise
  • Shared utilities (committed to git)
确定Skill的创建位置：
个人Skills（
~/.claude/skills/
）：
  • 个人工作流与偏好设置
  • 实验性Skills
  • 个人生产力工具
项目Skills（
.claude/skills/
）：
  • 团队工作流与规范
  • 项目专属技能
  • 共享工具（提交至git）

Step 3: Create Skill structure

步骤3：创建Skill结构

Create the directory and files:
bash
undefined
创建目录与文件：
bash
undefined

Personal

Personal

mkdir -p ~/.claude/skills/skill-name
mkdir -p ~/.claude/skills/skill-name

Project

Project

mkdir -p .claude/skills/skill-name

For multi-file Skills:
skill-name/ ├── SKILL.md (required) ├── reference.md (optional) ├── examples.md (optional) ├── scripts/ │ └── helper.py (optional) └── templates/ └── template.txt (optional)
undefined
mkdir -p .claude/skills/skill-name

对于多文件Skill：
skill-name/ ├── SKILL.md (required) ├── reference.md (optional) ├── examples.md (optional) ├── scripts/ │ └── helper.py (optional) └── templates/ └── template.txt (optional)
undefined

Step 4: Write SKILL.md frontmatter

步骤4：编写SKILL.md前置元数据（frontmatter）

Create YAML frontmatter with required fields:
yaml
---
name: skill-name
description: Brief description of what this does and when to use it
---
Field requirements:
  • name:
    • Lowercase letters, numbers, hyphens only
    • Max 64 characters
    • Must match directory name
    • Good: 
      pdf-processor
      , 
      git-commit-helper
    • Bad: 
      PDF_Processor
      , 
      Git Commits!
  • description:
    • Max 1024 characters
    • Include BOTH what it does AND when to use it
    • Use specific trigger words users would say
    • Mention file types, operations, and context
Optional frontmatter fields:
  • allowed-tools: Restrict tool access (comma-separated list)
    yaml
    allowed-tools: Read, Grep, Glob
    Use for:
    • Read-only Skills
    • Security-sensitive workflows
    • Limited-scope operations
创建包含必填字段的YAML前置元数据：
yaml
---
name: skill-name
description: Brief description of what this does and when to use it
---
字段要求：
  • name：
    • 仅允许小写字母、数字、连字符
    • 最多64个字符
    • 必须与目录名称一致
    • 合理示例：
      pdf-processor
      , 
      git-commit-helper
    • 错误示例：
      PDF_Processor
      , 
      Git Commits!
  • description：
    • 最多1024个字符
    • 需同时包含功能说明与使用场景
    • 使用用户可能提及的特定触发词
    • 提及文件类型、操作与上下文
可选前置元数字段：
  • allowed-tools：限制工具访问权限（逗号分隔列表）
    yaml
    allowed-tools: Read, Grep, Glob
    适用场景：
    • 只读Skills
    • 安全敏感型工作流
    • 有限范围的操作

Step 5: Write effective descriptions

步骤5：编写有效的描述信息

The description is critical for Claude to discover your Skill.
Formula: 
[What it does] + [When to use it] + [Key triggers]
Examples:
✅ Good:
yaml
description: Extract 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 extraction.
✅ Good:
yaml
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
❌ Too vague:
yaml
description: Helps with documents
description: For data analysis
Tips:
  • Include specific file extensions (.pdf, .xlsx, .json)
  • Mention common user phrases ("analyze", "extract", "generate")
  • List concrete operations (not generic verbs)
  • Add context clues ("Use when...", "For...")
描述信息对Claude发现你的Skill至关重要。
公式：
[功能说明] + [使用场景] + [关键触发词]
示例：
✅ 合理示例：
yaml
description: Extract 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 extraction.
✅ 合理示例：
yaml
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
❌ 过于模糊：
yaml
description: Helps with documents
description: For data analysis
技巧：
  • 包含特定文件扩展名（.pdf, .xlsx, .json）
  • 提及常见用户用语（"分析"、"提取"、"生成"）
  • 列出具体操作（而非通用动词）
  • 添加上下文提示（"当...时使用"、"用于..."）

Step 6: Structure the Skill content

步骤6：构建Skill内容结构

Use clear Markdown sections:
markdown
undefined
使用清晰的Markdown章节：
markdown
undefined

Skill Name

Skill Name

Brief overview of what this Skill does.
Brief overview of what this Skill does.

Quick start

Quick start

Provide a simple example to get started immediately.
Provide a simple example to get started immediately.

Instructions

Instructions

Step-by-step guidance for Claude:
  1. First step with clear action
  2. Second step with expected outcome
  3. Handle edge cases
Step-by-step guidance for Claude:
  1. First step with clear action
  2. Second step with expected outcome
  3. Handle edge cases

Examples

Examples

Show concrete usage examples with code or commands.
Show concrete usage examples with code or commands.

Best practices

Best practices

  • Key conventions to follow
  • Common pitfalls to avoid
  • When to use vs. not use
  • Key conventions to follow
  • Common pitfalls to avoid
  • When to use vs. not use

Requirements

Requirements

List any dependencies or prerequisites:
bash
pip install package-name
List any dependencies or prerequisites:
bash
pip install package-name

Advanced usage

Advanced usage

For complex scenarios, see reference.md.
undefined
For complex scenarios, see reference.md.
undefined

Step 7: Add supporting files (optional)

步骤7：添加支持文件（可选）

Create additional files for progressive disclosure:
reference.md: Detailed API docs, advanced options examples.md: Extended examples and use cases scripts/: Helper scripts and utilities templates/: File templates or boilerplate
Reference them from SKILL.md:
markdown
For advanced usage, see [reference.md](reference.md).

Run the helper script:
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`
创建额外文件以实现渐进式信息披露：
reference.md：详细API文档、高级选项 examples.md：扩展示例与使用场景 scripts/：辅助脚本与工具 templates/：文件模板或样板代码
在SKILL.md中引用这些文件：
markdown
For advanced usage, see [reference.md](reference.md).

Run the helper script:
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`

Step 8: Validate the Skill

步骤8：验证Skill

Check these requirements:
✅ File structure:
  • SKILL.md exists in correct location
  • Directory name matches frontmatter 
    name
✅ YAML frontmatter:
  • Opening 
    ---
    on line 1
  • Closing 
    ---
    before content
  • Valid YAML (no tabs, correct indentation)
  • name
    follows naming rules
  • description
    is specific and < 1024 chars
✅ Content quality:
  • Clear instructions for Claude
  • Concrete examples provided
  • Edge cases handled
  • Dependencies listed (if any)
✅ Testing:
  • Description matches user questions
  • Skill activates on relevant queries
  • Instructions are clear and actionable
检查以下要求：
✅ 文件结构：
  • SKILL.md存在于正确位置
  • 目录名称与前置元数据中的
    name
    一致
✅ YAML前置元数据：
  • 第一行是开头的
    ---
  • 内容前有关闭的
    ---
  • 有效的YAML语法（无制表符，缩进正确）
  • name
    符合命名规则
  • description
    具体且长度小于1024字符
✅ 内容质量：
  • 为Claude提供清晰的操作说明
  • 提供具体示例
  • 处理边缘情况
  • 列出依赖项（如有）
✅ 测试：
  • 描述与用户问题匹配
  • Skill在相关查询时激活
  • 操作说明清晰且可执行

Step 9: Test the Skill

步骤9：测试Skill

  1. Restart Claude Code (if running) to load the Skill
  2. Ask relevant questions that match the description:
    Can you help me extract text from this PDF?
  3. Verify activation: Claude should use the Skill automatically
  4. Check behavior: Confirm Claude follows the instructions correctly
  1. 重启Claude Code（如正在运行）以加载Skill
  2. 提出相关问题，匹配描述信息：
    Can you help me extract text from this PDF?
  3. 验证激活状态：Claude应自动使用本Skill
  4. 检查行为：确认Claude正确遵循操作说明

Step 10: Debug if needed

步骤10：必要时进行调试

If Claude doesn't use the Skill:
  1. Make description more specific:
    • Add trigger words
    • Include file types
    • Mention common user phrases
  2. Check file location:
    bash
    ls ~/.claude/skills/skill-name/SKILL.md
ls .claude/skills/skill-name/SKILL.md
  3. Validate YAML:
    bash
    cat SKILL.md | head -n 10
  4. Run debug mode:
    bash
    claude --debug
如果Claude未使用本Skill：
  1. 让描述更具体：
    • 添加触发词
    • 包含文件类型
    • 提及常见用户用语
  2. 检查文件位置：
    bash
    ls ~/.claude/skills/skill-name/SKILL.md
ls .claude/skills/skill-name/SKILL.md
  3. 验证YAML语法：
    bash
    cat SKILL.md | head -n 10
  4. 运行调试模式：
    bash
    claude --debug

Common patterns

常见模式

Read-only Skill

只读Skill

yaml
---
name: code-reader
description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation.
allowed-tools: Read, Grep, Glob
---
yaml
---
name: code-reader
description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation.
allowed-tools: Read, Grep, Glob
---

Script-based Skill

基于脚本的Skill

yaml
---
name: data-processor
description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets.
---
yaml
---
name: data-processor
description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets.
---

Data Processor

Data Processor

Instructions

Instructions

  1. Use the processing script: ```bash python scripts/process.py input.csv --output results.json ```
  2. Validate output with: ```bash python scripts/validate.py results.json ```
undefined
  1. Use the processing script: ```bash python scripts/process.py input.csv --output results.json ```
  2. Validate output with: ```bash python scripts/validate.py results.json ```
undefined

Multi-file Skill with progressive disclosure

多文件渐进式披露Skill

yaml
---
name: api-designer
description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture.
---
yaml
---
name: api-designer
description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture.
---

API Designer

API Designer

Quick start: See examples.md
Detailed reference: See reference.md
Quick start: See examples.md
Detailed reference: See reference.md

Instructions

Instructions

  1. Gather requirements
  2. Design endpoints (see examples.md)
  3. Document with OpenAPI spec
  4. Review against best practices (see reference.md)
undefined
  1. Gather requirements
  2. Design endpoints (see examples.md)
  3. Document with OpenAPI spec
  4. Review against best practices (see reference.md)
undefined

Best practices for Skill authors

Skill作者最佳实践

  1. One Skill, one purpose: Don't create mega-Skills
  2. Specific descriptions: Include trigger words users will say
  3. Clear instructions: Write for Claude, not humans
  4. Concrete examples: Show real code, not pseudocode
  5. List dependencies: Mention required packages in description
  6. Test with teammates: Verify activation and clarity
  7. Version your Skills: Document changes in content
  8. Use progressive disclosure: Put advanced details in separate files
  1. 一Skill一功能：不要创建全能型Skill
  2. 具体的描述：包含用户可能使用的触发词
  3. 清晰的操作说明：为Claude编写，而非人类
  4. 具体的示例：展示真实代码，而非伪代码
  5. 列出依赖项：在描述中提及所需包
  6. 与团队成员测试：验证激活状态与清晰度
  7. 为Skills版本化：在内容中记录变更
  8. 使用渐进式披露：将高级细节放在单独文件中

Validation checklist

验证清单

Before finalizing a Skill, verify:
  • Name is lowercase, hyphens only, max 64 chars
  • Description is specific and < 1024 chars
  • Description includes "what" and "when"
  • YAML frontmatter is valid
  • Instructions are step-by-step
  • Examples are concrete and realistic
  • Dependencies are documented
  • File paths use forward slashes
  • Skill activates on relevant queries
  • Claude follows instructions correctly
在最终确定Skill前，验证以下内容：
  • 名称为小写字母，仅含连字符，最多64字符
  • 描述具体且长度小于1024字符
  • 描述包含"功能"与"场景"
  • YAML前置元数据有效
  • 操作说明分步清晰
  • 示例具体且真实
  • 依赖项已记录
  • 文件路径使用正斜杠
  • Skill在相关查询时激活
  • Claude正确遵循操作说明

Troubleshooting

故障排除

Skill doesn't activate:
  • Make description more specific with trigger words
  • Include file types and operations in description
  • Add "Use when..." clause with user phrases
Multiple Skills conflict:
  • Make descriptions more distinct
  • Use different trigger words
  • Narrow the scope of each Skill
Skill has errors:
  • Check YAML syntax (no tabs, proper indentation)
  • Verify file paths (use forward slashes)
  • Ensure scripts have execute permissions
  • List all dependencies
Skill未激活：
  • 在描述中添加更具体的触发词
  • 在描述中包含文件类型与操作
  • 添加包含用户用语的"当...时使用"条款
多个Skill冲突：
  • 让描述更具区分度
  • 使用不同的触发词
  • 缩小每个Skill的范围
Skill存在错误：
  • 检查YAML语法（无制表符，缩进正确）
  • 验证文件路径（使用正斜杠）
  • 确保脚本具有执行权限
  • 列出所有依赖项

Examples

示例

See the documentation for complete examples:
  • Simple single-file Skill (commit-helper)
  • Skill with tool permissions (code-reviewer)
  • Multi-file Skill (pdf-processing)
查看文档获取完整示例：
  • 简单单文件Skill（commit-helper）
  • 带工具权限的Skill（code-reviewer）
  • 多文件Skill（pdf-processing）

Output format

输出格式

When creating a Skill, I will:
  1. Ask clarifying questions about scope and requirements
  2. Suggest a Skill name and location
  3. Create the SKILL.md file with proper frontmatter
  4. Include clear instructions and examples
  5. Add supporting files if needed
  6. Provide testing instructions
  7. Validate against all requirements
The result will be a complete, working Skill that follows all best practices and validation rules.
当创建Skill时，我会：
  1. 询问关于范围与需求的澄清问题
  2. 建议Skill名称与存放位置
  3. 创建包含正确前置元数据的SKILL.md文件
  4. 包含清晰的操作说明与示例
  5. 必要时添加支持文件
  6. 提供测试说明
  7. 根据所有要求进行验证
最终结果将是一个完整、可运行的Skill，符合所有最佳实践与验证规则。