Skill Builder
Build new Claude Code skills that capture procedural knowledge.
Autonomy Model
Create then inform: When recognizing skill-worthy knowledge, create the skill proactively, then inform the user what was created and why. Don't ask permission first.
When to Invoke (Proactively)
- Successful novel solution - Just solved something in a way worth repeating
- Repeated pattern - Noticed doing the same thing multiple times
- Institutional knowledge - Learning domain-specific rules that should persist
- User workflow - User demonstrates a process they want automated
- Research findings - Discovered best practices worth preserving
Quality Gates (Pre-Extraction)
Before creating a skill, verify ALL gates pass:
| Gate | Question | Fail Criteria |
|---|---|---|
| REUSABLE | Applies beyond this instance? | One-off solution |
| NON-TRIVIAL | Required discovery, not docs lookup? | Just followed documentation |
| SPECIFIC | Clear trigger conditions defined? | Vague "sometimes useful" |
| VERIFIED | Solution confirmed working? | Theoretical, untested |
If ANY gate fails → Stop. Not skill-worthy.
Skill Creation Workflow
0. Research Best Practices
Before extracting, search for current patterns:
# Use Gemini CLI for web-grounded research
gemini "[technology] [feature] best practices 2026"
gemini "[technology] [problem type] official recommendations"Why: Don't just codify what you did. Incorporate current best practices. Skip if: Pattern is project-specific internal convention.
0.5. Classify Skill Type
Before creating, determine if foundational or workflow:
| Type | Characteristics | Frontmatter | Action |
|---|---|---|---|
| Foundational | Universal patterns, applies broadly, no explicit trigger needed | user-invocable: false | Add compressed summary to CLAUDE.md |
| Workflow | Explicit trigger, action-oriented, user/model invokes | (default) | Skill only |
If Foundational:
- Write skill as normal with
user-invocable: false - Create 20-30 line compressed summary extracting core principles
- Add summary to CLAUDE.md "Passive Knowledge Index" section
- Add skill to Skills Index (pipe-delimited format)
- Inform user: "Added to passive context — no invocation needed"
If Workflow:
- Write skill as normal (default is invocable)
- No CLAUDE.md changes needed
- Inform user of trigger terms
Foundational indicators:
- Would benefit all code, not specific triggers
- Patterns that should "always be on"
- Language-agnostic principles
- Universal conventions (naming, testing, docs)
Workflow indicators:
- Explicit action verb (audit, configure, check, fix)
- Specific domain (stripe, posthog, lightning)
- User would say "/skill-name" to invoke
1. Identify the Knowledge
- What problem does this solve?
- What trigger terms would activate it?
- Is it cross-project or project-specific?
2. Draft Structure
Reference references/structure-guide.md for ideal anatomy.
3. Write Description
Reference references/description-patterns.md for trigger-rich descriptions (~100 words, explicit trigger terms).
4. Validate
Run scripts/validate_skill.py <skill-path> to check structure and frontmatter.
5. Inform User
After creating, tell user:
- What skill was created and why
- What triggers will activate it
- How to test it works
Progressive Disclosure
Keep SKILL.md lean (<100 lines). Put detailed specs in references/:
- Detailed examples →
references/examples.md - Edge cases →
references/edge-cases.md - Anti-patterns →
references/anti-patterns.md
Code Opportunities
If skill involves deterministic operations (validation, parsing, extraction), create scripts/ with executable code rather than prose instructions. Scripts:
- Run without loading into context
- Must be executable (
chmod +x) - Should handle errors gracefully
Skill Locations
- Personal:
~/.claude/skills/- Available across all projects - Project:
.claude/skills/- Shared with team via git
Template
Use templates/SKILL-TEMPLATE.md as starting point for new skills.