@complexthings/superpowers-agent 8.4.1 → 9.0.0

package/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+<!-- SUPERPOWERS_-_INSTRUCTIONS_START -->
+${content}
+<!-- SUPERPOWERS_-_INSTRUCTIONS_END -->

package/.github/workflows/main.yaml

@@ -30,4 +30,4 @@ jobs:
       - name: Publish to npm
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish --access public
+        run: npm publish --access public

package/AGENTS.md

@@ -58,3 +58,100 @@ Skills encode proven techniques that prevent mistakes. Not using them means repe
 
 <!-- SUPERPOWERS_SKILLS_END -->
 
+## What This Project Is
+
+**Superpowers Agent** is a CLI (`superpowers-agent`, alias `superpowers`) that manages reusable markdown-based "skills" for AI coding assistants. It delivers skills to Claude, GitHub Copilot, Cursor, Gemini, OpenCode, and Codex. Skills live in `skills/` (this repo) and `.agents/skills/`, and bootstrap symlinks them into each assistant's config directory. Published to npm as `@complexthings/superpowers-agent`.
+
+## Build & Development
+
+The CLI source lives in `.agents/` and is built with **Bun** (`packageManager: bun@1.3.8`). Run scripts from the `.agents/` directory:
+
+```bash
+cd .agents
+bun run build            # Build minified ESM bundle → .agents/superpowers-agent
+bun run watch            # Build in watch mode
+bun run dev              # Run CLI from source (bun src/cli.js)
+bun run dev:link         # Symlink the `superpowers-agent` bin to the dev source
+bun run production:link  # Symlink the bin to the built bundle
+```
+
+The build (`.agents/build.js`) uses the `Bun.build` API, so it must run under **bun**, not node. Output is `.agents/superpowers-agent` — a polyglot shebang script that execs `bun` if present, otherwise `node`.
+
+The CLI has **no runtime dependencies** (pure Node.js/Bun built-ins). The only dev dependency is `husky`. Node engines: `^20 || ^22 || ^24`.
+
+## Testing
+
+There is **no automated test runner** and no `test` script. Verification is manual: run the CLI commands directly, or drive the saved prompt scenarios in `.agents/prompts/`. State this plainly rather than inventing a test command.
+
+## Architecture
+
+### Source (`.agents/src/`)
+
+| Layer | Files | Responsibility |
+|-------|-------|---------------|
+| CLI entry | `cli.js` | Command dispatch table |
+| Commands | `commands/bootstrap.js`, `update.js`, `simple-commands.js` | Command implementations |
+| Core | `core/config.js`, `paths.js`, `platform-detection.js`, `git.js` | Config, path resolution, platform detection, git helpers |
+| Skills | `skills/finder.js`, `locator.js`, `installer.js`, `executor.js`, `parser.js` | Skill discovery, install, execution pipeline |
+| Agents | `agents/installer.js`, `agents/platforms.js` | Install agent definitions (`.github/agents/*.agent.md`, `.opencode/agents/*.md`) into platform dirs |
+| Integrations | `integrations/claude.js`, `codex.js`, `copilot.js`, `cursor.js`, `gemini.js`, `opencode.js` | Per-platform symlink/config setup |
+| Utils | `utils/symlinks.js`, `frontmatter.js`, `output.js`, `file-ops.js` | Shared helpers |
+
+### Skill Discovery Priority (highest → lowest)
+
+1. `.agents/skills/` — project-level
+2. `~/.agents/skills/` — personal cross-project
+3. `~/.agents/superpowers/skills/` — bundled community skills
+
+### CLI Commands
+
+From `.agents/src/cli.js` dispatch table:
+
+- **Core:** `bootstrap [--no-update] [--force]`, `version`, `check-updates`, `update [--no-reinstall]`
+- **Config:** `config-get`, `config-set <key> <value>`
+- **Skills:** `setup-skills`, `find-skills [pattern]`, `use-skill <name>`, `execute <name>`, `dir <name>`, `path <name>`, `get-helpers <skill> <search-term>`
+- **Install/manage skills:** `add <url-or-path|@alias> [path]`, `add-repository <git-url> [--as=@alias]`, `list-repositories`, `pull <url-or-path|@alias>`, `rm <url-or-path|@alias>`
+- **Integrations:** `install-cursor-hooks`, `install-aliases`
+
+### Key Flows
+
+- **`bootstrap`** → detects installed AI platforms → symlinks skills into each platform's skills dir → writes platform config files
+- **`find-skills [pattern]`** → searches all three skill tiers → returns name/path/description
+- **`execute <skill-name>`** → locates skill → outputs SKILL.md content for the agent to follow
+- **`add <url-or-path|@alias>`** → clones a git repo or copies a local path → installs skills into `~/.agents/superpowers/skills/`
+- **`update`** → checks the npm registry for a newer version → reports if an update is available
+
+### Skill Structure
+
+Each skill is a directory with a `SKILL.md` file:
+
+```
+skills/
+└── <category>/
+    └── <skill-name>/
+        ├── SKILL.md         # Frontmatter (name, description) + instructions
+        ├── scripts/         # Optional support scripts
+        └── resources/       # Optional templates/data
+```
+
+`SKILL.md` frontmatter fields: `name`, `description`, and optional `metadata` (e.g. `version`). The set of bundled skills and their lockfile state are tracked in `skill.json` and `skills-lock.json` at the repo root.
+
+## Versioning & Publishing
+
+The `.husky/pre-commit` hook keeps the root `package.json` and `.agents/package.json` versions in sync: on commit it picks the higher of the two, writes both, refreshes lockfiles, rebuilds the bundle (`cd .agents && bun install && bun run build`), and stages the affected files. Don't hand-edit one version without the other.
+
+The package is published to npm as `@complexthings/superpowers-agent` (registry auth via the `COMPLEX_THINGS_NPM_TOKEN` in `.npmrc`). The current version is whatever `package.json` reports — do not hardcode it elsewhere.
+
+## Agent skills
+
+### Issue tracker
+
+Issues and PRDs are tracked as GitHub issues on `complexthings/superpowers`, managed via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical triage roles use their default label strings (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root (created lazily). See `docs/agents/domain.md`.

package/README.md

@@ -2,10 +2,19 @@
 
 A comprehensive skills library of proven techniques, patterns, and workflows for AI coding assistants.
 
-**This is a fork and extension of Jesse Vincent's incredible [Superpowers for Claude Code](https://github.com/obra/superpowers).** Jesse's groundbreaking work and [his amazing blog post](https://blog.fsck.com/2025/10/09/superpowers/) introduced the concept of systematic, reusable skills for AI agents. This fork extends that vision to support agent-agnostic workflows across GitHub Copilot, Cursor, Gemini, and other AI coding assistants.
+**This is a fork and extension of Jesse Vincent's incredible [Superpowers for Claude Code](https://github.com/obra/superpowers).** Jesse's groundbreaking work and [his amazing blog post](https://blog.fsck.com/2025/10/09/superpowers/) introduced the concept of systematic, reusable skills for AI agents. This fork extends that vision to support agent-agnostic workflows across GitHub Copilot, Claude Code, and OpenCode.
 
 ## What's New
 
+**v9.0.0 (May 28, 2026):**
+
+- **Claude persona installation** — `.claude/agents/<name>.md` personas now install into `~/.claude/agents/` via `add`/`pull` (previously silently skipped)
+- ⚠️ **No more `postinstall`** — the npm `postinstall` script was removed for supply-chain hardening. Fresh installs now require a **one-time manual** `superpowers-agent bootstrap`; `superpowers-agent update` self-runs bootstrap thereafter
+- ⚠️ **Removed Cursor, Codex & Gemini support** — supported platforms are now **GitHub Copilot, Claude Code, and OpenCode** only. Integration modules, detection, the `install-cursor-hooks` command, and `GEMINI.md` generation were removed
+- ⚠️ **Skills live only in `~/.agents/skills`** — per-platform skill symlinking has been removed. A one-time `skill.json`-gated cleaner runs during `bootstrap` to scrub deprecated symlink directories (including legacy Cursor/Codex/Gemini) without touching agent personas
+- **Fixed `copilot-instructions.md`** — `setup-skills` now correctly creates and idempotently updates `.github/copilot-instructions.md`
+- **`bun test` harness** — added a Bun test runner, smoke test, and `test` script following the `.agents/tests/<feature>.test.js` convention
+
 **v8.4.0 (April 6, 2026):**
 
 - **`superpowers-agent rm` command** — new CLI command for removing installed skills and agents from your system
@@ -77,7 +86,7 @@ A comprehensive skills library of proven techniques, patterns, and workflows for
 - **Utility Commands** - `find-skills` to discover available skills, `execute` to load them
 
 Plus:
-- **Universal Prompts** - Work across Claude, GitHub Copilot, Cursor, Gemini, and other AI assistants
+- **Universal Skills** - Work across GitHub Copilot, Claude Code, and OpenCode
 - **Automatic Integration** - Skills activate automatically when relevant
 - **Consistent Workflows** - Systematic approaches to common engineering tasks
 
@@ -85,13 +94,15 @@ Plus:
 
 ## Quick Install (Recommended)
 
-Install Superpowers globally with one command:
+Install Superpowers globally and run the required one-time bootstrap step:
 
 ```bash
 npm install -g @complexthings/superpowers-agent
 superpowers-agent bootstrap
 ```
 
+> **Note:** `superpowers-agent bootstrap` is a **required** one-time step after every fresh install. It is no longer run automatically by npm's `postinstall` hook — you must run it manually. Subsequent `superpowers-agent update` calls will run bootstrap for you automatically.
+
 ## Migration to Superpower Agent `^8.0.0`
 
 ```bash
@@ -273,90 +284,28 @@ superpowers-agent add https://github.com/example/agents-repo.git
 superpowers-agent pull @my-agents
 ```
 
-### Skill Symlinks for IDE Integration
-
-Superpowers automatically creates symlinks to make skills available to all major AI coding assistants in their native skill directories.
-
-**How it works:**
-
-When you run `superpowers-agent bootstrap` or `superpowers-agent setup-skills`:
-
-1. **Global symlinks** (via `bootstrap`) sync skills to user-level directories:
-   - `~/.claude/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.copilot/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.config/opencode/skill/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.cursor/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.gemini/skills/superpowers` -> `~/.agents/superpowers/skills/`
-   - `~/.codex/skills/superpowers` -> `~/.agents/superpowers/skills/`
-
-2. **Project symlinks** (via `setup-skills`) sync project skills to agent directories:
-   - `.claude/skills` -> `.agents/skills`
-   - `.github/skills` -> `.agents/skills`
-   - `.opencode/skill` -> `.agents/skills`
-   - `.cursor/skills` -> `.agents/skills`
-   - `.gemini/skills` -> `.agents/skills`
-   - `.codex/skills` -> `.agents/skills`
+### Skill Storage
 
-3. **Personal skills** (installed via `superpowers-agent add`) are symlinked individually to all platforms.
+As of v9.0.0, Superpowers no longer creates per-platform skill symlinks. Skills live in just two canonical locations and the supported agents discover them there directly:
 
-**Behavior:**
-- Symlinks are only created if the parent directory exists
-- Use `--force` flag to create parent directories: `superpowers-agent bootstrap --force`
-- Use `--force-<agent>` flags to re-install only specific agent integrations (e.g. `--force-copilot`, `--force-cursor`, `--force-claude`)
-- Symlinks are tracked in `~/.agents/config.json` for management
+- **Global skills** — bundled Superpowers skills in `~/.agents/superpowers/skills/` and personal skills in `~/.agents/skills/`
+- **Project skills** — `.agents/skills/` inside a project (created/managed by `setup-skills`)
 
-**Windows Notes:**
+**Stale symlink cleanup:**
 
-On Windows, symlinks require either:
-- Developer Mode enabled (Settings > Update & Security > For developers)
-- Running as administrator
-
-If symlink creation fails on Windows, you'll see a warning with instructions.
-
-**Configuration:**
-```json
-// ~/.agents/config.json
-{
-  "symlinks": {
-    "claude": {
-      "superpowers": "~/.claude/skills/superpowers",
-      "skills": ["~/.claude/skills/my-skill"]
-    },
-    "copilot": {
-      "superpowers": "~/.copilot/skills/superpowers",
-      "skills": []
-    },
-    "opencode": {
-      "superpowers": "~/.config/opencode/skill/superpowers",
-      "skills": []
-    },
-    "cursor": {
-      "superpowers": "~/.cursor/skills/superpowers",
-      "skills": []
-    },
-    "gemini": {
-      "superpowers": "~/.gemini/skills/superpowers",
-      "skills": []
-    },
-    "codex": {
-      "superpowers": "~/.codex/skills/superpowers",
-      "skills": []
-    }
-  }
-}
-```
+A one-time, `skill.json`-gated cleaner runs during `superpowers-agent bootstrap`. It scrubs deprecated per-platform skill symlink directories left behind by older versions — including legacy Cursor, Codex, and Gemini directories — without touching agent personas in `~/.claude/agents/` or the supported platforms.
 
-## Slash Commands & Skill Priority
+## Skill Priority
 
-Superpowers delivers skills as symlinks into each agent's native skill directory. Each agent discovers and loads skills using its native skill tool — no separate prompt/command files are installed.
+Each supported agent discovers and loads skills using its native skill tool. No separate prompt/command files are installed.
 
 **Skill priority pipeline (first match wins):**
-1. `./skills/` or `.agents/skills/` inside the workspace (project-specific overrides)
+1. `.agents/skills/` inside the workspace (project-specific overrides)
 2. `.claude/skills/` inside the repo if present (repo-wide Claude overrides)
 3. Personal skills in `~/.agents/skills/` (user-level customizations)
 4. Bundled Superpowers skills in `~/.agents/superpowers/skills/` (system defaults)
 
-When any agent invokes a skill — no matter which tool it originates from — the CLI enforces the ordering above. Add a `brainstorming` skill under `./skills/` and every tool immediately picks it up without modifying any prompt files.
+When any agent invokes a skill — no matter which supported tool it originates from — the CLI enforces the ordering above. Add a `brainstorming` skill under `.agents/skills/` and every supported tool immediately picks it up.
 
 ### OpenCode
 
@@ -364,22 +313,11 @@ Skills are available via OpenCode's native `skill` tool. The `.opencode/plugins/
 
 ### GitHub Copilot
 
-Skills are available via the native skill tool. 
-
-### Cursor
-
-Skills are available via the native skill tool. 
-### Gemini
-
-Skills are available via the native skill tool. 
+Skills are available via the native skill tool.
 
 ### Claude Code
 
-Skills are available via the native skill tool. 
-
-### Codex
-
-Skills are available via the native skill tool. 
+Skills are available via the native skill tool. Claude agent personas defined in `.claude/agents/<name>.md` are installed into `~/.claude/agents/` via `add`/`pull`.
 
 ## What's Inside
 
@@ -450,7 +388,7 @@ The `tests/` directory contains agent-agnostic test scripts for validating skill
 ./tests/skill-triggering/run-all.sh
 
 # Configure for your agent
-export AGENT_CLI="opencode"  # or "claude", "cursor", etc.
+export AGENT_CLI="opencode"  # or "claude", "copilot", etc.
 ./tests/skill-triggering/run-test.sh prompts/test-name.txt
 ```
 
@@ -609,7 +547,7 @@ superpowers-agent add @baici
 1. **Bootstrap Process** - Installs agent integrations and syncs skill symlinks globally
 2. **Skill Discovery** - Finds skills across system, personal, and project locations
 3. **Priority Resolution** - Project skills override personal skills override system skills
-4. **Universal Integration** - Works with OpenCode, GitHub Copilot, Cursor, Gemini, and other AI assistants
+4. **Universal Integration** - Works with GitHub Copilot, Claude Code, and OpenCode
 
 **For OpenCode:**
 1. **Plugin System** - The `.opencode/plugins/superpowers-agent.js` plugin injects bootstrap context dynamically at session start
@@ -667,11 +605,11 @@ Use `--force-<agent>` flags to target individual agents without running the full
 # Re-install only GitHub Copilot integration
 superpowers-agent bootstrap --force-copilot
 
-# Re-install Copilot and Gemini together
-superpowers-agent bootstrap --force-copilot --force-gemini
+# Re-install Copilot and Claude together
+superpowers-agent bootstrap --force-copilot --force-claude
 ```
 
-Supported flags: `--force-copilot`, `--force-cursor`, `--force-codex`, `--force-gemini`, `--force-claude`, `--force-opencode`
+Supported flags: `--force-copilot`, `--force-claude`, `--force-opencode`
 
 > When `--force-<agent>` flags are used, universal alias installation and `AGENTS.md` platform generation are skipped. Skill symlink sync still runs. If the agent's directory does not exist (e.g. `~/.copilot`), it will be created automatically.
 
@@ -725,7 +663,7 @@ This project builds on [Jesse Vincent's Superpowers for Claude Code](https://git
 - OpenCode plugin architecture pattern
 - Test infrastructure for skill validation
 
-This fork extends that vision to support agent-agnostic workflows across multiple AI coding assistants including GitHub Copilot, Cursor, Gemini, OpenCode, and Codex.
+This fork extends that vision to support agent-agnostic workflows across GitHub Copilot, Claude Code, and OpenCode.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@complexthings/superpowers-agent",
-  "version": "8.4.1",
+  "version": "9.0.0",
   "description": "Superpowers agent CLI — skills system for AI coding agents",
   "type": "module",
   "bin": {
@@ -25,9 +25,7 @@
   "engines": {
     "node": "^20 || ^22 || ^24"
   },
-  "scripts": {
-    "postinstall": "node .agents/superpowers-agent bootstrap --no-update 2>/dev/null || true"
-  },
+  "scripts": {},
   "author": {
     "name": "Greg Harvell",
     "email": "greg.harvell@complexthings.com",

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"
+  ]
+}