AgentSkillsCN

skill-optimizer

在源代码中嵌入文档，包括文档注释、API 文档，以及内联文档。适用于编写代码文档、审查文档质量，或为代码添加示例时。

SKILL.md
--- frontmatter
name: skill-optimizer
description: |
  Analyzes and optimizes existing skills based on official best practices.
  Evaluates quality score, proposes structural improvements (Progressive Disclosure),
  description enhancement, and error handling additions.
  Use when: "improve skill", "optimize skill", "follow best practices",
  "review skill", "check SKILL.md", "analyze SKILL.md quality".
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
  - Task

Skill Optimizer

Analyze and optimize skills based on official Anthropic best practices.

Workflow

Phase 1: Skill Identification

With argument: Use specified skill path directly.

Without argument:

  1. •Scan skills/ directory for SKILL.md files
  2. •List found skills with names
  3. •Let user select via AskUserQuestion

Phase 2: Analysis

  1. •Read the target SKILL.md
  2. •Auto-detect language from content (Japanese/English)
  3. •Analyze from these perspectives:
CategoryPointsCheck Items
Frontmatter20YAML syntax, name/description required, security constraints
Description25Trigger phrases, specificity, includes both WHAT and WHEN
Structure20Progressive Disclosure, SKILL.md size (under 5000 words)
Content20Error handling, examples, clear instructions
Additional15references/ usage, MCP integration (if applicable)
  1. •

    Calculate quality score:

    • •A: 90-100 (Almost no issues)
    • •B: 75-89 (Minor improvements available)
    • •C: 60-74 (Improvement recommended)
    • •D: 40-59 (Needs improvement)
    • •F: 0-39 (Fundamental issues)
  2. •

    Organize improvement proposals by category

Reference files for analysis criteria:

  • •./references/yaml-frontmatter.md - YAML spec & constraints
  • •./references/description-writing.md - Description field best practices
  • •./references/progressive-disclosure.md - Structure design guide
  • •./references/patterns.md - Workflow patterns
  • •./references/mcp-integration.md - MCP integration guidance
  • •./references/troubleshooting.md - Common issues & solutions
  • •./references/checklist.md - Quality checklist

Phase 3: User Confirmation

Display analysis results and confirm with AskUserQuestion.

Output language: Follow detected skill language.

code
## Analysis Result

**Skill**: {skill_name}
**Quality Score**: {score} ({grade})

### Issues Found

#### Frontmatter ({points}/20)
- {issue_1}
- {issue_2}

#### Description ({points}/25)
- {issue_1}

...

### Improvement Proposals

Select categories to apply:
- [ ] Structure improvements (split to references/)
- [ ] Trigger improvements (description field)
- [ ] Error handling additions
- [ ] MCP integration improvements

Phase 4: Execution

For selected categories:

  1. •Maintain original style (writing style, terminology, tone)
  2. •Output in detected language
  3. •Overwrite original directory (git recovery possible)
  4. •Display updated score after execution

Edge Cases

CaseResponse
YAML errorPropose fix as "improvement"
Wrong filenamePropose rename as "improvement"
No improvement neededShow score only, report "no issues"
Mixed Japanese/EnglishDetect main language, unify output
Multiple language templatesOptimize each in respective language

Analysis Details

Frontmatter Checks (20 points)

  • • --- delimiters present
  • • name field exists and is kebab-case
  • • description field exists
  • • No XML tags (< >)
  • • No "claude" or "anthropic" prefix in name
  • • Valid YAML syntax

Description Checks (25 points)

  • • Includes WHAT (what the skill does)
  • • Includes WHEN (trigger conditions)
  • • Under 1024 characters
  • • Contains specific trigger phrases
  • • Not too vague ("Helps with projects" is bad)
  • • Mentions relevant file types if applicable

Structure Checks (20 points)

  • • SKILL.md under 5000 words
  • • Uses Progressive Disclosure (references/ for detailed docs)
  • • Critical instructions at top
  • • Uses clear headers (## Important, ## Critical)
  • • Bullet points and numbered lists for clarity

Content Checks (20 points)

  • • Error handling included
  • • Examples provided
  • • Instructions are specific and actionable
  • • References clearly linked
  • • No ambiguous language

Additional Checks (15 points)

  • • references/ used appropriately for large skills
  • • MCP tool names correct (if applicable)
  • • Validation steps included (if applicable)