@complexthings/superpowers-agent 8.4.1 → 9.0.0

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.

package/skills/meta/writing-prompts/references/platforms.md

@@ -0,0 +1,114 @@
+# Platform formats
+
+Exact locations, file formats, frontmatter, and argument syntax for reusable commands on each platform. Read the section for your target platform when saving the file.
+
+## Contents
+- The convergence on SKILL.md
+- Claude Code (skills + legacy commands)
+- GitHub Copilot (prompt files + custom instructions)
+- Cursor (commands + rules + skills)
+- Quick pick
+
+## The convergence on SKILL.md
+
+All three platforms are moving the same direction: a reusable command is becoming a skill — a directory containing a `SKILL.md` file with YAML frontmatter. Claude Code states custom commands "have been merged into skills"; Cursor 2.4 promotes Skills as the successor to commands and ships a `/migrate-to-skills` flow; GitHub Copilot reads `AGENTS.md` and a skills-style layout. Legacy formats still work everywhere, but prefer skills for new work where the platform supports them.
+
+A minimal skill, identical in shape across platforms:
+
+```
+my-command/
+└── SKILL.md
+```
+
+```markdown
+---
+name: my-command
+description: What it does and when to use it.
+---
+
+# My Command
+
+<the prompt body>
+```
+
+## Claude Code
+
+**Skills (recommended).**
+- Project: `.claude/skills/<name>/SKILL.md` (commit to git to share)
+- Personal: `~/.claude/skills/<name>/SKILL.md` (all your projects)
+- The command name comes from the **directory name** → `/my-command`. Frontmatter `name` only sets the display label.
+- Precedence: enterprise > personal > project. If a skill and a legacy command share a name, the skill wins.
+
+**Legacy commands (still supported).**
+- `.claude/commands/<name>.md` or `~/.claude/commands/<name>.md` → `/name` (from the file name).
+- Support the same frontmatter as skills.
+
+**Frontmatter (all optional; `description` is the one that matters for triggering):**
+`name`, `description`, `when_to_use`, `argument-hint` (e.g. `[issue-number]`), `arguments` (named positional args), `disable-model-invocation` (default `false` — set `true` to make it manual-only, i.e. a pure slash command the model won't auto-run), `user-invocable` (default `true`), `allowed-tools` / `disallowed-tools`, `model` (or `inherit`), `effort` (`low`/`medium`/`high`/`xhigh`/`max`), `context` (`fork`), `agent`, `hooks`, `paths` (glob auto-activation), `shell` (`bash`/`powershell`).
+
+**Arguments (0-based — note this differs from the old `$1`-is-first convention):**
+- `$ARGUMENTS` — all arguments as one string. If the file contains none, the args are appended as `ARGUMENTS: <value>`.
+- `$ARGUMENTS[0]` — first argument; `$ARGUMENTS[1]` second, etc.
+- `$0`, `$1` — shorthand; **`$0` is the first argument.**
+- `$name` — a named argument declared in `arguments:` frontmatter, bound by position.
+- Also available: `${CLAUDE_SESSION_ID}`, `${CLAUDE_EFFORT}`, `${CLAUDE_SKILL_DIR}`.
+
+**Bash injection in the body:**
+- Inline: `` !`<command>` `` (only at line start or after whitespace).
+- Block: a fenced ` ```! ` code block.
+- Runs as preprocessing before the model sees the body; requires a matching `allowed-tools` grant such as `Bash(gh *)`.
+
+**Skill vs command vs subagent:**
+- Reference-style content (knowledge the model pulls in when relevant) → a normal skill.
+- Action you invoke explicitly → a skill with `disable-model-invocation: true`, or a legacy command.
+- Delegated, isolated-context work → a subagent in `.claude/agents/<name>.md` (frontmatter `name`, `description`, `tools`, `model`), or a skill run with `context: fork` + `agent:`.
+
+## GitHub Copilot
+
+**Prompt files** (VS Code, Visual Studio, JetBrains):
+- Location: `.github/prompts/`
+- Naming: `<name>.prompt.md` (e.g. `explain-code.prompt.md`)
+- Frontmatter documented by GitHub: `agent:` (value `'agent'`) and `description:`. (`model` and `tools` exist in VS Code's own prompt-file format but are **not** part of GitHub's documented spec — don't rely on them for portability.)
+- Invoke: type `/<name>` (no extension) in Copilot Chat → `/explain-code`.
+
+```markdown
+---
+agent: 'agent'
+description: 'Generate a clear code explanation with examples'
+---
+
+Explain the selected code. Cover what it does, the non-obvious parts, and one example call.
+```
+
+**Repository custom instructions** (always-on context, not invoked):
+- Repo-wide: `.github/copilot-instructions.md` — plain Markdown, no frontmatter.
+- Path-specific: `.github/instructions/<name>.instructions.md` — frontmatter `applyTo:` (glob, e.g. `applyTo: "app/models/**/*.rb"` or `applyTo: "**"`) and optional `excludeAgent:` (`"code-review"` / `"cloud-agent"`).
+- Copilot code review reads only the first 4,000 characters of an instruction file (other features are unaffected). Keep them tight.
+- `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` are also recognized.
+
+**Variables documented by GitHub:** input variables only — `${input:name}` and `${input:name:placeholder}` (e.g. `${input:code:Paste your code here}`). The `${selection}`, `${file}`, and `${workspaceFolder}` tokens come from VS Code's editor, not GitHub's spec — fine in VS Code, not portable.
+
+## Cursor
+
+**Commands** (lightly documented; Cursor now steers users toward Skills):
+- Location: `.cursor/commands/<name>.md` (project). A user-level form exists but Cursor doesn't publish the exact global path — don't quote one.
+- No documented frontmatter; commands are described simply as reusable prompts.
+- No documented argument/parameter passing.
+- Invoke: type `/` in the Agent input and pick the command.
+
+**Skills (preferred going forward):** `SKILL.md`-based, same shape as the convergence example above. Cursor ships `/migrate-to-skills` to convert commands.
+
+**Rules** (passive context, auto-injected — not invoked like commands):
+- Location: `.cursor/rules/` as `.md` or `.mdc`. Use `.mdc` for frontmatter.
+- Frontmatter: `description` (string), `globs` (file pattern), `alwaysApply` (boolean).
+- Types: **Always** (`alwaysApply: true`), **Agent Requested** (description, no globs — pulled in when relevant), **Auto Attached** (matches `globs`), **Manual** (only via `@`-mention).
+
+## Quick pick
+
+| You want… | Claude Code | GitHub Copilot | Cursor |
+|---|---|---|---|
+| Invoke a saved prompt by name | `.claude/skills/<name>/SKILL.md` → `/name` | `.github/prompts/<name>.prompt.md` → `/name` | `.cursor/commands/<name>.md` → `/name` |
+| Always-on project context | `.claude/skills/` (auto-invoked) or `CLAUDE.md` | `.github/copilot-instructions.md` | `.cursor/rules/*.mdc` |
+| Path-scoped context | `paths:` frontmatter | `.github/instructions/*.instructions.md` (`applyTo`) | `.cursor/rules/*.mdc` (`globs`) |
+
+When in doubt, write a `SKILL.md` — it's the format all three are converging on.