Skill Creator

Skill Creator

Research-enhanced skill creator that produces higher-quality skills than built-in defaults. Every design decision is grounded in how transformers process context.

Expert Vocabulary Payload

Prompt Engineering & Routing: expert vocabulary payload, dual-register description, vocabulary routing, distributional convergence, attention budget, distribution center, right altitude, retrieval anchor

Skill Architecture: progressive disclosure, context window management, U-shaped attention curve, YAML frontmatter, trigger surface, structural delineation, three-level loading (metadata / SKILL.md / references)

Behavioral Design: anti-pattern watchlist, detection signal, counter-example, imperative instruction, conditional branching, evaluation criteria

Quality & Testing: canonical example, few-shot learning, 15-year practitioner test, consultant-speak (banned), over-prompting, recency bias

Anti-Pattern Watchlist

These are anti-patterns in the skills this creator generates. Scan every generated SKILL.md against this list before delivery.

1. Generic Consultant-Speak in Vocabulary

Detection: Vocabulary payload contains terms like "best practices," "leverage," "synergy," "robust solution," "scalable framework," or "holistic approach." Apply the 15-year practitioner test: would a senior domain expert use this exact term with a peer? If not, it fails. Resolution: Replace every generic term with the precise domain term it vaguely gestures at. "Best practices for error handling" becomes "circuit breaker pattern (Nygard), exponential backoff, dead letter queue."

2. Over-Prompting

Detection: SKILL.md exceeds 500 lines. The same concept is stated 2-3 times in different words "for emphasis." Instructions contain hedging phrases ("you might want to consider," "it could be helpful to"). Resolution: State each instruction once, in imperative form. Remove hedging. Move heavy reference content to references/. Test with a minimal version first; add detail only where the model demonstrably fails.

3. Positive-Only Instructions

Detection: Zero "do NOT" or "avoid" guidance. No anti-pattern watchlist. The skill only describes what to do, never what not to do. Resolution: Add 5-10 domain-specific anti-patterns with named patterns, detection signals, and resolution steps. Without negative constraints, the model gravitates to the distribution center (the most generic, average output).

4. Single-Register Description

Detection: Description uses only formal terminology OR only casual language. Test: would the skill trigger if a user said "help me with [casual version of task]"? If not, the casual register is missing. Resolution: Rewrite description to include both expert terms (for routing to deep knowledge) and natural-language trigger scenarios (for reliable activation). Add explicit "even if they don't say [formal term]" phrases.

5. Edge-Case Stuffing

Detection: More than 15 specific edge-case rules. Long lists of "if X then Y" covering every scenario instead of demonstrating the pattern. Resolution: Replace with 3-5 diverse canonical examples that show the pattern. Include one hard case. Let the model generalize from examples rather than memorize rules. Anthropic's documented recommendation is 3-5 examples; LangChain found 3 examples roughly matched 9 in effectiveness on their benchmark (diminishing returns, not a hard ceiling).

6. Paragraph-Form Logic

Detection: Complex multi-step behavior described in prose paragraphs. No numbered steps, no IF/THEN conditions, no imperative verbs. Resolution: Refactor to imperative ordered steps with explicit conditions. "First check for anti-patterns, and if you find some you should probably address them" becomes "1. Scan input for anti-patterns. IF detected: apply Detect-Name-Explain-Resolve-Prevent. IF none: proceed to step 2."

7. Missing Examples

Detection: Zero input-to-output examples or BAD/GOOD pairs in the generated skill. The skill relies entirely on verbal instructions. Resolution: Add 3-5 diverse examples. Use BAD vs GOOD pairs for quality standards, input-to-output pairs for workflows. Place the most representative example last (recency bias gives it the strongest influence).

8. Over-Prescription for Current Models

Detection: The generated SKILL.md enumerates exhaustive rules, hedges every instruction, or reads like it was tuned for an older, weaker model — dense and enumerative even where the vocabulary and anti-pattern sections are lean. Resolution: State the goal, the boundaries, and the verification standard; let the model fill in competent defaults. Keep the description pushy (triggering is still the weak point) but keep the body lean. When migrating an existing skill to a newer model generation, test whether REMOVING instructions improves output before adding more.

9. Reasoning-Echo Instructions

Detection: Behavioral instructions tell the model to "show your chain of thought," "transcribe your reasoning process," or "explain your internal thinking step by step." Resolution: Replace with a request for a conclusion plus brief stated rationale (e.g., "state the tier and explain why in one sentence"). Manual CoT scaffolding is deprecated now that adaptive thinking handles this internally; on Claude Fable 5, instructing reasoning-echo can trigger the reasoning-extraction refusal classifier and fail the request outright.

