AI_template/.claude/skills/create-skill/SKILL.md

name, description, disable-model-invocation, argument-hint

name	description	disable-model-invocation	argument-hint
create-skill	Create or improve a Claude Code skill — gathers requirements, selects agent type and frontmatter, generates a SKILL.md following best practices. Use when the user wants to create a skill, turn a workflow into a skill, improve an existing skill, or automate a repeating task as a slash command.	true	[skill-name or 'improve existing-skill-name']

Create or Improve Skill

Target: $ARGUMENTS

Context

Existing project skills: !ls .claude/skills/ 2>/dev/null

Detect Mode

• If $ARGUMENTS names an existing skill (check dirs above) → Improve mode
• Otherwise → Create mode

---

Create Mode

1. Capture intent

Check if the current conversation already contains a workflow the user wants to turn into a skill. If so, extract: tools used, sequence of steps, corrections made, input/output formats. Confirm with the user before proceeding.

If no prior context, gather requirements:

• What does this skill do? (one sentence)
• When should someone use it? (trigger phrases, contexts)
• What arguments does it expect? (file path, name, or none)
• Does it produce new files, modify existing files, or output analysis?
• Does it need live data at invocation time? (git diff, shell output)
• Scope: personal skill (all projects) or project-only?

2. Research

Read 2-3 existing skills closest in nature to the user's intent. Use them as examples of project conventions.

Read ${CLAUDE_SKILL_DIR}/references/frontmatter-spec.md for the complete frontmatter specification. Read ${CLAUDE_SKILL_DIR}/references/writing-guide.md for skill writing best practices.

3. Determine frontmatter

Select the appropriate agent based on domain:

Agent	Domain
frontend-architect	UI, components, accessibility
backend-architect	APIs, databases, server logic
code-reviewer	Code review, quality analysis
test-engineer	Tests, test strategy
security-auditor	Security, threat modeling
prompt-engineer	Prompts, LLM config
documentation-expert	Docs, ADRs
(omit + no fork)	Multi-file coordination, interactive workflows

Decide: context: fork for standalone deliverables (new file, analysis report). Omit for interactive workflows or multi-file coordination.

Always include disable-model-invocation: true (project convention).

4. Write the SKILL.md

Structure:

• H1 title — short action phrase
• One-liner referencing $ARGUMENTS
• Context section (optional) — ! backtick for live data
• Steps — numbered, imperative:
  • Step 1: read project context
  • Middle: core logic
  • Last: output or summary
• Output format (if structured) — markdown template in fenced block

5. Write file

Based on scope choice:

• Personal: ~/.claude/skills/$NAME/SKILL.md
• Project: .claude/skills/$NAME/SKILL.md

6. Verify and suggest tests

Read back the file and check:

• Valid YAML frontmatter
• Lowercase-hyphen name, no collision with existing skills
• Description with trigger contexts (slightly "pushy")
• Body: H1, steps, $ARGUMENTS reference
• Length appropriate (30-70 focused, up to 500 complex)

Propose 2-3 realistic test prompts including one edge case.

---

Improve Mode

1. Read the existing skill

Read the full SKILL.md and any bundled resources in its directory.

2. Diagnose issues

Read ${CLAUDE_SKILL_DIR}/references/writing-guide.md for evaluation criteria.

Analyze against:

• Description quality — is it "pushy" enough? Does it cover trigger contexts?
• Instruction clarity — does it explain WHY, not just rules?
• Structure — follows project conventions?
• Length — is it concise or bloated?
• Filler — does every sentence change agent behavior?

3. Propose improvements

Show a before/after diff of proposed changes with rationale for each change. Apply only after user approval.

4. Suggest test prompts

Propose 2-3 prompts to verify the improved skill works as expected.