claudetools/.claude/skills/skill-creator/SKILL.md

---
name: skill-creator
description: |
  Create new Claude Code custom skills and slash commands. Use when the user wants to create a new skill,
  add a slash command, build a custom command, or set up a new automation. Guides through the process of
  defining the skill's purpose, triggers, and implementation, then generates the proper file structure.
---

# Skill Creator

You help the user create new Claude Code custom skills and slash commands.

## Two Types of Custom Extensions

### 1. Skills (`.claude/skills/{name}/SKILL.md`)
- Rich, multi-purpose capabilities with automatic invocation triggers
- Can include supporting files (scripts, references, checklists)
- Best for: complex behaviors, design patterns, validation workflows, integrations

### 2. Slash Commands (`.claude/commands/{name}.md`)
- Simple, user-invoked commands triggered by `/{name}`
- Single markdown file with instructions
- Best for: workflows the user explicitly triggers, task automation, shortcuts
- Can accept arguments via `$ARGUMENTS`

## Creation Process

### Step 1: Gather Requirements

Ask the user:
1. **What should this skill/command do?** (core purpose)
2. **Skill or command?** Help them decide:
   - If it should run automatically in response to certain actions -> **Skill**
   - If the user will invoke it explicitly with `/{name}` -> **Command**
   - If unsure, recommend based on the use case
3. **Name** - short, kebab-case identifier (e.g., `code-review`, `deploy-check`)
4. **When should it trigger?** (for skills: automatic triggers; for commands: typical usage)

### Step 2: Generate the Files

#### For Skills

Create `.claude/skills/{name}/SKILL.md`:

```markdown
---
name: {name}
description: |
  {Detailed description. This is used for discovery/matching, so be specific about
  when this skill should be invoked. Include trigger keywords and example scenarios.}
---

# {Skill Title}

{Clear instructions for what Claude should do when this skill is invoked.}

## When to Invoke

{List specific triggers - file types, actions, keywords that should activate this skill.}

## Workflow

{Step-by-step process the skill follows.}

## Guidelines

{Rules, patterns, and best practices to follow.}
```

#### For Commands

Create `.claude/commands/{name}.md`:

```markdown
---
description: {One-line description shown in command list}
---

# {Command Title}

{Instructions for what Claude should do when the user runs /{name}.}

## Arguments

If the command accepts arguments, reference them via `$ARGUMENTS`.

## Workflow

{Step-by-step process.}
```

### Step 3: Register and Validate

After creating the files:
1. Confirm the file was created in the correct location
2. Tell the user they can invoke it:
   - Skills: Explain the automatic triggers or manual invocation via `/skill-name`
   - Commands: Tell them to use `/{name}` or `/{name} arguments`
3. Remind them to update CLAUDE.md's Commands & Skills table if they want it documented there

## Mandatory: functional error logging

**Every skill MUST report genuine functional errors to `errorlog.md`** via the canonical
helper, so failures can be linted and fed back into skill improvements (CLAUDE.md core rule).
Bake this into the skill from the start:

- In each skill **script's failure branches** (API/auth failure, unexpected response,
  validation error, unexpected non-zero exit), call:
  ```bash
  bash "$ROOT/.claude/scripts/log-skill-error.sh" "<skill-name>" "<brief error>" --context "op=... http=..."
  ```
  It stamps date+machine, inserts in the standard `YYYY-MM-DD | MACHINE | skill | error`
  format, and soft-fails (never breaks the caller). Python skills shell out to the same helper.
- In the **SKILL.md**, add a line under workflow/guidelines: "On a functional error, log it via
  `log-skill-error.sh` before surfacing it."
- Do NOT log expected/handled conditions (no results, no unread, user-declined) — only real failures.

## Quality Checklist

Before finalizing, verify:
- [ ] Description is detailed enough for Claude to match it to relevant situations
- [ ] Instructions are clear and actionable (Claude will follow them literally)
- [ ] The skill/command doesn't duplicate an existing one
- [ ] File is in the correct location (`.claude/skills/` or `.claude/commands/`)
- [ ] Name uses kebab-case and is concise
- [ ] For skills with auto-triggers: triggers are specific enough to avoid false positives
- [ ] **Functional errors are logged** via `log-skill-error.sh` in the script's failure branches

## Tips for Good Skills/Commands

- **Be specific in descriptions** - vague descriptions lead to missed or false invocations
- **Include examples** in the instructions so Claude understands edge cases
- **Keep scope focused** - one skill per concern, don't create mega-skills
- **Test after creation** - have the user try invoking it to verify behavior
- **Reference existing patterns** - look at `.claude/skills/` and `.claude/commands/` for examples