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:

1. Agent Skills Specification (the open standard): https://agentskills.io/specification
2. Skill Authoring Best Practices (Anthropic): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
3. Claude Code Skills Documentation (Claude Code extensions): https://docs.claude.com/en/docs/claude-code/skills
4. 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:

1. Clarify → Define purpose, scope, activation keywords
2. Design → Plan structure, decide on progressive disclosure
3. Generate → Create SKILL.md with proper frontmatter and body
4. Validate → Check against spec and best practices
5. 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