Skills Creator

Skills Creator

Create new Claude Code plugin components (skills, agents, commands, full plugins) with proper conventions and real content. Marketplace-agnostic: read the target .claude-plugin/marketplace.json and CLAUDE.md for project-specific conventions (author, license, category taxonomy) before scaffolding.

Decision Flow

Determine what the user wants to create:

1. "new skill"   --> Skill Creation workflow
2. "new agent"   --> Agent Creation workflow
3. "new command" --> Command Creation workflow
4. "new plugin"  --> Full Plugin workflow (combines above)

If unclear, ask: "What do you want to create -- a skill, agent, command, or full plugin?"

Skill vs Agent Decision

Before gathering requirements, help the user decide the right component type.

Key question: "Does this need its own context/tools/isolation, or is it knowledge that any agent should access?"

• If it's knowledge, conventions, recipes --> Skill
• If it needs isolation, tool restrictions, parallel execution --> Agent
• If it's a domain with both knowledge and specialist work --> Skill + Agent(s)

See references/skills-vs-agents.md for the full decision table, real restructure examples, and anti-patterns.

Description Engineering

The description field is the single most important line in any skill or agent. It determines whether the component activates at all. Passive descriptions achieve ~50-77% activation; directive descriptions with negative constraints achieve 97-100%.

The High-Activation Template

<Domain> expert. ALWAYS invoke this skill when the user <trigger actions>.
Do not <alternative action> directly.
TRIGGER WHEN: <specific triggers, comma-separated>
DO NOT TRIGGER WHEN: <confusable case> (use <sibling-component> instead)

The last line is conditional: write it only when a confusable sibling exists to name. See "The DO NOT TRIGGER WHEN rule" below.

Examples

# BAD (50-77% activation) -- passive, suggestion-style
description: "Helps with Docker containerization tasks"

# GOOD (97-100% activation) -- directive with negative constraint
description: >
  Docker containerization expert. ALWAYS invoke this skill when the user
  asks about Docker, containers, Dockerfiles, or docker-compose.
  Do not run Docker commands or write Dockerfiles directly.
  TRIGGER WHEN: building containers, writing Dockerfiles, debugging Docker issues
  DO NOT TRIGGER WHEN: the task is Kubernetes orchestration (use k8s-operator instead)

Description Rules

1. Directive voice -- "ALWAYS invoke" not "Can be used for"
2. Negative constraint -- "Do not X directly" prevents Claude from bypassing the skill
3. Specific trigger phrases -- list the exact words/phrases that should activate it
4. Third person -- "Processes X when Y" not "I process X" or "You should use this"
5. Max 1024 characters -- hard limit per description
6. Always include TRIGGER WHEN -- it carries the vocabulary that routes to this component
7. Include DO NOT TRIGGER WHEN only when it names a sibling -- see the rule below
8. Never repeat a term in both the opening sentence and TRIGGER WHEN: the trigger line keeps it

The DO NOT TRIGGER WHEN rule

A DO NOT TRIGGER WHEN clause earns its context cost only by naming the component that should handle the case instead. It is a routing instruction, not a disclaimer.

# Useless: the logical inverse of TRIGGER WHEN, discriminates nothing, costs every session
DO NOT TRIGGER WHEN: the task is outside the specific scope of this component.

# Useful: routes the confusable case to a named sibling
DO NOT TRIGGER WHEN: the target is a Python codebase (use python-dead-code instead)

When no confusable sibling exists, omit the clause entirely.

Token Budget Awareness

A description is the only part of a component that sits in context in every session; the body loads only after invocation. Anything a description restates from its own body is pure cost, paid on every request that never invokes the component.

Each skill/agent costs ~100 tokens at idle (just name + description in system prompt). All descriptions combined share a 15,000 character budget by default. When total description text exceeds this limit, components may be silently dropped from the system prompt, which degrades routing for everything.

• Keep individual descriptions under 300 characters when possible
• List the trigger vocabulary, never the feature set: if the body covers it, the description must not enumerate it
• Strip marketing adjectives (Expert, Comprehensive, Adversarial, Master), mechanics sentences ("Report-only", "Spawned in parallel"), and toolchain version numbers that are not themselves triggers

Phase 1: Requirements Gathering

Before writing any files, gather enough context to produce real content.

For Skills

