Create a custom /skill-name that lives in your project, complementing the kit's built-in audit and workflow skills.

The kit ships 20 generic skills (/code-quality-audit, /architecture-review, etc.). Sometimes your project has a workflow specific enough that a custom skill makes sense — "audit our API routes for the envelope response pattern", "verify offline-first sync code", "review the i18n keys".

This recipe walks through creating a skill that lives in your repo, loads automatically via Claude Code's semantic matching, and survives kit upgrades.

When to use this

You've found yourself running the same multi-step audit 3+ times
The audit is too project-specific to upstream into the kit
A short prompt like "check the envelope pattern" keeps producing inconsistent results

When NOT to use this

The need is one-time → just prompt Claude directly
The need fits an existing kit skill with minor tweaks → customize via CLAUDE.project.md instead
You want the skill in every project → consider extracting to user-level (~/.claude/skills/) or PR upstream

Steps

1. Pick a name

Use kebab-case, descriptive, slash-prefixed when invoked. Examples:

envelope-pattern-audit
i18n-key-check
api-route-review

The name becomes the file path: .claude/skills/<name>/SKILL.md.

2. Create the skill directory

mkdir -p .claude/skills/envelope-pattern-audit
touch .claude/skills/envelope-pattern-audit/SKILL.md

Skills you create after install.sh aren't tracked in .kit-manifest, so --upgrade will leave them alone. They're project-owned.

3. Write the SKILL.md

Use the kit's standard skill structure. Minimum required:

---
name: envelope-pattern-audit
description: Audits all API route handlers for the envelope response pattern — { data, error, meta }. Flags deviations and suggests fixes.
user-invocable: true
---

# Envelope Pattern Audit

## Kit Context

Before starting:

1. Read `CODEBASE_MAP.md` for project understanding
2. Read `CLAUDE.project.md` for project-specific rules

## When to Use

Invoke with `/envelope-pattern-audit` when:

- Reviewing a new feature that adds API routes
- Onboarding to ensure consistency
- Pre-release sweep before tagging a version

## Process

### Phase 1: Locate route handlers

[your project-specific instructions]

### Phase 2: Verify envelope shape

For each handler:

- Success: `{ data: T, error: null, meta?: {...} }`
- Failure: `{ data: null, error: { code, message }, meta?: {...} }`

[etc.]

## Output Format

\`\`\`markdown
# Envelope Pattern Audit

| Route | Handler | Compliant | Issue |
|---|---|---|---|
\`\`\`

## Notes

- [project-specific gotchas]

4. Verify

./scripts/validate-skills.sh

Should report your new skill passing all checks (frontmatter, required sections, etc.).

5. Test the skill

In a Claude Code session:

/envelope-pattern-audit

If Claude doesn't pick it up automatically, the description field in frontmatter probably isn't specific enough — Claude Code uses semantic matching against the description.

What good descriptions look like

The description field is the only thing Claude's semantic matcher sees. Make it concrete:

Bad	Good
Audits API routes	Audits all API route handlers for the envelope response pattern — `{ data, error, meta }`. Flags deviations.
Checks i18n	Verifies all user-facing strings use `t('key')` from `useTranslation()` and that every key exists in `locales/en.json` and `locales/tr.json`.

Extending the skill

If your skill needs sub-files (anti-patterns, examples, checklists):

.claude/skills/envelope-pattern-audit/
  SKILL.md
  references/
    examples.md       # correct patterns from your codebase
    anti-patterns.md  # what to flag and why
    checklist.md      # pre-commit verification list

Reference them from SKILL.md with relative links: [examples](references/examples.md).

Verification

./scripts/validate-skills.sh   # passes
./scripts/doctor.sh            # reports your skill in the count

In a fresh Claude Code session, ask: "What skills do you have for this project?" — Claude should mention your new skill.

Skills guide — how the skill system works under the hood
Customize CLAUDE.project.md — for lighter-weight project rules that don't warrant a full skill
Skill Generator — meta-skill that scaffolds new skills from your tech stack

Edit this page on GitHub

Add a Project-Specific Skill