Skip to content

AGENTS.md

Latest commit

 

History

History
153 lines (102 loc) · 7.37 KB

AGENTS.md

File metadata and controls

153 lines (102 loc) · 7.37 KB
Raw

AGENTS.md

🎯 SKILLS

Skills extend your capabilities with proven workflows.

Discover Skills First

Before starting any task, check for relevant skills:

  1. Use your native skill tool to list available skills.
  2. Review skill descriptions/frontmatter to identify relevant ones.

Skill Loading Rules

  • Load skills JIT only — never preload to "understand" them.
  • Follow skill instructions exactly as written — no skimming, no shortcuts.
  • If a skill has a checklist, create a todo for each item — no mental tracking.
  • Simple tasks benefit from skills as much as complex ones.

Skill priority (highest to lowest): Project → Personal

Using Tools with Skills

  1. Native skill tool — load skills via your platform's native skill tool.
  2. Symlinked skills — Superpowers skills are symlinked into your platform's skills directory.
  3. Fallback — if a skill isn't found via the native tool, inspect the configured skill directories and read its SKILL.md directly.
  4. Tool equivalence — when a skill references a tool you don't have, substitute your equivalent.

Why Skills Matter

Skills encode proven techniques that prevent mistakes. Not using them means repeating solved problems and missing edge cases.

If a skill exists for your task, you MUST use it.

Version Check

Periodically, e.g. once per day check the version of superpowers-agent:

  1. CURRENT_VERSION — run a superpowers-agent command and extract X.Y.Z from the ^^SAV:X.Y.Z^^ string in its output.
  2. NPM_LATEST_VERSION — run npm view @complexthings/superpowers-agent version.
  3. Compare by semver precedence, not string comparison (e.g. 9.10.0 > 9.9.0). If NPM_LATEST_VERSION is newer, tell the user — do not run these yourself:

    Your superpowers-agent has updates (CURRENT_VERSION → NPM_LATEST_VERSION). Run:

    npm install -g @complexthings/superpowers-agent
superpowers-agent bootstrap && superpowers-agent setup-skills
    If versions match, or either lookup fails (e.g. no network), continue silently.

Generated by Superpowers on 2026-07-12

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:

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

Run the automated test suite from .agents with bun test. There is no root-level test script; run CLI commands directly for manual acceptance checks.

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, session-context [--format=claude|copilot|raw]
  • 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
  • Native skill tools → discover and load skills from their configured directories
  • 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.

@RTK.md