Installation

Agent Powerups ships reusable skills, plugins, and support assets for local coding agents. Manual install is intentionally direct: choose an agent and copy the native assets into that agent's root.

Install The CLI

From a source checkout:

npm install
npm run build
npm link

Verify the CLI:

apx doctor
apx list
apx discover "fix a failing test" --target codex

Manual Native Install

Use this path when a human wants the full basic setup without asking an agent to curate it.

apx install codex
apx install claude
apx install gemini

Default native install writes immediately and installs:

Agent	Skills	Plugins
Codex	%USERPROFILE%\.codex\skills\	%USERPROFILE%\.codex\plugins\
Claude Code	%USERPROFILE%\.claude\skills\	%USERPROFILE%\.claude\plugins\cache\agent-powerups\
Gemini CLI	%USERPROFILE%\.gemini\skills\	%USERPROFILE%\.gemini\extensions\

claude and claude-code are aliases for the same target.

Existing identical files are skipped. Existing changed files are not overwritten unless --force is passed, except for Agent Powerups-owned guidance and discovery indexes, which refresh by default when stale.

Native install also writes discovery-index.json beside native skills and plugins so agents and tools can inspect installed capabilities without scanning every file. This index is a derived installed snapshot; command-time apx inventory remains the source of truth for current local state.

Preview first:

apx install codex --dry-run
apx install claude --dry-run
apx install gemini --dry-run

Show per-file paths:

apx install codex --verbose

Use a non-default agent root:

apx install codex --agent-root C:\tmp\codex-root

Full Native Install

Full mode includes the default native install, stages support assets under <agent-root>\agent-powerups\, and updates the global instruction file when it already exists.

apx install codex --full
apx install claude --full
apx install gemini --full

Instruction files:

Agent	Instruction file
Codex	<codex-root>\AGENTS.md
Claude Code	<claude-root>\CLAUDE.md
Gemini CLI	<gemini-root>\GEMINI.md

When the instruction file exists, apx install <agent> --full appends or refreshes one marked agent-powerups block and writes a timestamped backup first. When it does not exist, the block is written for review at:

<agent-root>\agent-powerups\instructions\agent-powerups.md

Use a specific instruction file:

apx install codex --full --instructions-file C:\path\AGENTS.md

MCP snippets are staged for review only. No MCP server is enabled automatically. Full mode also writes a staged <agent-root>\agent-powerups\discovery-index.json for agents that inspect the support directory rather than native skill/plugin directories. Stale staged instructions and indexes are refreshed by later apx install <agent> --full runs.

Agent-Curated Setup

apx setup <agent> is legacy compatibility for agent-delegated curated setups. It is dry-run by default and still supports minimal, recommended, and full modes:

apx setup codex --dry-run
apx setup codex --mode recommended --yes
apx setup codex --mode full --yes

Use it only when an agent is deciding which subset/profile to install. Use apx install <agent> for manual default install. apx setup remains supported through at least v0.8.0; removal or aliasing requires a separate batch.

Per-agent references:

• docs/setup/codex.md
• docs/setup/claude-code.md
• docs/setup/gemini.md

Single Asset And Plugin Commands

Single asset install remains available and is still dry-run unless an explicit destination is provided:

apx install ask-claude --target codex --dry-run
apx install ask-claude --target codex --dest .agent-powerups\installed\ask-claude

Plugin commands remain useful for inspection and targeted install:

apx plugins list
apx plugins info dev-vitals
apx plugins info dev-vitals --json
apx plugins validate --all
apx plugins install dev-vitals --target codex --dry-run

Plugins are registered for Claude and Codex marketplace-style discovery. Gemini uses local extensions under .gemini/extensions/; each plugin includes gemini-extension.json and GEMINI.md.

Use discovery commands when an agent or user wants task-based selection rather than a raw catalog list:

apx inventory --target codex --json
apx discover "review this risky refactor" --target codex --json

Optional Tools

Install optional tools only when a specific skill requires them. apx check is dependency-only; it is not a generic proof that an asset was selected or used.

claude --version
codex --version
gemini --version
python -m pip install markitdown
python -m pip install graphifyy
npm install -g defuddle

After review and approval, install optional tools in a controlled environment such as a virtual environment or pinned global toolchain.

Agents can preview supported installs without running them:

apx check markitdown-file-intake --install-missing --dry-run
apx check defuddle --install-missing --dry-run
apx check graphify --install-missing --dry-run

Do not auto-install tools in scripts or hooks without explicit user approval. Use --install-missing --yes only after approval.

Validation

After editing repository content, run:

npm run build
npm run test
python scripts\validate-skills.py
python scripts\validate-catalog.py
apx plugins validate --all

Native install never installs external tools, mutates shell profiles, writes secrets, or enables MCP servers.