skill-creator

What this skill does

# skill-creator

> Creates new skills, either generic for the global catalog or specific to the current project.

**Triggers**: skill:create, create skill, new skill, generate skill

---

## Two modes of operation

### Mode `/skill-create <name>`

Creates a **new** skill that does not exist anywhere. Asks whether it is:

- **Generic** → goes to `~/.claude/skills/<name>/SKILL.md` (available in all projects)
- **Project-specific** → goes to `.claude/skills/<name>/SKILL.md` (only in this project)

> **EXCEPTION — `agent-config` repo**: this repo IS the source of `~/.claude/`. When working inside it:
>
> - "Generic" placement → write to `<repo>/skills/<name>/SKILL.md` (NOT `~/.claude/skills/`). `install.sh` deploys it.
> - "Project-specific" does NOT apply — the repo has no `.claude/` of its own; everything it owns is global.
> - NEVER write directly to `~/.claude/skills/` from this repo; the next `install.sh` overwrites it.

### Mode `/skill-add <name>`

Adds an **existing skill from the global catalog** to the current project. Copies or creates a reference.

---

## Process: /skill-create

### Step 1 — Gather information

**Context detection (run before presenting the placement prompt):**

```
is_claude_config = (
  file_exists("install.sh")
  AND (
    project root contains install.sh AND skills/_shared/
    OR basename(cwd) == "agent-config"
  )
)

has_project_context = (
  dir_exists(".claude")
)

is_tech_skill = name matches any of:
  react*, vue*, angular*, svelte*, next*, nuxt*, remix*,
  prisma*, drizzle*, sequelize*, typeorm*, mongoose*,
  zod*, yup*, valibot*,
  tailwind*, bootstrap*, chakra*,
  typescript*, javascript*, node*,
  python*, django*, fastapi*, flask*,
  rails*, laravel*, spring*,
  go-*, rust-*, kotlin*, swift*,
  zustand*, redux*, jotai*, mobx*, recoil*,
  react-native*, expo*,
  playwright*, vitest*, jest*, cypress*, storybook*

if is_tech_skill AND NOT is_claude_config:
  default_placement = "project-local"      → option 1
  rationale = "Tech-specific skills belong in the consuming project's
               .claude/skills/, not the global catalog. See CLAUDE.md rule."
elif is_tech_skill AND is_claude_config:
  default_placement = "_templates/tech/"   → option 3 (template-only)
  rationale = "In agent-config repo, tech skills go to skills/_templates/tech/
               so skill-creator can scaffold them into consumer projects."
elif has_project_context AND NOT is_claude_config:
  default_placement = "project-local"      → option 1
else:
  default_placement = "global"             → option 2
```

Ask the necessary questions to create a useful skill.
The placement prompt MUST reflect the detected default using the `[DEFAULT]` marker:

**When `default_placement = "project-local"`:**

```
Is this skill for this specific project or for all your projects?
  1. This project only → .claude/skills/  [DEFAULT]
  2. Global catalog    → ~/.claude/skills/

What does this skill do? (one-sentence description)

When should it activate? (what situations trigger its use?)

Are there specific code patterns, commands, or processes it should know about?
```

**When `default_placement = "global"`:**

```
Is this skill for this specific project or for all your projects?
  1. This project only → .claude/skills/
  2. Global catalog    → ~/.claude/skills/  [DEFAULT]

What does this skill do? (one-sentence description)

When should it activate? (what situations trigger its use?)

Are there specific code patterns, commands, or processes it should know about?
```

**When `default_placement = "_templates/tech/"` (tech skill inside agent-config repo):**

```
This is a tech-specific skill. It will NOT be deployed globally.
Save as a template at `skills/_templates/tech/<name>/` so `skill-creator`
can scaffold it into consumer projects on demand.

Confirm [Y/n]:
```

**When context is ambiguous (neither `has_project_context` nor `is_claude_config` matches):**

