Skill Creator

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

---

Mode /skill-create <name>

Creates a skill. The placement is decided by context (see Process below) — a new generic skill, a project-specific one, or a tech template. 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.

---

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

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

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

# [skill-name]

> [technology] anti-patterns: [brief description].

**Triggers**: [technology name] antipatterns, code review, refactoring

---

## Anti-patterns

### ❌ [Anti-pattern 1]: [Descriptive name]

**Why it is problematic**: [explanation]

// ❌ Bad [bad code] ````

```[language] // ✅ Good [corrected code]

### ❌ [Anti-pattern 2]: [Descriptive name]

**Why it is problematic**: [explanation]

---

## Rules

- [scope or usage constraint for this skill]

Step 4 — Preview and confirm

Show the content to be created and confirm with the user before writing.

Step 5 — Create and register

1. Create the file at the corresponding path 2. If it is a project skill, suggest adding it to the project CLAUDE.md in the skills section 3. If it is a generic skill, add it to the registry in ~/.claude/CLAUDE.md

---

Global Catalog Skills

Current catalog available in ~/.claude/skills/:

SDD Phase Skills

Infrastructure / Meta-tools

Workflow

Stack-agnostic global skills

Tech skill templates (NOT deployed globally)

Located at skills/_templates/tech/<name>/ in the agent-config repo. NOT copied to ~/.claude/skills/ by install.sh. skill-creator copies them into a consumer project's .claude/skills/<name>/ on demand.

---

Rules

• Always use real project code as examples when it is a project skill
• Never invent patterns — extract them from existing code
• Minimum 3 code examples per skill (reference and anti-pattern formats)
• Preview and confirm before writing
• Register the new skill in the corresponding CLAUDE.md
• The format-selection step (Step 1b) MUST always run before skeleton generation — a skeleton is never written without a confirmed format type
• The format: field MUST be present in the YAML frontmatter of every SKILL.md generated by this skill
• If docs/format-types.md does not exist, default all new skills to procedural and emit WARNING: "docs/format-types.md not found — skill-format-types change may not be applied"
• Inference is a convenience — the user MUST always confirm or override the inferred type before the skeleton is written