write-skills

name	write-skills
description	Creates new Claude Code custom skills (slash commands) by generating SKILL.md files with proper frontmatter and instructions. Use when the user wants to create, add, define, or scaffold a new skill or slash command.
argument-hint	["skill-name"]
allowed-tools	Read, Write, Bash(mkdir *), Glob, Grep

Workflow

1. Gather requirements — If $ARGUMENTS provides a skill name, use it. Otherwise ask:

   • Skill name (lowercase, hyphens only, max 64 chars, no reserved words "anthropic"/"claude")
   • What the skill should do
   • Whether it accepts arguments

2. Determine scope — Ask where to store it:

   • Project: .claude/skills/<name>/SKILL.md (default)
   • Personal: ~/.claude/skills/<name>/SKILL.md

3. Create the skill — mkdir -p the directory, then write SKILL.md.

4. Confirm — Report the file path and invocation command /<name>.

Authoring rules

Follow these when writing the SKILL.md content:

• Description: Write in third person. Include what it does AND when to use it. Max 1024 chars.
• Conciseness: Only include context Claude doesn't already know. Keep body under 500 lines.
• Naming: Prefer gerund form (processing-pdfs) or action form (process-pdfs). Avoid vague names like helper or utils.
• Degrees of freedom: Match specificity to task fragility — exact scripts for fragile operations, general guidance for flexible tasks.
• Progressive disclosure: Keep SKILL.md as an overview. Split detailed reference into separate files linked one level deep.
• No time-sensitive info: Avoid dates or version-dependent instructions.
• Consistent terminology: Pick one term per concept and use it throughout.

Frontmatter fields

---
name: required          # lowercase, hyphens, numbers only
description: required   # third-person, what + when
argument-hint: optional # e.g., [filename] [format]
allowed-tools: optional # e.g., Read, Grep, Bash(git *)
disable-model-invocation: optional # true to prevent auto-trigger
user-invocable: optional           # false to hide from / menu
model: optional         # override model
context: optional       # "fork" for subagent
agent: optional         # subagent type with context: fork
---

Substitutions

• $ARGUMENTS — all user arguments
• $1, $2 — positional arguments
• ${CLAUDE_SESSION_ID} — session ID
• ! followed by backtick-wrapped command — inline shell output