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

skill-builder