{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/agent-powerups-header-dark.svg\">\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"./assets/agent-powerups-header-light.svg\">\n    <img src=\"./assets/agent-powerups-header-dark.svg\" alt=\"Agent-Powerups\" width=\"100%\">\n  </picture>\n</p>\n\n<h1 align=\"center\">Agent Powerups</h1>\n\n<p align=\"center\">\n  <strong>Oh My Zsh for coding agents.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/agent-powerups/v/latest\">\n    <img alt=\"npm version\" src=\"https://img.shields.io/npm/v/agent-powerups?logo=npm&logoColor=white&label=npm\" />\n  </a>\n  <a href=\"https://www.npmjs.com/package/agent-powerups/v/latest\">\n    <img alt=\"npm weekly downloads\" src=\"https://img.shields.io/npm/dm/agent-powerups?style=flat&logo=npm&logoColor=white&logoSize=auto&cacheSeconds=86400\" />\n  </a>\n  <a href=\"https://github.com/yeaight7/agent-powerups/actions/workflows/ci.yml\">\n    <img alt=\"CI\" src=\"https://github.com/yeaight7/agent-powerups/actions/workflows/ci.yml/badge.svg\" />\n  </a>\n  <a href=\"https://github.com/yeaight7/agent-powerups/releases\">\n    <img alt=\"GitHub release\" src=\"https://img.shields.io/github/v/release/yeaight7/agent-powerups?display_name=tag&logo=github&label=release\" />\n  </a>\n  <a href=\"https://github.com/yeaight7/agent-powerups/blob/main/LICENSE\">\n    <img alt=\"License\" src=\"https://img.shields.io/npm/l/agent-powerups?label=license\" />\n  </a>\n    <img alt=\"Node.js Version\" src=\"https://img.shields.io/node/v/agent-powerups?label=node\" />\n  <a href=\"https://github.com/yeaight7/agent-powerups/stargazers\">\n    <img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yeaight7/agent-powerups?logo=github\" />\n  </a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#quickstart\">Quickstart</a>\n  ·\n  <a href=\"#agent-quickstart\">Agent Quickstart</a>\n  ·\n  <a href=\"#plugins\">Plugins</a>\n  ·\n  <a href=\"./docs/installation.md\">Installation</a>\n  ·\n  <a href=\"./docs/security-model.md\">Security Model</a>\n  ·\n  <a href=\"./CONTRIBUTING.md\">Contributing</a>\n</p>\n\nAgent Powerups is an Oh My Zsh-style collection of reusable skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for coding agents.\n\nToday, this repo ships:\n\n- reusable skills\n- safe local CLI (`apx`) with runnable local checks\n- persistent Gemini relay for always-active secondary-agent delegation\n- validation and requirement-check scripts\n- verified local GitHub MCP check, smoke, and install flow\n- command, hook, workflow, examples, and AGENTS.md templates\n- plugins with native install, marketplace metadata, and `apx plugins` inspection (`apx plugins list`)\n- user-intent profiles with `apx profiles` for curated skill/plugin sets\n\nNative install is direct for humans. Safety boundaries stay around external tools, secrets, shell profiles, and MCP enablement.\n\n## What Is Here\n\n|  Path  | Status | Notes |\n|--------|--------|-------|\n|  `skills/`  | shipped | Reusable agent workflows such as `systematic-debugging` and `writing-plans` |\n|  `mcp/`  | shipped | Local-first GitHub MCP config with check, smoke, and explicit install commands |\n|  `agents-md/`  | shipped | Starter AGENTS.md templates |\n|  `commands/`  | shipped | Review-first command prompts plus safe runnable checks |\n|  `hooks/`  | shipped | Review-before-use hook recipes plus safe runnable checks |\n|  `workflows/`  | shipped | Scenario guides |\n|  `plugins/`  | shipped | Plugins with local-first discovery, validation, native install, and marketplace metadata (`apx plugins list`) |\n|  `scripts/`  | shipped | Validation and tool-check helpers for this repo |\n|  `examples/`  | shipped | Minimal safe setup examples |\n\n## Agent Quickstart\n\nIf you are an agent working in a repo with Agent Powerups available, route tasks to capabilities yourself instead of waiting to be told:\n\n1. **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`.\n2. **Discover the rest** — anything not natively loaded (MCP configs, hooks, AGENTS.md templates, installed-only assets):\n\n   ```sh\n   apx discover \"<the user's task>\" --target <codex|claude-code|gemini|generic> --json\n   apx info <chosen-asset>     # what it is, when to use it, source path, next action\n   ```\n\n3. **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.\n4. **Gate risky assets.** MCP configs and hooks are review-before-use — surface them for approval, never auto-enable.\n\n## Quickstart\n\n### Using npm (Recommended)\n\n```sh\nnpm install -g agent-powerups\napx install claude --full\n```\n\nThis 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.\n\n### Using Source Checkout (Development)\n\n1. Clone and install deps:\n\n```sh\ngit clone https://github.com/yeaight7/agent-powerups.git\ncd agent-powerups\nnpm install\n```\n\n2. Build CLI and install globally:\n\n```sh\nnpm run build\nnpm link\n```\n\n3. Check repo health:\n\n```sh\napx doctor\napx doctor --full\n```\n\n4. Discover relevant powerups and browse the catalog:\n\n```sh\napx discover \"fix a failing test regression\" --target codex\napx inventory --target codex --json\napx list\napx list --json --verbose\napx info markitdown-file-intake\napx commands run ship-check\napx hooks run no-secrets-preflight --all\napx mcp check github-local --target generic\napx mcp smoke github-local --json\napx mcp install github-local --target codex --dry-run\n```\n\n5. Manual native install:\n\n```sh\napx install codex --dry-run\napx install codex\napx install claude\napx install gemini\napx install codex --full\napx install codex --verbose\n```\n\nDefault 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.\n\n6. Work with plugins:\n\n```sh\napx plugins list\napx plugins info dev-vitals\napx plugins validate --all\napx plugins install dev-vitals --target codex --dry-run\n```\n\n6. Try a local advisor CLI and save an artifact:\n\n```sh\napx ask-codex \"Return OK only\" --json\napx ask-claude \"Return OK only\" --json\napx ask-gemini \"Return OK only\" --json\n```\n\n7. Start a persistent relay session (keeps context across turns):\n\n```sh\napx relay init second-opinion\napx relay start second-opinion --provider gemini\napx relay ask second-opinion \"Review this plan\" --json\napx relay status second-opinion\napx relay stop second-opinion\n```\n\n8. Browse profiles:\n\n```sh\napx profiles list\napx profiles info safe-core\napx profiles plan safe-core --target codex\n```\n\n9. Check declared external deps without installing:\n\n```sh\napx check markitdown-file-intake\napx check graphify\n```\n\nUse `apx check` only for assets that declare external requirements. A successful dependency check does not mean the skill or workflow was used correctly.\n\nPreview supported dependency installers before asking for approval:\n\n```sh\napx check defuddle --install-missing --dry-run\napx check markitdown-file-intake --install-missing --dry-run\napx check graphify --install-missing --dry-run\n```\n\n10. Install a single asset explicitly:\n\n```sh\napx install markitdown-file-intake --target codex --dry-run\napx install ask-claude --target codex --dry-run\n```\n\n11. Legacy agent-curated setup compatibility path:\n\n```sh\napx setup codex --dry-run\napx setup codex --mode minimal --yes    # bootstrap only\napx setup codex --mode recommended --yes  # main agent setup (recommended)\napx setup codex --mode full --yes       # broad staging\n```\n\n`apx setup` is legacy compatibility and remains supported through at least `v0.8.0`. Prefer `apx install <agent>` for manual native install.\n\n#### Manual Setup (Primary)\n\n```sh\napx install <codex|claude|claude-code|gemini> [--verbose]\napx install <codex|claude|claude-code|gemini> --full [--verbose]\n```\n\nDefault manual install:\n\n- root `skills/` -> `<agent-root>/skills/`\n- Codex/Claude plugins -> `<agent-root>/plugins/`\n- Gemini plugins -> `<agent-root>/extensions/`\n\n#### Agent-Managed Setup\n\nGive your agent access to this repo and ask it to run:\n\n```sh\napx list\napx profiles list\napx setup <codex|claude-code|gemini> --mode recommended --yes\n```\n\nAgent 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>`.\n\nAgent setup docs:\n\n- [`docs/setup/codex.md`](./docs/setup/codex.md)\n- [`docs/setup/claude-code.md`](./docs/setup/claude-code.md)\n- [`docs/setup/gemini.md`](./docs/setup/gemini.md)\n\n12. Keep repo validation in loop:\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\npython scripts/validate-mirrors.py\npython scripts/check-requirements.py\n```\n\n## Catalog Overview\n\nThe shipped catalog changes often, so it is not enumerated here. Browse it from the CLI — these\nsurfaces are always current:\n\n```sh\napx list                       # compact human browse of everything shipped\napx list --type skill          # filter by category (skill, command, plugin, hook, mcp-config, ...)\napx discover \"<your task>\"     # task-based: what should I use for this?\napx plugins list               # available plugins\napx mcp list                   # available MCP configs\n```\n\nHuman-facing categories: **skills**, **commands**, **plugins**, **MCP configs**, **hooks**, and\n**AGENTS.md templates** (scripts, examples, and workflows are internal). See the taxonomy and\nfield definitions in [`docs/catalog-schema.md`](./docs/catalog-schema.md). Catalog assets also carry\na browsing tier: **core**, **common**, **specialized**, or **experimental**.\n\n## Compatibility Matrix\n\nCompatibility claims in this repo are intentionally narrow:\n\n| Asset class | Shipped today | Compatibility claim |\n|-------------|---------------|---------------------|\n| Root `skills/` | yes | Generic text-based skills; some also mention known agent surfaces |\n| `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 |\n| `agents-md/` | yes | Plain text templates |\n| `commands/` | yes | Review-first markdown command prompts; Claude Code and Codex targets where provided |\n| `hooks/` | yes | Documentation recipes only; not installed automatically |\n| `workflows/` | yes | Plain text scenario guides |\n| `plugins/` | yes | Plugins with native install, marketplace metadata, and `apx plugins` inspection |\n| `scripts/` | yes | Generic Python scripts |\n| `examples/` | yes | Plain text setup examples only |\n\nMore detail: [`docs/compatibility.md`](./docs/compatibility.md)\n\n## Tool Requirements\n\nMost shipped skills are pure text and need no extra installation.\n\nCurrent optional external tools used by shipped skills:\n\n| Skill | Tool | Required | Install |\n|-------|------|----------|---------|\n| `ask-codex` | Codex CLI (`codex`) | yes for local advisor workflow | install/configure Codex CLI |\n| `ask-claude` | Claude Code CLI (`claude`) | yes for local advisor workflow | install/configure Claude Code CLI |\n| `ask-gemini` | Gemini CLI (`gemini`) | yes for local advisor workflow | install/configure Gemini CLI |\n| `markitdown-file-intake` | Microsoft MarkItDown (`markitdown`) | yes for conversion workflow | `python -m pip install markitdown` |\n| `defuddle` | Defuddle CLI (`defuddle`) | yes for Defuddle workflow | `npm install -g defuddle` |\n| `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` |\n| `pr-triage` | GitHub CLI (`gh`) | optional | platform package manager |\n\nTool policy:\n\n- Do not assume tools are installed.\n- Do not auto-install without user approval.\n- Show install command before running it.\n- Prefer user-local or project-local installation where practical.\n\nMore detail: [`docs/tool-requirements.md`](./docs/tool-requirements.md) and [`docs/installation.md`](./docs/installation.md)\n\n## CLI Usage\n\n```sh\nnpm install\nnpm run build\nnpm link\napx doctor\napx doctor --full --json\napx list\napx list --json --verbose\napx inventory --target codex --json\napx discover \"fix a failing test\" --target codex --json\napx info markitdown-file-intake\napx check markitdown-file-intake\napx check graphify\napx ask-codex \"Explain this code\" --json\napx ask-claude \"Review this patch\" --json\napx ask-gemini \"Brainstorm test cases\" --json\napx relay start second-opinion --provider gemini --json\napx relay ask second-opinion \"Review this plan\" --json\napx relay stop second-opinion --json\napx ship-check --json\napx no-secrets-preflight --all --json\napx using-powerups\napx install codex --dry-run\napx install codex\napx install claude\napx install gemini\napx install codex --full\napx install markitdown-file-intake --target codex --dry-run\napx setup codex --dry-run\napx setup claude-code --dry-run\napx setup gemini --dry-run\napx setup codex --mode recommended --yes\napx setup claude-code --mode recommended --yes\napx setup gemini --mode recommended --yes\n```\n\n### Migration note (v0.x)\n\n`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.\n\nExtra surfaces:\n\n```sh\napx mcp list\napx mcp print github-local --target claude-code\napx mcp check github-local --target claude-code --json\napx mcp smoke github-local --json\napx mcp install github-local --target codex --dry-run\napx mcp install github-local --target claude-code --dry-run\napx mcp write github-local --target generic --dest .agent-powerups/github-local.json\napx agents-md list\napx agents-md print typescript-app\napx commands list\napx commands print ship-check --target generic\napx commands run ship-check --full\napx hooks list\napx hooks print no-secrets-preflight\napx hooks run no-secrets-preflight --path README.md\napx workflows list\napx workflows print feature-iteration\napx plugins list\napx plugins info dev-vitals\napx plugins validate --all\napx plugins install dev-vitals --target codex --dry-run\napx profiles list\napx profiles info safe-core\napx profiles plan safe-core --target codex\napx relay init second-opinion\napx relay start second-opinion --provider gemini --json\napx relay ask second-opinion \"Review this plan\" --json\napx relay status second-opinion --json\napx relay stop second-opinion --json\n```\n\nTo explicitly copy a skill into a local Codex-visible folder, choose the destination yourself:\n\n```sh\napx install ask-claude --target codex --dest .agent-powerups/installed/ask-claude\n```\n\n## Plugins\n\nPlugins ship under [`plugins/`](./plugins/). They are registered in both [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json) and [`.codex-plugin/marketplace.json`](./.codex-plugin/marketplace.json). Gemini CLI uses local extensions; each plugin includes `gemini-extension.json` and `GEMINI.md`.\n\n- use `apx plugins list` to discover plugins\n- use `apx plugins info <name>` to inspect a single plugin\n- use `apx plugins info <name> --json` to inspect contained skill, command, agent, and template metadata\n- use `apx plugins validate --all` to verify plugin structure\n- use `apx plugins install <name> --target <codex|claude-code|generic> --dry-run` before any write\n- installed plugins include `discovery-index.json` so contained assets are queryable directly\n- use `apx install <codex|claude|gemini>` for full manual native install\n\n## Safety Warning\n\nReview assets before loading them into a trusted agent environment.\n\n- Skills can instruct an agent to read local files or run commands.\n- Hooks can execute code when supported by the host agent.\n- MCP configs can expand tool access.\n- Install commands can modify the local environment.\n- Secrets should never be pasted into agent context unless strictly necessary.\n\nSee [`SECURITY.md`](./SECURITY.md) and [`docs/security-model.md`](./docs/security-model.md).\n\n## Contributing\n\nContribution guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md)\n\nAcknowledgements: [`ACKNOWLEDGEMENTS.md`](./ACKNOWLEDGEMENTS.md)\n\nMCP configs: [`docs/mcp-configs.md`](./docs/mcp-configs.md)\n\nRoadmap: [`roadmap.md`](./docs/roadmap.md)\n",
  "bytes": 16900,
  "sha": "3b84bc22197885532b86297baad6ed7d549a5fe2a51f9ebe7dd56420bb1b1ca3",
  "repo_slug": "yeaight7/agent-powerups",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_yeaight7_agent_powerups_f10fa52e/readme"
}