Agent Powerups is an Oh My Zsh-style collection of reusable skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for coding agents.
Today, this repo ships:
- reusable skills
- safe local CLI (
apx) with runnable local checks
- persistent Gemini relay for always-active secondary-agent delegation
- validation and requirement-check scripts
- verified local GitHub MCP check, smoke, and install flow
- command, hook, workflow, examples, and AGENTS.md templates
- plugins with native install, marketplace metadata, and
apx plugins inspection (apx plugins list)
- user-intent profiles with
apx profiles for curated skill/plugin sets
Native install is direct for humans. Safety boundaries stay around external tools, secrets, shell profiles, and MCP enablement.
What Is Here
| Path | Status | Notes |
|---|
skills/ | shipped | Reusable agent workflows such as systematic-debugging and writing-plans |
mcp/ | shipped | Local-first GitHub MCP config with check, smoke, and explicit install commands |
agents-md/ | shipped | Starter AGENTS.md templates |
commands/ | shipped | Review-first command prompts plus safe runnable checks |
hooks/ | shipped | Review-before-use hook recipes plus safe runnable checks |
workflows/ | shipped | Scenario guides |
plugins/ | shipped | Plugins with local-first discovery, validation, native install, and marketplace metadata (apx plugins list) |
scripts/ | shipped | Validation and tool-check helpers for this repo |
examples/ | shipped | Minimal safe setup examples |
Agent Quickstart
If you are an agent working in a repo with Agent Powerups available, route tasks to capabilities yourself instead of waiting to be told:
-
Match first. On Claude Code the host already lists skills natively — match the task to the narrowest fitting skill (plus obvious fits like no-fluff). On Codex, Gemini, or generic agents, start with apx discover.
-
Discover the rest — anything not natively loaded (MCP configs, hooks, AGENTS.md templates, installed-only assets):
apx discover "<the user's task>" --target <codex|claude-code|gemini|generic> --json
apx info <chosen-asset> # what it is, when to use it, source path, next action
-
Read, apply, verify. Read the asset's SKILL.md (or file) before applying it; run apx check <asset> only if it declares external requirements; then verify the result against the task.
-
Gate risky assets. MCP configs and hooks are review-before-use — surface them for approval, never auto-enable.
Quickstart
Using npm (Recommended)
npm install -g agent-powerups
apx install claude --full
This installs the apx CLI globally and runs a full Claude Code setup — copies skills, plugins, and commands into ~/.claude/ and patches your CLAUDE.md. Use --dry-run to preview changes first.
Using Source Checkout (Development)
- Clone and install deps:
git clone https://github.com/yeaight7/agent-powerups.git
cd agent-powerups
npm install
- Build CLI and install globally:
npm run build
npm link
- Check repo health:
apx doctor
apx doctor --full
- Discover relevant powerups and browse the catalog:
apx discover "fix a failing test regression" --target codex
apx inventory --target codex --json
apx list
apx list --json --verbose
apx info markitdown-file-intake
apx commands run ship-check
apx hooks run no-secrets-preflight --all
apx mcp check github-local --target generic
apx mcp smoke github-local --json
apx mcp install github-local --target codex --dry-run
- Manual native install:
apx install codex --dry-run
apx install codex
apx install claude
apx install gemini
apx install codex --full
apx install codex --verbose
Default native install copies all root skills and plugins into the selected agent root and writes a discovery-index.json beside them. Human output shows counts by default; use --verbose for per-file paths. If installed Agent Powerups guidance or discovery indexes are stale, apx install <agent> refreshes them by default. --full also stages support assets and another discovery index under agent-powerups/, then updates existing global instructions with a backup.
- Work with plugins:
apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target codex --dry-run
- Try a local advisor CLI and save an artifact:
apx ask-codex "Return OK only" --json
apx ask-claude "Return OK only" --json
apx ask-gemini "Return OK only" --json
- Start a persistent relay session (keeps context across turns):
apx relay init second-opinion
apx relay start second-opinion --provider gemini
apx relay ask second-opinion "Review this plan" --json
apx relay status second-opinion
apx relay stop second-opinion
- Browse profiles:
apx profiles list
apx profiles info safe-core
apx profiles plan safe-core --target codex
- Check declared external deps without installing:
apx check markitdown-file-intake
apx check graphify
Use apx check only for assets that declare external requirements. A successful dependency check does not mean the skill or workflow was used correctly.
Preview supported dependency installers before asking for approval:
apx check defuddle --install-missing --dry-run
apx check markitdown-file-intake --install-missing --dry-run
apx check graphify --install-missing --dry-run
- Install a single asset explicitly:
apx install markitdown-file-intake --target codex --dry-run
apx install ask-claude --target codex --dry-run
- Legacy agent-curated setup compatibility path:
apx setup codex --dry-run
apx setup codex --mode minimal --yes # bootstrap only
apx setup codex --mode recommended --yes # main agent setup (recommended)
apx setup codex --mode full --yes # broad staging
apx setup is legacy compatibility and remains supported through at least v0.8.0. Prefer apx install <agent> for manual native install.
Manual Setup (Primary)
apx install <codex|claude|claude-code|gemini> [--verbose]
apx install <codex|claude|claude-code|gemini> --full [--verbose]
Default manual install:
- root
skills/ -> <agent-root>/skills/
- Codex/Claude plugins ->
<agent-root>/plugins/
- Gemini plugins ->
<agent-root>/extensions/
Agent-Managed Setup
Give your agent access to this repo and ask it to run:
apx list
apx profiles list
apx setup <codex|claude-code|gemini> --mode recommended --yes
Agent will inspect available skills/plugins, propose a plan, and apply it. This is the legacy compatibility path for agent-curated setup; manual setup should use apx install <agent>.
Agent setup docs:
- Keep repo validation in loop:
python scripts/validate-skills.py
python scripts/validate-catalog.py
python scripts/validate-mirrors.py
python scripts/check-requirements.py
Catalog Overview
The shipped catalog changes often, so it is not enumerated here. Browse it from the CLI — these
surfaces are always current:
apx list # compact human browse of everything shipped
apx list --type skill # filter by category (skill, command, plugin, hook, mcp-config, ...)
apx discover "<your task>" # task-based: what should I use for this?
apx plugins list # available plugins
apx mcp list # available MCP configs
Human-facing categories: skills, commands, plugins, MCP configs, hooks, and
AGENTS.md templates (scripts, examples, and workflows are internal). See the taxonomy and
field definitions in docs/catalog-schema.md. Catalog assets also carry
a browsing tier: core, common, specialized, or experimental.
Compatibility Matrix
Compatibility claims in this repo are intentionally narrow:
| Asset class | Shipped today | Compatibility claim |
|---|
Root skills/ | yes | Generic text-based skills; some also mention known agent surfaces |
mcp/ | yes | MCP configs for local and remote servers (GitHub, Supabase, Vercel, Cloudflare, Exa, Atlassian, Browserbase, E2B, and more); github-local has a full check/smoke/install flow |
agents-md/ | yes | Plain text templates |
commands/ | yes | Review-first markdown command prompts; Claude Code and Codex targets where provided |
hooks/ | yes | Documentation recipes only; not installed automatically |
workflows/ | yes | Plain text scenario guides |
plugins/ | yes | Plugins with native install, marketplace metadata, and apx plugins inspection |
scripts/ | yes | Generic Python scripts |
examples/ | yes | Plain text setup examples only |
More detail: docs/compatibility.md
Tool Requirements
Most shipped skills are pure text and need no extra installation.
Current optional external tools used by shipped skills:
| Skill | Tool | Required | Install |
|---|
ask-codex | Codex CLI (codex) | yes for local advisor workflow | install/configure Codex CLI |
ask-claude | Claude Code CLI (claude) | yes for local advisor workflow | install/configure Claude Code CLI |
ask-gemini | Gemini CLI (gemini) | yes for local advisor workflow | install/configure Gemini CLI |
markitdown-file-intake | Microsoft MarkItDown (markitdown) | yes for conversion workflow | python -m pip install markitdown |
defuddle | Defuddle CLI (defuddle) | yes for Defuddle workflow | npm install -g defuddle |
graphify | Upstream Graphify CLI + Python package (graphify, graphifyy) | yes for graph workflow | uv tool install graphifyy or pipx install graphifyy or python -m pip install graphifyy |
pr-triage | GitHub CLI (gh) | optional | platform package manager |
Tool policy:
- Do not assume tools are installed.
- Do not auto-install without user approval.
- Show install command before running it.
- Prefer user-local or project-local installation where practical.
More detail: docs/tool-requirements.md and docs/installation.md
CLI Usage
npm install
npm run build
npm link
apx doctor
apx doctor --full --json
apx list
apx list --json --verbose
apx inventory --target codex --json
apx discover "fix a failing test" --target codex --json
apx info markitdown-file-intake
apx check markitdown-file-intake
apx check graphify
apx ask-codex "Explain this code" --json
apx ask-claude "Review this patch" --json
apx ask-gemini "Brainstorm test cases" --json
apx relay start second-opinion --provider gemini --json
apx relay ask second-opinion "Review this plan" --json
apx relay stop second-opinion --json
apx ship-check --json
apx no-secrets-preflight --all --json
apx using-powerups
apx install codex --dry-run
apx install codex
apx install claude
apx install gemini
apx install codex --full
apx install markitdown-file-intake --target codex --dry-run
apx setup codex --dry-run
apx setup claude-code --dry-run
apx setup gemini --dry-run
apx setup codex --mode recommended --yes
apx setup claude-code --mode recommended --yes
apx setup gemini --mode recommended --yes
Migration note (v0.x)
apx install <agent> is now the primary manual install path and writes native skills/plugins by default. apx setup <agent> is legacy compatibility for agent-curated setup, remains dry-run by default unless --yes is passed, and remains supported through at least v0.8.0; removal or aliasing requires a separate batch.
Extra surfaces:
apx mcp list
apx mcp print github-local --target claude-code
apx mcp check github-local --target claude-code --json
apx mcp smoke github-local --json
apx mcp install github-local --target codex --dry-run
apx mcp install github-local --target claude-code --dry-run
apx mcp write github-local --target generic --dest .agent-powerups/github-local.json
apx agents-md list
apx agents-md print typescript-app
apx commands list
apx commands print ship-check --target generic
apx commands run ship-check --full
apx hooks list
apx hooks print no-secrets-preflight
apx hooks run no-secrets-preflight --path README.md
apx workflows list
apx workflows print feature-iteration
apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target codex --dry-run
apx profiles list
apx profiles info safe-core
apx profiles plan safe-core --target codex
apx relay init second-opinion
apx relay start second-opinion --provider gemini --json
apx relay ask second-opinion "Review this plan" --json
apx relay status second-opinion --json
apx relay stop second-opinion --json
To explicitly copy a skill into a local Codex-visible folder, choose the destination yourself:
apx install ask-claude --target codex --dest .agent-powerups/installed/ask-claude
Plugins
Plugins ship under plugins/. They are registered in both .claude-plugin/marketplace.json and .codex-plugin/marketplace.json. Gemini CLI uses local extensions; each plugin includes gemini-extension.json and GEMINI.md.
- use
apx plugins list to discover plugins
- use
apx plugins info <name> to inspect a single plugin
- use
apx plugins info <name> --json to inspect contained skill, command, agent, and template metadata
- use
apx plugins validate --all to verify plugin structure
- use
apx plugins install <name> --target <codex|claude-code|generic> --dry-run before any write
- installed plugins include
discovery-index.json so contained assets are queryable directly
- use
apx install <codex|claude|gemini> for full manual native install
Safety Warning
Review assets before loading them into a trusted agent environment.
- Skills can instruct an agent to read local files or run commands.
- Hooks can execute code when supported by the host agent.
- MCP configs can expand tool access.
- Install commands can modify the local environment.
- Secrets should never be pasted into agent context unless strictly necessary.
See SECURITY.md and docs/security-model.md.
Contributing
Contribution guide: CONTRIBUTING.md
Acknowledgements: ACKNOWLEDGEMENTS.md
MCP configs: docs/mcp-configs.md
Roadmap: roadmap.md
