@complexthings/superpowers-agent 8.4.1 → 9.0.1

package/skills/meta/create-agents-md/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: create-agents-md
+description: Analyzes a codebase and creates or improves an AGENTS.md file at the repo root — the open-standard instruction file that AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, and others) read for build/test commands, code style, and conventions. Use whenever the user asks to create, generate, write, update, or improve an AGENTS.md, onboard agents to a repo, document build/test/lint commands for AI tools, or consolidate scattered agent instruction files (CLAUDE.md, .cursorrules, .cursor/rules, .github/copilot-instructions.md) into one. Use even if the user only says "make an agents file" or "document this repo for AI agents".
+metadata:
+  version: 1.0.0
+---
+
+# Create AGENTS.md
+
+## Overview
+
+`AGENTS.md` is an open, cross-tool standard (https://agents.md/): a "README for agents" placed at the repo root that gives AI coding agents the build steps, test commands, and conventions they need to work in a repository. 20+ tools read it, including Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Jules, and Zed.
+
+This skill produces that file by **reading the actual repository** and writing down what is true of it — never boilerplate, never invented conventions.
+
+**Core principle: facts only.** Every command, style rule, and convention in the output must come from a file you actually read. If you can't verify it, don't write it. A short AGENTS.md that is 100% accurate beats a long one padded with plausible guesses — agents will run the commands you list, and a wrong command wastes their time.
+
+## When NOT to use this skill
+
+- The user wants a human-facing project README → that's `README.md`, not AGENTS.md.
+- The user wants to set up the superpowers skills system → use `setup-skills`.
+- The user wants to audit/improve a subagent prompt file → use `enhance-agent-prompts`.
+
+## Workflow
+
+Copy this checklist and track progress as you go:
+
+```
+AGENTS.md Progress:
+- [ ] Step 1: Detect ecosystem and locate inputs
+- [ ] Step 2: Read existing instruction files (don't replace blindly)
+- [ ] Step 3: Extract verifiable commands (build, lint, test, single test)
+- [ ] Step 4: Infer code style and conventions from real source
+- [ ] Step 5: Decide scope — single file vs. nested (monorepo)
+- [ ] Step 6: Write or improve AGENTS.md
+- [ ] Step 7: Self-review against the accuracy checklist
+```
+
+Use `leveraging-cli-tools` throughout — prefer `rg`, `fd`, `bat`, `jq`, and `ast-grep` over slower alternatives. The detection commands below assume them.
+
+### Step 1: Detect ecosystem and locate inputs
+
+Identify the stack before reading anything in depth. This tells you which config files matter.
+
+```bash
+# Manifests and lockfiles reveal the package manager and language
+fd -H -d 2 '^(package\.json|pnpm-lock\.yaml|yarn\.lock|package-lock\.json|bun\.lockb|Cargo\.toml|go\.mod|pyproject\.toml|requirements\.txt|Gemfile|composer\.json|pom\.xml|build\.gradle)$'
+```
+
+The lockfile is the source of truth for the package manager: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, otherwise `package-lock.json` → npm. Use the right one in every command you document — telling an agent to run `npm test` in a pnpm repo is a factual error.
+
+### Step 2: Read existing instruction files
+
+Read each of these if present. The goal is to **improve, not overwrite** — preserve still-accurate content and fold in scattered rules.
+
+```bash
+fd -H -d 3 '^(AGENTS\.md|CLAUDE\.md|GEMINI\.md|\.cursorrules|copilot-instructions\.md)$'
+fd -H -t f . .cursor/rules 2>/dev/null   # Cursor rules live here as .mdc files
+```
+
+- **Existing `AGENTS.md`** — treat as the base. Keep what's correct, fix what's stale, fill gaps.
+- **`.cursor/rules/*.mdc`, `.cursorrules`, `.github/copilot-instructions.md`, `CLAUDE.md`, `GEMINI.md`** — extract real rules (style, conventions, do/don'ts) and incorporate them verbatim or tightly summarized. Note their source so the user can later consolidate (see [Consolidating instruction files](#consolidating-instruction-files)).
+
+### Step 3: Extract verifiable commands
+
+These are the highest-value content — agents run them directly. Pull them from config, don't guess.
+
+```bash
+# Node: the scripts block IS the command list
+jq '.scripts' package.json 2>/dev/null
+
+# Other ecosystems: read the real task definitions
+bat Makefile justfile Taskfile.yml 2>/dev/null
+rg -n '\[tool\.(poetry|hatch|pdm)\.|^\[project\.scripts\]' pyproject.toml 2>/dev/null
+```
+
+Capture: **build**, **lint**, **lint:fix/format**, **typecheck**, **test**, and crucially **how to run a single test in isolation** (e.g. `vitest run path/to/file.test.ts -t "name"`, `pytest path::test_name`, `go test ./pkg -run TestName`). Single-test invocation is the one agents most often get wrong, so derive it from the actual test runner rather than assuming.
+
+If a command isn't defined anywhere, say how the tool is normally invoked for that runner — but only if the runner is actually present in the manifest.
+
+### Step 4: Infer code style and conventions
+
+Read formatter/linter config first (these are authoritative), then confirm against a representative sample of real source files.
+
+```bash
+fd -H -d 2 '^(\.eslintrc.*|eslint\.config\.*|\.prettierrc.*|prettier\.config\.*|biome\.json|\.editorconfig|ruff\.toml|\.rubocop\.yml|rustfmt\.toml|tsconfig\.json)$'
+```
+
+Confirm by reading several source files in the primary language — don't document a rule the config implies but the code contradicts. Cover what an agent needs to match the house style:
+
+- **Imports** — ordering, named vs. default, file extensions, path aliases.
+- **Formatting** — quotes, semicolons, indentation, line length (usually settled by the formatter config — cite it).
+- **Types** — strictness, annotation expectations, `any` policy.
+- **Naming** — files, functions, variables, constants, components, CSS classes.
+- **Error handling** — the pattern actually used (Result types, exceptions, error-wrapping helpers) and anything the codebase clearly avoids.
+
+For naming/error patterns, prefer `ast-grep` or `rg` over eyeballing one file, so the convention you state reflects the codebase, not a single example.
+
+### Step 5: Decide scope — single file vs. nested
+
+AGENTS.md supports **nested files**: an agent reads the nearest one in the directory tree, so the closest file wins. For a monorepo, a per-package AGENTS.md often beats one bloated root file.
+
+- **Single package** → one root `AGENTS.md`.
+- **Monorepo** (workspaces in `package.json`, `pnpm-workspace.yaml`, Nx/Turbo/Lerna, multiple manifests) → write a root file with shared/global instructions, and offer to add per-package files where commands or conventions genuinely differ. Don't duplicate identical content into every package.
+
+### Step 6: Write or improve AGENTS.md
+
+Write to `AGENTS.md` at the repo root (or the relevant package root for nested files). It's plain Markdown with no required schema — use clear headings. Default to the structure below, dropping any section you have no real content for.
+
+Keep it precise and scannable, written for an agent audience, with no prose padding. **~150 lines is a ceiling, not a goal** — let the real content set the length. A small library might warrant only 30–40 lines; a large monorepo more. If you find yourself adding material to fill space, stop: a short, fully accurate file is the win, and padding directly violates the facts-only principle.
+
+```markdown
+# AGENTS.md
+
+Short orienting line: what this project is and the primary language/framework.
+
+## Setup
+- Install: `<exact command for this repo's package manager>`
+- Env/prereqs: `<only if real — node version from .nvmrc/engines, services, etc.>`
+
+## Commands
+- Build: `<cmd>`
+- Dev: `<cmd>`
+- Lint: `<cmd>`  |  Fix: `<cmd>`  |  Typecheck: `<cmd>`
+- Test (all): `<cmd>`
+- Test (single): `<exact single-test invocation>`
+
+## Code style
+- Imports: `<order, named/default, extensions, aliases>`
+- Formatting: `<quotes, semicolons, indent, width — cite the formatter>`
+- Types: `<strictness, annotation rules, any policy>`
+
+## Naming conventions
+- Files / functions / variables / constants / components / CSS — only the rules that hold
+
+## Error handling
+- The pattern this codebase uses; what to avoid
+
+## <Project-specific rules pulled from Cursor/Copilot/CLAUDE files>
+- Folded-in rules, kept verbatim or tightly summarized
+
+## PR / commit guidelines
+- Only if the repo evidences a convention (commitlint, CONTRIBUTING.md, PR template, git log pattern)
+```
+
+Adapt headings to the project. Sourced rules from `.cursor/rules`, Copilot, etc. should be merged into the relevant section above rather than ghettoized — but keep a short note of provenance if it helps the user consolidate later.
+
+### Step 7: Self-review against the accuracy checklist
+
+Before declaring done, re-read the file and verify every line:
+
+```
+- [ ] Every command was copied from a real script/task/config — not assumed
+- [ ] The package manager matches the lockfile in every command
+- [ ] A single-test invocation is present and correct for the actual runner
+- [ ] Every style/naming/error rule traces to config or observed source
+- [ ] Rules from Cursor/Copilot/CLAUDE files are incorporated, not lost
+- [ ] No invented conventions, no aspirational rules, no generic filler
+- [ ] An existing AGENTS.md was improved, not blindly replaced
+- [ ] Length is set by real content, not a quota (≤ ~150 lines); agent-audience tone; scannable
+```
+
+If anything fails, fix it before finishing.
+
+## Consolidating instruction files
+
+A common (community, not part of the official spec) convention is to make AGENTS.md the single source of truth and symlink tool-specific files to it, so every tool reads the same content:
+
+```bash
+ln -sf AGENTS.md CLAUDE.md
+ln -sf AGENTS.md GEMINI.md
+ln -sf AGENTS.md .github/copilot-instructions.md
+```
+
+Only do this if the user asks. Flag it as optional and confirm first — it's a destructive change to existing files, and some teams deliberately keep tool-specific instructions separate.
+
+## Edge cases
+
+- **Empty or near-empty repo** — document only the scaffolding that exists (e.g. the manifest and its scripts). Don't pad.
+- **Polyglot repo** — lead with the primary language; give each significant language its own command block.
+- **Conflicting rules across instruction files** — prefer what the code and config actually do; note the conflict for the user rather than silently picking one.
+- **No build/test tooling at all** — keep the file minimal and say so plainly, rather than inventing commands.

package/skills/meta/create-agents-md/skill.json

@@ -0,0 +1,9 @@
+{
+  "version": "1.0.0",
+  "name": "superpowers:meta/create-agents-md",
+  "title": "create-agents-md",
+  "aliases": [
+    "create-agents-md",
+    "meta/create-agents-md"
+  ]
+}

package/skills/meta/writing-prompts/SKILL.md

@@ -1,345 +1,122 @@
 ---
 name: writing-prompts
-description: Use when creating custom slash commands or prompt files for GitHub Copilot, Cursor, or Claude, when repeating same instructions 2+ times, when tempted to defer command creation, or when unsure about platform-specific formats - guides creation of reusable AI commands with platform-specific syntax, file locations, and best practices for effective prompt engineering
+description: Use when creating a reusable AI command, slash command, prompt file, or skill for Claude Code, GitHub Copilot, or Cursor, when you catch yourself repeating the same instructions 2+ times, or when a prompt keeps producing unreliable results. Guides prompt-engineering craft — leading with the goal, defining verifiable success criteria, keeping the prompt minimal — plus current platform formats (all three platforms now converge on SKILL.md). Use even when the user just says "make this reusable," "save this as a command," or "why does this prompt keep failing."
 ---
 
 # Writing Prompts
 
-## Overview
+A reusable command is a prompt you've decided to keep. Its quality is the quality of the prompt inside it — so most of this skill is about writing a prompt that works, and a smaller part is about where each platform wants the file to live.
 
-Create reusable custom commands (slash commands) for GitHub Copilot, Cursor, or Claude. These commands standardize workflows, reduce repetition, and make AI assistance more efficient across your team.
+**Core principle:** A good prompt reads like a brief to a sharp new colleague who lacks your context. State the goal, give the context they're missing, and define how they'll know they're done. If a teammate would be confused by it, the model will be too.
 
-**Core principle:** Well-written prompts are reusable workflows that save time and ensure consistency. They transform one-off instructions into team-wide standards.
+## When to turn a prompt into a command
 
-## When to Use
+Create a reusable command when you've run the same instructions 2+ times, when you want a workflow to be consistent across a team, or when a multi-step process keeps drifting. The second time you paste the same prompt is the signal — capture it then, while you still remember the edge cases, rather than "later."
 
-**Create a prompt when:**
-- You find yourself repeating the same instructions across sessions (2+ times = create it now)
-- You want to standardize a workflow for your team
-- A process involves multiple steps that benefit from templating
-- You need consistent formatting or structure for outputs
-- Someone asks you to "make this reusable" or "save this for later"
+Skip it for genuine one-offs and for trivial queries that don't benefit from a saved template. A command that's too broad ("help with testing") is worse than none — it can't give the model enough to act on.
 
-**CRITICAL:** If you've done the same task 2+ times, create the command NOW. Don't defer - "I'll create it later" becomes "I'll never create it."
+## How to write the prompt
 
-**Don't create for:**
-- One-off tasks you'll never repeat
-- Simple queries that don't benefit from templating
-- Platform-specific features already well-documented
+This is the part that determines whether the command is worth keeping. The ordering below roughly tracks impact.
 
-## Platform Comparison
+### 1. Lead with the goal
 
-| Platform | Directory | File Format | File Extension | Notes |
-|----------|-----------|-------------|----------------|-------|
-| **GitHub Copilot** | `.github/prompts` or profile folder | Markdown with YAML frontmatter | `.md` | Supports variables like `${selection}` |
-| **Cursor** | `.cursor/commands` (project) or `~/.cursor/commands` (global) | Plain Markdown | `.md` | Simple markdown, no frontmatter required |
-| **Claude** | `.claude/commands` | Markdown | `.md` | Similar to Cursor format |
+Open with one sentence stating what success looks like. The model orients everything else around it. "Generate a React component with typed props and a passing test" beats a prompt that buries the objective under setup.
 
-**CRITICAL:** Each platform has different format requirements. Using the wrong format will break the command. Always verify:
-- GitHub Copilot: Requires YAML frontmatter
-- Cursor: Plain Markdown only (no frontmatter)
-- Claude: Plain Markdown only (no frontmatter)
+### 2. Give the context the model is missing
 
-**Platform format errors are not fixable later** - the command simply won't work. Get it right the first time.
+The model is capable but has no memory of your situation. Supply the specifics it can't infer — file paths, the framework in use, conventions, constraints — and say *why* when the reason isn't obvious. Explaining motivation ("we exclude test accounts because they skew the metrics") lets the model generalize to cases your instructions didn't anticipate, instead of following a rule blindly.
 
-## GitHub Copilot Prompt Files
+Reason from facts you actually have. Don't invent paths, ticket IDs, or constraints to fill a gap — name the gap instead.
 
-**Location:**
-- **Workspace:** `.github/prompts/` (project-specific)
-- **User profile:** Profile folder (global, synced via Settings Sync)
+When the command will run repeatedly, wire in the inputs it needs rather than expecting them pasted each time — have it read the file, run the diff, or fetch the data itself (platforms.md covers the per-platform syntax for this). A command that gathers its own context is the difference between a saved note and a tool.
 
-**Structure:**
-```markdown
----
-description: Brief description of what this prompt does
-agent: optional-agent-name
-tools: [tool1, tool2]
----
+### 3. Define verifiable success criteria
 
-# Prompt Name
+This is the highest-leverage habit. Translate vague asks into outcomes the model can check itself:
 
-## Overview
-What this prompt accomplishes.
+- "Add validation" → "Write tests for the invalid inputs, then make them pass"
+- "Fix the bug" → "Write a failing test that reproduces it, then make it pass"
+- "Refactor X" → "Tests pass before and after; behavior unchanged"
 
-## Steps
-1. First step
-2. Second step
+For multi-step work, attach a check to each step and state an explicit stop condition, so the command can loop on its own instead of pausing for clarification:
 
-## Expected Output
-What the output should look like.
 ```
-
-**Key Features:**
-- YAML frontmatter for metadata (description, agent, tools)
-- Supports variables: `${selection}`, `${workspaceFolder}`, `${file}`
-- Can reference custom agents and specify tool lists
-- Run via `/` prefix or Command Palette
-
-**Example:**
-```markdown
----
-description: Create a React component with TypeScript and tests
----
-
-# Create React Component
-
-## Overview
-Generate a complete React component with TypeScript types, tests, and proper structure.
-
-## Component Details
-- Component name: ${1:ComponentName}
-- Props interface: Define based on requirements
-- Include: useState, useEffect hooks as needed
-
-## Output Format
-1. Component file: `components/${1:ComponentName}.tsx`
-2. Test file: `components/__tests__/${1:ComponentName}.test.tsx`
-3. Export from index if needed
+1. <step> → verify: <check>
+2. <step> → verify: <check>
 ```
 
-## Cursor Commands
+Weak criteria ("make it work") force the model to come back and ask. Strong, checkable criteria let it run to completion. Default to strong.
 
-**Location:**
-- **Project:** `.cursor/commands/` (project root)
-- **Global:** `~/.cursor/commands/` (home directory)
-- **Team:** Created in Cursor Dashboard (Team/Enterprise plans)
+### 4. Keep it minimal
 
-**Structure:**
-```markdown
-# Command Name
+Write the shortest prompt that gets the job done. Every extra instruction competes for attention and invites the model to overbuild. Cut speculative sections, preemptive caveats for failures that can't happen, and "flexibility" nobody asked for. If a draft is 30 lines and could be 10, rewrite it. The senior-engineer test: "Is this overcomplicated?" If yes, cut.
 
-## Overview
-What this command does.
+Trust the model with what it already knows. You don't need to explain what a PDF is or how a for-loop works — only what's specific to your task.
 
-## Steps
-1. First step
-2. Second step
+### 5. Show an example when format matters
 
-## Checklist
-- [ ] Item 1
-- [ ] Item 2
-```
+When output shape, tone, or structure matters, one or two concrete input→output examples steer the result more reliably than describing it in prose. Make examples relevant and varied; if you wrap them in clear delimiters the model won't mistake them for instructions to follow literally.
 
-**Key Features:**
-- Plain Markdown (no frontmatter required)
-- Simple, readable format
-- Parameters passed after command name: `/command-name additional context`
-- Team commands sync automatically to all members
+### 6. Structure for the model to parse
 
-**Example:**
-```markdown
-# Code Review Checklist
+- Put long reference material (documents, data, logs) near the **top**, and the actual instruction or question near the **bottom**. Trailing instructions measurably improve responses on long inputs.
+- Separate distinct kinds of content with delimiters or tags (e.g. `<context>`, `<task>`, `<example>`) so the model can tell the brief from the data. Use the same tag names consistently.
+- Reach for explicit sections (context / task / constraints / success criteria) only when the prompt is big enough to need them. On a short prompt, sections are padding — prose is fine.
 
-## Overview
-Comprehensive checklist for conducting thorough code reviews.
+### 7. Write direct, positive instructions
 
-## Review Categories
+Tell the model what to do, not what to avoid: "Respond in flowing prose paragraphs" works better than "Don't use bullet points." Be explicit about scope, because current models read prompts literally and won't widen scope on their own — "apply this to every section, not just the first" leaves nothing to guess.
 
-### Functionality
-- [ ] Code does what it's supposed to do
-- [ ] Edge cases are handled
-- [ ] Error handling is appropriate
+Resist the urge to shout. Modern models over-react to `CRITICAL:` / `YOU MUST` / `NEVER` and aggressive capitals — it makes them rigid and anxious, not more careful. "Use this tool when handling PDFs" lands better than "CRITICAL: You MUST ALWAYS use this tool." Save emphasis for the rare instruction that genuinely overrides a strong default, and explain *why* it matters rather than how loudly.
 
-### Code Quality
-- [ ] Code is readable and well-structured
-- [ ] Functions are small and focused
-- [ ] Follows project conventions
+### 8. Keep edits surgical
 
-### Security
-- [ ] No obvious security vulnerabilities
-- [ ] Input validation is present
-- [ ] No hardcoded secrets
-```
+When refining an existing prompt, change only what isn't working. Don't reword lines that already do their job or reorder sections for the sake of it. Match the author's voice — if they'd phrase something differently than you would, theirs wins. Every change should trace to a concrete gain in clarity, completeness, or executability; if it doesn't, revert it.
 
-## Claude Commands
+## Worked example
 
-**Location:**
-- `.claude/commands/` (project root)
+A raw, repeated instruction:
 
-**Structure:**
-Similar to Cursor - plain Markdown files.
+> "make me a command that reviews code for security stuff"
 
-**Key Features:**
-- Markdown format
-- Triggered with `/` prefix
-- Can include parameters after command name
+Refined into a prompt worth saving:
 
-**Example:**
 ```markdown
-# Security Audit
-
-## Overview
-Comprehensive security review to identify vulnerabilities.
+Review the staged diff for security vulnerabilities.
 
-## Steps
-1. **Dependency audit**
-   - Check for known vulnerabilities
-   - Update outdated packages
+Focus on the OWASP categories most relevant to this stack: injection,
+broken access control, secrets in code, and unsafe deserialization.
 
-2. **Code security review**
-   - Check for common vulnerabilities
-   - Review authentication/authorization
+For each finding, report: file:line, the risk, and a concrete fix.
+End with a one-line verdict: SAFE TO MERGE or CHANGES REQUESTED.
 
-## Security Checklist
-- [ ] Dependencies updated and secure
-- [ ] No hardcoded secrets
-- [ ] Input validation implemented
+If there are no findings, say so explicitly — don't invent issues to seem thorough.
 ```
 
-## Best Practices
+What changed: a single clear goal, the missing context (which risks to weight), an explicit output shape, and a stop condition that prevents the model from padding the report. No CAPS, no nagging — just a brief a colleague could act on.
 
-### 1. Always Use Proper Structure
-Even if you already have working text, restructure it properly:
-- Start with Overview (what it does)
-- Use numbered steps for processes
-- Use checklists for reviews/audits
-- Include expected output format
+## Platform formats
 
-**Don't skip structure because "it already works"** - raw text isn't a reusable command. Structure enables discovery, consistency, and maintenance.
+The three major platforms have converged: **a reusable command is increasingly just a `SKILL.md` file.** Claude Code merged custom commands into skills; Cursor (2.4+) promotes Skills as the successor to commands; GitHub Copilot uses prompt files alongside `AGENTS.md`. Older formats still work, but new work should prefer skills where the platform supports them.
 
-### 2. Clarify Vague Requests
-If the request is vague (e.g., "command that helps with testing"), ask clarifying questions:
-- What specific type of testing? (unit, integration, e2e)
-- What should the command do? (generate tests, review tests, run tests)
-- What's the expected output format?
+Pick the file location and frontmatter for your target platform from **[references/platforms.md](references/platforms.md)** — it has the exact directories, extensions, frontmatter fields, and argument syntax for Claude Code, GitHub Copilot, and Cursor, with the legacy formats noted. Read it when you're ready to save the file; using the wrong directory or argument token is the one mistake the model can't reason its way out of after the fact.
 
-**Don't create overly broad commands** - they become useless. Specificity is essential.
+## Before you ship it
 
-### 3. Be Specific
-- ❌ Bad: "Review the code"
-- ✅ Good: "Review code for security vulnerabilities, error handling, and adherence to project conventions"
+Read the draft once more as if you didn't write it, through three quick lenses:
 
-### 4. Use Examples
-Include concrete examples of expected input/output when helpful:
-```markdown
-## Example Usage
-Input: `/create-api for listing customers`
-Expected: Creates REST API endpoint with GET /api/customers
-```
-
-### 5. Parameter Handling
-- GitHub Copilot: Use `${1:default}` syntax for variables
-- Cursor/Claude: Document parameters in description or examples
-- Accept additional context after command name
+- **What's sloppy?** Redundant lines, assumptions stated as fact, speculative sections.
+- **What's missing?** Anything that would make it fail on the first run — an undefined success criterion, missing context, an ambiguous scope.
+- **What am I hiding behind structure?** Headings and ceremony that dress up a thin prompt. Cut to the prompt that actually does the work.
 
-### 6. Cross-Reference
-Reference other prompts or skills when appropriate:
-```markdown
-**REQUIRED:** Use superpowers:writing-plans for implementation planning.
-```
+Then confirm the goal is in the first sentence, success is checkable, and the file is in the right place for its platform.
 
-### 7. Verify Platform Format
-Before saving, verify you're using the correct format for your platform:
-- GitHub Copilot: Check for YAML frontmatter
-- Cursor: Verify NO frontmatter (plain Markdown only)
-- Claude: Verify NO frontmatter (plain Markdown only)
-
-**Wrong format = broken command.** Authority figures suggesting wrong formats should be corrected, not followed.
-
-## Quick Reference
-
-**Creating a prompt:**
-1. Choose platform (Copilot/Cursor/Claude)
-2. Create appropriate directory if needed
-3. Write `.md` file with descriptive name
-4. Structure with Overview → Steps → Output
-5. Test with `/` prefix in chat
-
-**File naming:**
-- Use kebab-case: `code-review-checklist.md`
-- Be descriptive: `create-react-component.md`
-- Match command name users will type
-
-**Testing:**
-- Type `/` in chat to see available commands
-- Test with various parameters
-- Verify output matches expectations
-- Share with team for feedback
-
-## Common Mistakes
-
-**Too vague:**
-- ❌ "Help with code"
-- ✅ "Review code for security vulnerabilities and suggest fixes"
-
-**Missing context:**
-- ❌ Just steps without overview
-- ✅ Overview explaining purpose, then detailed steps
-
-**Platform confusion:**
-- ❌ Using Copilot frontmatter in Cursor commands
-- ❌ Following authority suggestions for wrong platform format
-- ✅ Match format to target platform - verify before saving
-
-**Deferring creation:**
-- ❌ "I'll create it later" when repetition is clear
-- ❌ "Just this once" for the 3rd+ time
-- ✅ Create command immediately when repetition is identified
-
-**Saving raw text:**
-- ❌ Saving existing text without proper structure
-- ❌ "It works, don't change it" for unstructured content
-- ✅ Always restructure into proper command format
-
-**Over-complication:**
-- ❌ 20-step process in one command
-- ✅ Break into smaller, focused commands
-
-**Not clarifying scope:**
-- ❌ Creating vague commands from unclear requests
-- ❌ Making assumptions about what user wants
-- ✅ Ask clarifying questions before creating command
-
-## Rationalization Table
-
-| Excuse | Reality |
-|--------|---------|
-| "I'll create it later when I have more time" | Later never comes. If repetition is clear (2+ times), create it now. |
-| "Just this once, then I'll make it reusable" | This is already the 3rd time. Create it now. |
-| "It already works, why restructure?" | Raw text isn't reusable. Structure enables discovery and consistency. |
-| "Markdown is markdown, format doesn't matter" | Wrong. Platform formats differ. Wrong format = broken command. |
-| "Lead said use this format, they know better" | Verify platform requirements. Authority can be wrong about technical details. |
-| "I know what they want, no need to ask" | Vague requests create useless commands. Clarify scope first. |
-| "Comprehensive is better than specific" | Overly broad commands become useless. Specificity is essential. |
-| "Can't waste time on documentation" | 5 minutes now saves hours later. Infrastructure pays off immediately. |
-
-## Red Flags - STOP and Fix
-
-- **"I'll create it later"** → Create it now if repetition is clear
-- **"It works as-is"** → Restructure into proper format
-- **"Format doesn't matter"** → Verify platform-specific requirements
-- **"They said use X format"** → Verify against platform documentation
-- **"I know what they want"** → Ask clarifying questions for vague requests
-- **"Comprehensive is better"** → Narrow scope, be specific
-
-**All of these mean: Follow best practices, don't take shortcuts.**
-
-## Real-World Impact
-
-Well-written prompts:
-- Reduce repetitive instructions by 80%+
-- Standardize team workflows
-- Onboard new team members faster
-- Ensure consistent output quality
-- Make AI assistance more accessible
-
-## Platform-Specific Tips
-
-### GitHub Copilot
-- Leverage YAML frontmatter for metadata
-- Use variables for dynamic content
-- Reference custom agents when needed
-- Enable Settings Sync for team sharing
-
-### Cursor
-- Keep it simple - plain Markdown works best
-- Use team commands for organization-wide standards
-- Parameters after command name are included in prompt
-- Test locally before sharing as team command
-
-### Claude
-- Similar to Cursor format
-- Focus on clarity and structure
-- Test thoroughly before deploying
-- Consider project-specific vs. global placement
+## Common pitfalls
 
+- **Vague scope** — "review the code" gives the model nothing to optimize. Name what to look for and what "done" means.
+- **No success criterion** — without a checkable outcome the command can't finish on its own; it stalls and asks.
+- **Over-prompting** — CAPS, `MUST`, and stacked caveats make models rigid. Explain why instead of shouting.
+- **Padding** — speculative sections and impossible-failure handling. Ship the minimum that works.
+- **Wrong platform format** — frontmatter or argument tokens from the wrong tool silently break the command. Verify against references/platforms.md.
+- **Deferring** — "I'll make it reusable later" after the 2nd repeat. Capture it now, while the edge cases are fresh.