AgentSkillsCN

am2rican5:skill-builder

按照 Anthropic 官方指南的最佳实践，自动验证并创建或更新 Claude Code 技能。依次梳理前言、说明、示例和故障排除部分，随后运行 validate-skill.sh 进行验证。适用于用户提到“创建技能”、“构建技能”、“新技能”、“更新此技能”、“改进此技能”、“修复此技能”或“验证我的技能”时使用。切勿用于创建智能体（应直接使用 agents/ 目录）或进行通用的 Claude Code 配置。

SKILL.md
--- frontmatter
name: am2rican5:skill-builder
description: Create or update Claude Code skills following Anthropic's official guide best practices, with automated validation. Walks through frontmatter, instructions, examples, and troubleshooting sections, then runs validate-skill.sh to verify. Use when user says "create a skill", "build a skill", "new skill", "update this skill", "improve this skill", "fix this skill", or "validate my skill". Do NOT use for creating agents (use agents/ directory directly) or for general Claude Code configuration.
disable-model-invocation: true
allowed-tools: "Read Write Edit Bash Glob Grep"
compatibility: Requires Claude Code with writable filesystem. Works with any skill directory.
argument-hint: [skill-name or path-to-existing-skill]
metadata:
  author: am2rican5
  version: 1.0.0
  category: workflow-automation

Skill Builder

Critical Rules

  • •NEVER overwrite an existing SKILL.md without reading it first and showing the user what will change
  • •ALWAYS run scripts/validate-skill.sh after creating or updating a skill — do not skip validation
  • •ALWAYS use kebab-case for skill names and folder names — no spaces, capitals, or underscores
  • •WHEN the description exceeds 1024 characters, shorten it — trim verbose phrases, not trigger coverage
  • •WHEN SKILL.md exceeds 5,000 words, move detailed content to references/ and link to it
  • •NEVER include README.md inside the skill folder — all documentation goes in SKILL.md or references/

Instructions

Step 1: Determine Create or Update

  1. •IF $ARGUMENTS contains a path to an existing SKILL.md → read it and go to Step 5 (Update)
  2. •IF $ARGUMENTS contains a skill name → use it as the new skill name
  3. •IF no arguments → ask the user: "What should this skill do? Describe the workflow in 1-2 sentences."

From the user's description, derive:

  • •A kebab-case skill name (e.g., "generate frontend designs" → frontend-design)
  • •2-3 concrete use cases the skill enables

Step 2: Write Frontmatter

Build the YAML frontmatter with ALL required and recommended fields:

yaml
---
name: <kebab-case-name>
description: <[What it does] + [When to use it] + [Key capabilities] + [Do NOT use for]>
disable-model-invocation: true
allowed-tools: "<space-separated tool list>"
compatibility: <environment requirements>
argument-hint: <expected arguments, if any>
metadata:
  author: <user or org name>
  version: 1.0.0
  category: <category>
---

Description formula — include ALL four parts:

  1. •What: One sentence on what the skill does
  2. •When: Trigger phrases users would say (include 4-6 variations)
  3. •Capabilities: Key things the skill enables
  4. •Negative triggers: "Do NOT use for..." to prevent over-triggering on adjacent use cases

Allowed-tools: Only list tools the skill actually needs. Common sets:

  • •Read-only analysis: "Read Glob Grep"
  • •File creation: "Read Write Bash Glob"
  • •File editing: "Read Edit Write Glob Grep"
  • •Full access: "Read Edit Write Bash Glob Grep"

Step 3: Write the Body

Write the skill body using this exact section structure:

## Critical Rules (5-8 rules)

  • •Format: NEVER/ALWAYS/WHEN X, DO Y — trigger-action only
  • •Put the most important safety rules first
  • •Include rules about validation, error handling, and user confirmation

## Instructions with numbered ### Step N: Title subsections

  • •Each step should be actionable and specific
  • •Include expected inputs, actions, and outputs
  • •Use code blocks for commands, file formats, and templates
  • •Link to references/ for detailed content that would bloat the main file

## Examples (at least 2)

  • •Format: "User says: ..." → brief summary of actions → "Result: ..."
  • •Cover the most common use case and one edge case

## Troubleshooting (at least 2 entries)

  • •Format: ### Problem title → **Cause:** → **Solution:**
  • •Cover the most likely failure modes

Step 4: Validate and Finalize

  1. •Write the SKILL.md file to skills/<name>/SKILL.md
  2. •Run validation: bash skills/skill-builder/scripts/validate-skill.sh skills/<name>/SKILL.md
  3. •IF validation fails → fix each reported issue and re-run
  4. •IF validation passes → show the user the final result

After validation passes, check progressive disclosure:

  • •IF word count > 3,000 → suggest extracting detailed sections to references/
  • •IF word count < 1,000 → the skill may be too thin — suggest adding more examples or troubleshooting

Step 5: Update an Existing Skill

WHEN updating instead of creating:

  1. •Read the existing SKILL.md
  2. •Run bash skills/skill-builder/scripts/validate-skill.sh <path-to-SKILL.md> to identify current issues
  3. •Present findings grouped by severity:
    • •Missing fields: frontmatter gaps (allowed-tools, compatibility, etc.)
    • •Missing sections: Critical Rules, Examples, Troubleshooting
    • •Structural issues: word count, description length, kebab-case
    • •Content quality: vague descriptions, missing negative triggers, no trigger phrases
  4. •For each issue, show the proposed fix with before/after
  5. •WAIT for user approval before applying changes
  6. •Apply approved changes
  7. •Re-run validation to confirm all issues resolved

Examples

Example 1: Creating a new skill

User says: "Create a skill for generating API documentation from OpenAPI specs"

Result: Created skills/api-doc-generator/SKILL.md with frontmatter (name, description with triggers and negative triggers, allowed-tools, compatibility), Critical Rules (5 rules), Instructions (4 steps: load spec, analyze endpoints, generate docs, validate output), 2 examples, 2 troubleshooting entries. Validation passes at 1,847 words.

Example 2: Updating an existing skill

User says: "/skill-builder skills/self-improve/SKILL.md"

Result: Read existing file, ran validation — found 2 issues (missing allowed-tools, missing compatibility). Proposed fixes with exact content. After approval, applied changes and re-validated: PASS at 628 words.

Troubleshooting

Validation fails on missing sections

Cause: The SKILL.md body is missing one of: Critical Rules, Instructions, Examples, Troubleshooting. Solution: The validator checks for ## .*<Section> headers (case-insensitive). Ensure each section uses a level-2 heading containing the exact word. For example, ## Critical Rules or ## Instructions — not ## Setup or ## Usage.

Description exceeds 1024 characters

Cause: Too many trigger phrases or verbose capability descriptions. Solution: Shorten the "What it does" part to one sentence. Use shorter trigger phrases. Keep the "Do NOT use for" clause to one sentence. Aim for 400-700 characters.

Word count over 5,000

Cause: Detailed reference content, long examples, or verbose protocol descriptions inline. Solution: Create a references/ subdirectory. Move the longest sections (usually examples or protocol specs) there. Replace inline content with a link: "See references/<file>.md for details."

Skill doesn't trigger on expected phrases

Cause: The description field is too vague or missing the user's actual vocabulary. Solution: Add more trigger phrase variations to the description. Include both formal ("orchestrate parallel agents") and casual ("run agents at the same time") phrasings. Test by asking Claude: "When would you use the <skill-name> skill?"