Contributing to cursor_kenji

August 19, 2026 · View on GitHub

Guide for adding, updating, and maintaining skills and commands.

Prefix	Purpose
`audit-`	Findings; default present-then-stop. Audit-and-fix exceptions: `audit-responsive`, `audit-code-quality`, `audit-performance`, `audit-security`, `audit-i18n`, `audit-bundle-size`
`plan-`	Audit + burndown — no edits until the user approves
`backend-`	Server-side patterns (DB, observability, realtime)
`data-`	Pipelines, ETL, visualization
`debug-`	Reproduce → isolate → fix failures
`deploy-`	Release, publish, post-deploy verify
`design-`	Create new visual/API surfaces
`docs-`	Write or co-author documentation
`enhance-`	Improve existing web/mobile UI, UX, SEO, email deliverability
`housekeep-`	Consolidate a drifted design system
`meta-`	Skills and MCP authoring
`mobile-`	React Native, Capacitor, emulator
`protocol-`	Procedural guardrails
`test-`	QA, unit tests, load, visual regression
`workflow-`	Dev-process skills (git, refactor, PR, spec-TDD)

Core Content

Pattern 2

[Code examples, explanations]

skill-a — How it relates
skill-b — How it relates

Validation

After using this skill:

Check 1 → What to verify
Check 2 → What to verify
Check 3 → What to verify


### 3. Quality Checklist

Every skill MUST have:

- [ ] **Frontmatter** with `name` and `description` (include trigger keywords)
- [ ] **"Check Existing First"** section at the top
- [ ] **Production-ready code examples** (no placeholders)
- [ ] **TypeScript** in all code examples (strict, no `any`)
- [ ] **Related Skills** section for cross-referencing
- [ ] **Validation** section with post-implementation checks
- [ ] **Prompt enhancement (T1–T6)** — freedom declared, one reasoning scaffold, one worked example, self-critique rubric; see [PROMPT-ENHANCEMENT-PLAYBOOK.md](PROMPT-ENHANCEMENT-PLAYBOOK.md) / `enhance-skill-prompts` (existing skills) or `meta-skill-creator` (new)

### 4. Description Guidelines

The `description` field is critical — it's how Cursor decides when to use the skill.

**Rules:**
- Open with an action verb (`Fix`, `Wire`, `Build`, `Audit`, `Release` …)
- Keep ≤320 characters (same folding as `scripts/validate-skills.mjs`)
- Include 3-6 trigger keywords/phrases users actually type
- Never write "This skill provides…" or "This skill should be used when…"
- No AI-tells: avoid `leverage`, `seamless`, `robust`, `powerful`, `elevate`, `cutting-edge`, `delve`, `comprehensive solution`

**Good:**
```yaml
description: Fix slow Postgres queries and N+1 problems. Use when asked about "slow query", "add index", "database timeout", "optimize query", schema design, or RLS policies.

Bad:

description: This comprehensive skill leverages powerful AI capabilities to seamlessly help with database stuff.

5. Voice & tone

Imperative, direct: "Fix X", "Wire Y", "Run Z"
No hedging: ~~"This might help with…"~~ → "Use when…"
No filler: ~~"In order to…"~~ → "To…"
Body prose: short sentences, bullet points preferred over dense paragraphs

6. Language

SKILL.md bodies: English only (SEO + Cursor intent matching)
references/*.md detail files: English tight prose (reference files are link-only, not auto-loaded; Japanese would save zero tokens for typical sessions)

Adding a New Command

1. Create the File

touch commands/my-command.md

2. Structure

Commands are plain markdown (no frontmatter). They're triggered via /my-command in Cursor.

# Command Title

## Purpose
One-line description of what this command does.

## Process

### 1. First Step
- Action items
- Commands to run

### 2. Second Step
[...]

## Checklist
- [ ] Verification step 1
- [ ] Verification step 2

3. Command Design Principles

Actionable — Each step produces a concrete output
Sequential — Steps build on each other
Verifiable — Includes a checklist at the end
Self-contained — Doesn't require external context

Updating Existing Skills

When to Update

Library API changed (React 19, Next.js 15+, etc.)
New patterns emerged as best practice
Missing coverage for common use case
Code examples have bugs or are outdated

Update Process

Read the existing skill fully
Identify what needs changing
Make targeted edits (don't rewrite everything)
Ensure backward compatibility
Update "Related Skills" if new cross-references exist
Test code examples are syntactically valid

Version Tracking

Use git commit messages to track skill evolution:

feat(skills): add React 19 use() patterns to data-visualization
fix(skills): update design-motion for Framer Motion v11 API
docs(skills): add cross-references to enhance-web-web3d

Style Guide

Code Examples

Use TypeScript, strict mode
Include type annotations
Show complete, copy-pasteable examples
Add comments for non-obvious code
Use existing project conventions (@/ imports, cn() utility)

Formatting

Use tables for comparisons and checklists
Use code blocks with language tags
Keep paragraphs short (2-3 sentences max)
Use headers to create scannable structure
Avoid filler words

Naming

Element	Convention	Example
Skill name	lowercase-hyphen	`data-visualization`
Command name	lowercase	`commit.md`
Directory	lowercase-hyphen	`skills/mobile-first/`
Code identifiers	Follow TypeScript conventions	`useMediaQuery`, `ButtonProps`

Testing Skills

Quick Validation

Syntax check: Ensure YAML frontmatter is valid
Code check: Code examples should compile (no syntax errors)
Completeness: Has all required sections
Accuracy: Code patterns match current library versions

In Cursor

Copy skill to ~/.cursor/skills/ or run ./install.sh
Start a conversation that should trigger the skill
Verify Cursor uses the skill appropriately
Check that code suggestions match the skill's patterns

Repository Maintenance

Git hooks (clone contributors)

After cloning, enable pre-commit validation:

git config core.hooksPath .githooks

This is not run automatically on npm install — only set it when working from a git clone.

Regular Tasks

Quarterly: Check all skills against latest library versions
Monthly: Review git log for skill-related commits
On major release: Update affected skills (React, Next.js, Tailwind, etc.)

Adding to CATALOG.md

When adding a new skill, also update:

docs/CATALOG.md — entry, trigger phrases, related skills
docs/TRIGGER-CHEATSHEET.md — "say this → skill" row
docs/PLAN-LOOPS.md + a /…-plan command if it is a plan-* skill
docs/GETTING-STARTED.md / README use-case table if a newcomer would type that phrase

Then say "audit my skills" (audit-skill-conflicts) so overlapping descriptions and stale handoffs get caught. Per-file spec lint (npm run validate:skills) cannot see those. npm run check:skill-refs fails CI on doubled-prefix typos (mobile-mobile-*) and stale audit-responsive-layout aliases.

Brief description

Updating README.md

When adding a new skill:

Add to the appropriate category table in README
Update the skill count in the file tree
Add to "What's Inside" tree if it's a new directory

Third-party skills: also update THIRD-PARTY-SKILLS.md.

Third-Party Skills (summary)

Full guide: THIRD-PARTY-SKILLS.md

Requirement	Detail
Directory prefix	`thirdparty-` (e.g. `thirdparty-emil-design-eng`)
Frontmatter `name`	Must match directory name
`ATTRIBUTION.md`	Upstream URL, license, update steps
Skill body	Upstream content only — no Kenji "Check Existing First"
Pipeline	Included automatically by `./install.sh`