Ask (adapt based on what's already known):

1. What does this skill do? What problem does it solve?
2. What are the exact trigger phrases? (user actions, keywords, file types -- be specific: "when the user says X", "when working on Y files")
3. What should NOT trigger it? (adjacent domains that should be excluded)
4. Which plugin should it live in? (existing or new)
5. Does it need bundled resources? (scripts/, references/, assets/)
6. What's the degree of freedom? (rigid workflow vs flexible guidance)

For Agents

Ask (adapt based on what's already known):

1. What role does this agent fill? What task does it handle?
2. What tools does it need? (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task -- or all)
3. Which plugin should it live in?
4. What color fits its domain? See references/conventions.md for the palette and semantic guidance.

For Commands

Ask (adapt based on what's already known):

1. What does this command do when invoked?
2. What arguments does it expect?
3. Which plugin should it live in?

For Full Plugins

Ask (adapt based on what's already known):

1. What's the plugin's domain/purpose?
2. What components does it need? (agents, skills, commands)
3. What category? See references/conventions.md for valid categories.

Do not ask more than 3-4 questions per message. Start with the most important, follow up as needed.

Phase 2: Content Generation

Generate production-ready files with real content -- not [FILL] placeholders.

Skill Creation

1. Create directory: plugins/<plugin>/skills/<skill-name>/
2. Write SKILL.md following these rules:
   • Frontmatter: name (kebab-case, max 64 chars) and description (max 1024 chars)
   • Description format -- MUST follow the high-activation template:
     • Directive voice: "ALWAYS invoke this skill when..."
     • Negative constraint: "Do not X directly"
     • Always include a TRIGGER WHEN: line; add DO NOT TRIGGER WHEN: only when it names a sibling
     • Third person, specific trigger phrases
     • See "Description Engineering" section above
   • Optional frontmatter: context: fork (isolates in subagent), allowed-tools (restricts tool access), disable-model-invocation: true (prevents auto-triggering)
   • Body: under 500 lines, imperative tone, concise
   • Only add context Claude doesn't already have -- don't repeat what Claude already knows
   • Progressive disclosure: split into references/ if body exceeds ~300 lines
   • Can use !command syntax for dynamic context injection (shell commands that execute before content reaches Claude)
3. Create references/, scripts/, assets/ subdirs only if needed
4. Write any bundled resources

Agent Creation

1. Create file: plugins/<plugin>/agents/<agent-name>.md
2. Write with frontmatter and body following these rules:
   • Frontmatter fields: name, description (use YAML > for multiline), model: inherit, color, optionally tools
   • Description format -- same directive template as skills:
     • Always include a TRIGGER WHEN: line; add DO NOT TRIGGER WHEN: only when it names a sibling
     • Third person, specific triggers
     • Example: "Does X. TRIGGER WHEN: user needs Y. DO NOT TRIGGER WHEN: the work is Z (use sibling-agent instead)."
   • Body: terse keyword-list style, imperative tone, structured with markdown headers
   • Sections: # ROLE, # CAPABILITIES or # CORE CAPABILITIES, # CONVENTIONS, # OUTPUT FORMAT
   • Simple agents: 60-200 lines; complex agents: up to 800 lines
   • See references/conventions.md for color palette and style patterns

Command Creation

1. Create file: plugins/<plugin>/commands/<command-name>.md
2. Write with frontmatter: description, argument-hint
3. Body: step-by-step procedure, clear and actionable

Phase 3: Marketplace Registration

After files are created:

1. Read .claude-plugin/marketplace.json
2. Add paths to the plugin's agents, skills, or commands arrays
   • Agents: "./agents/<name>.md"
   • Skills: "./skills/<name>"
   • Commands: "./commands/<name>.md"
3. If new plugin: add full entry to plugins[] with all required fields (name, source, description, version 1.0.0, author, license, keywords, category, strict)
4. Bump plugin version (patch for new component in existing plugin)
5. Bump metadata.version (patch increment)

Phase 4: Validation

After registration:

1. Verify the file exists at the registered path
2. Verify frontmatter parses correctly
3. Verify naming conventions (kebab-case, filename matches name field)
4. Verify no em dash characters anywhere
5. Report what was created with file paths

Anti-patterns

Critical Rules

• All names: kebab-case
• Never use em dash -- use hyphen - or double hyphen --
• Default model for agents: inherit (agents follow the session model)
• Agent filename must match frontmatter name field
• Skill directory name must match frontmatter name field
• Always bump both plugin version AND metadata.version
• Stage marketplace.json with component files in same commit
• Write real content, never placeholder text