Behavioral Instructions

Phase 1: Capture Intent

1. Identify what the skill should do, when it should trigger, and what output format is expected.
2. Identify the target audience: who triggers this skill, and what do they typically say?
3. IF the user's request is vague: ask 1-2 clarifying questions about domain, trigger scenarios, and expected output format. Do NOT proceed with a generic skill.

Phase 2: Research (Conditional)

4. IF unfamiliar domain: research the domain before drafting.
   • Use web search for domain terminology, frameworks, and named patterns.
   • Use codebase exploration if the skill is project-specific.
   • Identify 15-30 expert terms that pass the 15-year practitioner test.
   • Identify 5-10 domain anti-patterns with established names.

Phase 3: Draft SKILL.md

5. Write YAML frontmatter with dual-register description (~100 words, pushy, third person, states what AND when).

   • Include both expert terminology AND natural-language trigger scenarios.
   • Include explicit exclusions ("Do NOT use for...").
   • Be aggressive about triggering — current models undertrigger. Include synonyms, edge cases, and adjacent scenarios.
   • Platform limits (Claude Code, 2026): description max 1024 characters. Combined description + when_to_use truncates at 1,536 characters inside a skill-listing budget of ~1% of the context window — least-used skills get dropped first, so don't rely on padding. Use when_to_use to extend the triggering surface beyond the description proper.
   • Other useful frontmatter: disable-model-invocation, user-invocable, allowed-tools, model, effort, context: fork (runs the skill in a forked subagent), paths (glob-scoped activation). SKILL.md follows the Agent Skills open standard (agentskills.io) — custom slash commands have merged into skills.

6. Write Expert Vocabulary Payload (15-30 terms in 3-5 clusters).

   • Place BEFORE behavioral instructions. WHY: vocabulary primes the routing signal before execution begins.
   • Organize in sub-domain clusters of 3-8 terms each.
   • Include originator attribution for named frameworks: "circuit breaker (Nygard)" not just "circuit breaker."
   • Apply the 15-year practitioner test to every term. Remove any that fail.

7. Write Anti-Pattern Watchlist (5-10 named patterns).

   • Place BEFORE behavioral instructions. WHY: the model checks for problems before proceeding with normal execution.
   • Each pattern needs: name + origin, detection signal, resolution step.
   • Use established names where they exist: "Bikeshedding (Parkinson)" not "spending too much time on details."

8. Write Behavioral Instructions (imperative, ordered, conditional).

   • Use imperative verbs: "Scan," "Classify," "Output," not "You should try to."
   • Number every step. Use IF/THEN for branching logic.
   • Include WHY for non-obvious steps. WHY: the model can generalize principles to edge cases, but dead rules only cover literal matches.
   • Start with an anti-pattern scan step.
   • Keep the body lean. Claude 4.5+/5 follows brief instructions reliably — enumerating every case and hedging every step is tuned for older, weaker models and can degrade output on current ones. When migrating a skill, test whether removing instructions improves the result before adding any.
   • Never instruct the model to echo or transcribe its internal reasoning ("show your chain of thought," "explain your thinking step by step"). Ask for conclusions with brief stated rationale instead — on Claude Fable 5, reasoning-echo instructions can trigger the reasoning-extraction refusal classifier.

9. Write Output Format specification.

   • Define required fields, structure, and templates.
   • Use structured formats (YAML, tables, numbered lists) over prose.

10. Write 3-5 diverse Examples (BAD vs GOOD or input-to-output).

    • Cover different cases including at least one hard case.
    • Place the most representative example LAST. WHY: recency bias gives the final example the strongest influence on output.

11. Write "Questions This Skill Answers" section (8-15 natural-language queries).

    • Place at the END of the file. WHY: retrieval anchors benefit from end-of-context attention (U-shaped curve).
    • Use the exact phrasing a user would type, including casual and imprecise versions.
    • These function as retrieval anchors, self-documentation, and test cases simultaneously.

Phase 4: Reference Files (Conditional)

12. IF the skill requires heavy reference content (pattern libraries, extended examples, checklists, evaluation criteria):

    • Create files in references/ directory.
    • Keep each reference file under 300 lines.
    • Include clear guidance in SKILL.md on WHEN to read each reference file.

13. Keep SKILL.md under 500 lines total. IF over 500: move content to references/.

Phase 5: Library Metadata

14. Include library metadata in YAML frontmatter: name, version, domain tags, and compatibility notes.

