skills-creator

Skills Creator

Create new ACP components with proper conventions and real content.

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: <exclusions>

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 not about containerization.

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. Include TRIGGER WHEN / DO NOT TRIGGER WHEN -- explicit activation boundaries

Token Budget Awareness

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, skills may be silently dropped from the system prompt.

• Keep individual descriptions under 300 characters when possible
• For the current marketplace (~39 plugins, ~80+ components), monitor total description size
• Prefer concise trigger lists over verbose explanations

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"
     • Include TRIGGER WHEN: and DO NOT TRIGGER WHEN: lines
     • 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: opus, color, optionally tools
   • Description format -- same directive template as skills:
     • Include TRIGGER WHEN: and DO NOT TRIGGER WHEN: lines
     • Third person, specific triggers
     • Example: "Expert X. TRIGGER WHEN: user needs Y. DO NOT TRIGGER WHEN: task is Z."
   • 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

Scenario	Wrong	Right
Writing descriptions	Passive: "Helps with Docker" (50% activation)	Directive: "ALWAYS invoke when user asks about Docker. Do not run Docker commands directly." (97%+ activation)
Description tone	"Can be used for...", "Use when..."	"ALWAYS invoke this skill when...", "Do not X directly"
Missing exclusions	No DO NOT TRIGGER WHEN clause	Always specify what should NOT trigger the component
Writing agent prompts	Verbose prose paragraphs	Terse keyword-list style
Skill body length	800+ lines in SKILL.md	Split into references/ at ~300 lines
Skill body content	Repeating what Claude already knows	Only add context Claude lacks; trust built-in knowledge
Creating resources	Empty placeholder dirs	Only create dirs that have files
Choosing a plugin	Always create a new one	Prefer adding to existing plugin if domain fits
Agent description	First/second person	Third person: "Processes X when Y"
Token budget	Long verbose descriptions on all components	Keep descriptions under 300 chars when possible; total budget is 15k chars

Critical Rules

• All names: kebab-case
• Never use em dash -- use hyphen - or double hyphen --
• Default model for agents: opus
• 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