Skill Builder

Purpose

Creates production-ready Agent Skills following the official specifications and best practices.

When I Activate

I automatically load when you mention:

• "build a skill" or "create a skill"

• "generate a skill" or "make a skill"

• "design a skill" or "new skill"

Authoritative References (Read These First)

Before creating any skill, read the current versions of these docs:

• Agent Skills Specification (the open standard): https://agentskills.io/specification

• Skill Authoring Best Practices (Anthropic): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

• Claude Code Skills Documentation (Claude Code extensions): https://docs.claude.com/en/docs/claude-code/skills

• Example Skills (reference implementations): https://github.com/anthropics/skills

These are the source of truth. If anything in this skill contradicts those docs, the official docs win.

What I Do

Create skills in 5 steps:

• Clarify → Define purpose, scope, activation keywords

• Design → Plan structure, decide on progressive disclosure

• Generate → Create SKILL.md with proper frontmatter and body

• Validate → Check against spec and best practices

• Test → Verify activation and behavior

Frontmatter (Agent Skills Spec)

Only two fields are required:

name: my-skill description: What this skill does and when to use it. Include specific keywords for discovery.

Optional fields: license , compatibility , metadata , allowed-tools .

Claude Code adds: disable-model-invocation , user-invocable , model , context , agent , hooks , argument-hint .

Do NOT use: version (use metadata.version ), auto_activates , priority_score , source_urls , evaluation_criteria , invokes , philosophy , maturity — none of these are recognized by any runtime.

Key Best Practices

From the official best practices:

Conciseness

• Claude is already smart. Only add context it doesn't have.

• Challenge every paragraph: "Does this justify its token cost?"

• SKILL.md body under 500 lines.

Description Quality

• Write in third person ("Processes Excel files", not "I help you")

• Include both what the skill does AND when to use it

• Include specific trigger keywords for discovery

• Max 1024 characters

Progressive Disclosure

• Metadata loaded at startup (name + description only)

• SKILL.md loaded when skill activates

• Supporting files loaded only when needed

• Keep references one level deep from SKILL.md

Degrees of Freedom

• High freedom: Multiple valid approaches, context-dependent

• Medium freedom: Preferred pattern exists, some variation OK

• Low freedom: Fragile operations, exact sequence required

No Time-Sensitive Content

• Never write "as of today", "recently added", "new in v3.0"

• Use an "old patterns" section for historical context if needed

Feedback Loops

• Run validator → fix errors → repeat

• Include verification steps for critical operations

Validation Checklist

✅ Frontmatter: name and description present and valid ✅ Name: Lowercase, hyphens only, 1-64 chars, matches directory name ✅ Description: 1-1024 chars, third person, includes trigger keywords ✅ Body: Under 500 lines ✅ References: One level deep from SKILL.md ✅ No stale content: No temporal references ✅ Consistent terminology: One term per concept throughout ✅ Tested: Works with at least 3 representative prompts

Supporting Files

• reference.md: Detailed patterns, architecture, validation rules

• examples.md: Skill creation workflows and examples