Phase 6: Validate and Package

15. Scan the generated SKILL.md against the Anti-Pattern Watchlist above. Fix any violations.
16. IF subagents are available: test against 3-5 realistic prompts that a real user would type (casual, imprecise, no formal vocabulary).
17. Package the skill: validate structure, zip, and use present_files for installation.
18. Save to library/skills/ and update index.json.
19. Log creation to usage-log.jsonl.

Output Format

The primary output is a complete skill directory:

skill-name/
  SKILL.md              # Core instructions (<500 lines)
  references/           # Optional: heavy reference content
    [topic].md          # Each file <300 lines

SKILL.md internal structure (in this order):

1. YAML frontmatter (name, description, optional when_to_use/allowed-tools/model/effort/context/paths)
2. Expert Vocabulary Payload
3. Anti-Pattern Watchlist
4. Behavioral Instructions
5. Output Format
6. Examples (BAD vs GOOD)
7. Questions This Skill Answers

Examples

Example 1: BAD vs GOOD Description

BAD:

description: "Helps with code review."

Single-register. Not pushy. No expert terms. No trigger scenarios. No exclusions. This skill will almost never fire, and when it does, it will produce generic output.

GOOD:

description: |
  Performs structured code review using cyclomatic complexity analysis,
  connascence taxonomy, and conventional comments (Slaughter). Use when
  the user asks to review code, check a PR, look at their changes, or
  says "is this good?" about code -- even if they don't mention "review."
  Also triggers for diff review, merge request feedback, and pre-commit
  quality checks. Do NOT use for architecture decisions (use Decision
  Advisor) or writing new code (use Code Generator).

Dual-register. Pushy. Expert terms route to deep knowledge. Casual triggers ensure activation. Explicit exclusions prevent mis-triggers.

Example 2: BAD vs GOOD Vocabulary Payload

BAD:

## Domain Vocabulary
good code, clean code, readable, maintainable, well-tested

Generic terms that every blog post uses. Routes to introductory content. Fails the 15-year practitioner test: no senior engineer says "good code" to a peer.

GOOD:

## Domain Vocabulary
**Structural Analysis:** cyclomatic complexity (McCabe), cognitive
complexity (SonarSource), afferent/efferent coupling (Martin),
connascence (Page-Jones)

**Change Safety:** shotgun surgery (Fowler), feature envy, divergent
change, Liskov substitution violation

**Review Process:** conventional comments (Slaughter), ship/no-ship
framework, diff review vs design review, LGTM criteria

Precise terms organized in clusters. Named frameworks with originators. Routes to code review expertise, not generic advice. Every term passes the 15-year practitioner test.

Explicit Note on Packaging

This skill uses Anthropic's native .skill packaging mechanism (validate, zip, present_files) for delivery. It does NOT invoke the built-in skill creator. It replaces the built-in approach with research-backed principles from the Forge synthesis:

• Vocabulary routing (precise terminology steers output away from the generic training-distribution center — "embedding cluster activation" is a useful working model here, not a proven mechanism)
• U-shaped attention optimization (front-load vocabulary, back-load retrieval anchors; current frontier models show much smaller mid-context degradation than older benchmarks, but front/back positioning remains the safer default)
• Negative constraint steering (anti-patterns push past the distribution center)
• Progressive disclosure (three-level context loading; Claude Code truncates skill descriptions at 1,536 characters and retains only ~5K tokens per invoked skill after auto-compaction — front-load what matters)
• Few-shot superiority (3-5 diverse examples beat verbose instructions; diminishing returns beyond that)

Numeric ranges throughout this skill (15-30 vocabulary terms, 3-5 clusters, 5-10 anti-patterns, ~100-word description, 8-15 trigger questions) are Forge design standards for coverage without dilution, not measured thresholds. The <500-line SKILL.md ceiling IS verified Anthropic guidance. See ./references/skill-principles.md for the condensed research (with citations and bounds) and ./references/skill-template.md for an annotated gold-standard example.

Questions This Skill Answers

• "Create a skill for [domain/task]"
• "Build a skill that [does X]"
• "I want Claude to always [behavior] when [trigger]"
• "Make a reusable [domain] helper"
• "How do I create a good skill?"
• "Turn this workflow into a skill"
• "I need a skill for [task]"
• "Build me a custom [domain] assistant"
• "Create a prompt template for [task]"
• "Package this as a skill"
• "What makes a skill effective?"
• "My skill isn't triggering, how do I fix it?"
• "How should I structure a SKILL.md?"