/using-powerups

name: using-powerups
description: Use when starting work in a repository with Agent Powerups installed, when a task may match a reusable local skill, command, workflow, hook recipe, AGENTS.md template, or MCP feature.

Using Powerups

Purpose

Find and apply installed Agent Powerups before improvising. A powerup is useful only after you discover likely matches, inspect the actual asset, follow its instructions, and verify the user task with task-specific evidence.

When to Use

Use at the start of non-trivial work, and again when the task changes shape.

Use when the user asks for debugging, planning, review, setup, file intake, cleanup, PR triage, second opinions, MCP config, hooks, commands, or AGENTS.md templates.

Do not force a powerup when none fits. Say no matching powerup applies and proceed normally.

Inputs

• User task.
• Current repo or agent root.
• Installed `agent-powerups` location, usually `agent-powerups/` under the agent root or the package repo.
• Optional CLI access to `apx` for discovery and inventory.
• Optional installed discovery index file; treat it as a derived snapshot, not the source of truth.

Workflow

1. Discover or match available assets.

Use target-specific routing:

• Claude Code: start with native skill discovery when skills are already exposed by the host. Use `apx discover` when the task is uncertain, when no native skill clearly fits, or when the task may need non-skill assets.
• Codex, Gemini, and generic agents: start with `apx discover`.
• All targets: use `apx inventory` for MCP configs, hooks, AGENTS.md templates, plugin-contained assets, staged assets, and installed-only assets.

apx discover "<user task>" --target <codex|claude-code|gemini|generic>
apx inventory --target <codex|claude-code|gemini|generic> --json
apx list --json --verbose
apx plugins list

If `apx` is unavailable, inspect local folders: `skills/`, `commands/`, `mcp/`, `agents-md/`, `hooks/`, `workflows/`.

2. Match the task to assets.

Prefer the narrowest high-ranked asset whose description matches the current task. Treat `apx discover` output as a shortlist, not as proof that a powerup has been used.

Examples:

| Task signal | Asset type to inspect | | --- | --- | | bug, failing test, regression | debugging skill | | implementation spec | planning skill | | file or URL intake | file-intake skill | | pre-handoff validation | command | | local MCP setup | MCP config | | repo instruction baseline | AGENTS.md template |

3. Read before using.

For a candidate asset:

apx info <name>

Then read the asset file. Do not rely only on the catalog summary.

Most powerups do not require step 4. Only use `apx check` when the asset declares external requirements or its own instructions say a dependency check is needed. Do not run `apx check` for every asset by default.

4. Check requirements.

If `apx check` reports a missing command or package, stop and say exactly what is missing. Use `apx check <asset> --install-missing --dry-run` to preview supported installers. Ask before running `--install-missing --yes`. Do not pretend conversion, fetch, review, or CLI delegation happened when the tool was unavailable.

5. Apply conservatively.

Follow the asset instructions. Keep scope local to the user task. For GitHub MCP, use `apx mcp check github-local`, `apx mcp smoke github-local`, then `apx mcp install github-local --target <agent> --dry-run` before any `--yes` install. For hooks, treat recipes as review-before-use; do not enable them automatically.

6. Report use.

Final response should name:

• powerup used
• requirement check result, or `not needed`
• important fallback or skipped asset
• task-specific validation performed

Output

When a powerup applies:

Used: <asset-name>
Why: <task signal>
Requirements: <OK / missing / not needed>
Result: <how it changed the work>
Validation: <real task-specific checks, not apx check>

When none applies:

No matching Agent Powerup found. Proceeded with normal repo inspection.

Verification

Before claiming setup or use succeeded:

• Asset was read, not guessed from name.
• Requirements were checked only when the selected asset declared external dependencies.
• Missing tools were reported, not bypassed silently.
• `apx check` output was not presented as proof that the skill was used or the task succeeded.
• No secrets were written.
• No global config, shell profile, hook, MCP server, or dependency install was changed without explicit user approval.

Failure Modes

• **Catalog missing**: inspect local asset folders directly, then report that `apx` catalog discovery failed.
• **Missing dependency**: stop that asset path; ask before install; use a lower-capability fallback if safe.
• **No matching asset**: say so and continue normally.
• **Unsafe asset request**: print manual review steps instead of mutating config.
• **Multiple possible assets**: choose the narrowest one; mention skipped alternatives only when relevant.