```
Is this skill for this specific project or for all your projects?
  1. This project only → .claude/skills/
  2. Global catalog    → ~/.claude/skills/

What does this skill do? (one-sentence description)

When should it activate? (what situations trigger its use?)

Are there specific code patterns, commands, or processes it should know about?
```

The user can accept the default by pressing Enter or selecting the numbered option.
If the user has already provided enough context in the command, skip obvious questions.

### Step 1b — Select format type

Before generating the skeleton, determine the skill's format type. Apply inference heuristics first,
then always show the result to the user for confirmation.

**Inference heuristics (apply in order; stop at first match):**

1. Skill name matches `*-antipatterns` or `*-anti-patterns` → infer `anti-pattern`
2. Skill name is a technology or library name (e.g., contains a known framework name, version suffix like `-19`, `-5`, `-4`, or a language name) → infer `reference`
3. Skill name starts with an action verb or matches SDD/meta-tool patterns (e.g., `sdd-*`, `project-*`, `memory-*`, `deploy-*`, `run-*`) → infer `procedural`
4. No match → no inference; ask the user directly

**Always present the format to the user before proceeding:**

```
Format type for this skill:
  Inferred: [procedural | reference | anti-pattern | none — please select]

Available formats (full contract: docs/format-types.md):
  1. procedural   — orchestrates a sequence of steps (SDD phases, meta-tools, workflows)
  2. reference    — provides patterns and examples for a technology or library
  3. anti-pattern — catalogs things to avoid (use for anti-pattern-focused skills)

Confirm [1/2/3] or press Enter to accept inferred:
```

If `docs/format-types.md` does not exist:

```
⚠️ WARNING: docs/format-types.md not found — skill-format-types change may not be applied.
Defaulting to procedural format.
```

Continue with `procedural` and do not block skill creation.

Store the confirmed format as `$SELECTED_FORMAT` for use in Step 3.

### Step 2 — If project skill: analyze the code

Read the existing project code to:

- Detect real patterns to document
- Find real examples to include in the skill
- Identify existing anti-patterns that must be avoided

### Step 3 — Generate the skill

Generate the skeleton based on `$SELECTED_FORMAT` from Step 1b. Each skeleton includes
`format: $SELECTED_FORMAT` in the YAML frontmatter and meets the section contract for that format.
Full contracts are defined in `docs/format-types.md`.

**If `$SELECTED_FORMAT` is `procedural`:**

```markdown
---
name: [skill-name]
description: >
  [one-line description]
format: procedural
---

# [skill-name]

> [One-line description. What it does and what it is for.]

**Triggers**: [word1, word2, situation1, situation2]

---

## Process

### Step 1 — [step name]

[Explain what this step does.]

### Step 2 — [step name]

[Explain what this step does.]

---

## Rules

- [constraint or invariant for this skill]
- [another constraint]
```

**If `$SELECTED_FORMAT` is `reference`:**

````markdown
---
name: [skill-name]
description: >
  [technology] patterns for [use case].
format: reference
---

# [skill-name]

> [technology] patterns for [use case].

**Triggers**: [technology name], [use-case keyword]

---

## Patterns

### [Pattern 1]: [Descriptive name]

[Explanation of the pattern]

```[language]
[real example code]
```
````

### [Pattern 2]: [Descriptive name]

[Explanation]

```[language]
[example code]
```

## Complete Examples

### [Scenario 1]

[Complete, executable code]

### [Scenario 2]

[Complete, executable code]

## Quick Reference

| Task          | Pattern / Command |
| ------------- | ----------------- |
| [common task] | [solution]        |

---

## Rules

- [constraint or anti-pattern to avoid]

````

**If `$SELECTED_FORMAT` is `anti-pattern`:**

```markdown
---
name: [skill-name]
description: >
  [technology] anti-patterns: [brief description].
format: anti-pattern
---

# [skill-name]

> [technology] anti-patt