# https://github.com/yeaight7/agent-powerups 项目说明书
生成时间：2026-05-15 17:26:54 UTC
## 目录
- [Project Overview](#overview)
- [Installation Guide](#installation)
- [apx CLI Reference](#cli-reference)
- [Skills System](#skills-system)
- [Plugin Bundles](#plugin-bundles)
- [MCP Configurations](#mcp-configurations)
- [Hooks and Commands](#hooks-commands)
- [Claude Code Integration](#claude-code-integration)
- [Codex Integration](#codex-integration)
- [Gemini Integration](#gemini-integration)
## Project Overview
### 相关页面
相关主题：[Installation Guide](#installation), [apx CLI Reference](#cli-reference), [Skills System](#skills-system)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
- [package.json](https://github.com/yeaight7/agent-powerups/blob/main/package.json)
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
# Project Overview
Agent Powerups is an open-source CLI toolkit and plugin ecosystem designed to extend the capabilities of AI coding agents. Inspired by the "Oh My Zsh" philosophy of shared, reusable configurations, it provides a curated collection of skills, commands, MCP server configurations, hooks, and workflow templates that work across multiple agent platforms including Claude Code, OpenAI Codex, and Google Gemini CLI.
## Project Purpose
The core purpose of Agent Powerups is to solve the fragmentation problem in AI-assisted development. Instead of each developer or team maintaining their own custom prompts, scripts, and agent configurations in isolation, Agent Powerups provides a **community-driven library of reusable agent enhancements** that can be discovered, validated, and installed through a unified CLI interface.
Key objectives:
- Provide **portable, validated skills** that encode best-practice workflows (debugging, code review, planning)
- Enable **explicit, auditable installation** of agent extensions rather than opaque粘贴
- Support **multi-agent compatibility** with a single codebase
- Maintain **safety boundaries** around secrets, shell access, and MCP server enablement
- Offer **graduated onboarding** through user-intent profiles and dry-run validation
## Architecture Overview
Agent Powerups follows a layered architecture with three primary concerns:
1. **Catalog Layer**: JSON manifests (`catalog.json`, `plugin-bundles.json`, `profiles.json`) that index all available assets
2. **CLI Layer**: The `apx` command-line interface that provides discovery, validation, and installation
3. **Asset Layer**: The actual skill files, command packs, MCP configs, hooks, and workflow templates
```mermaid
graph TD
A[User / Agent] -->|apx commands| B[CLI Layer: apx]
B -->|read| C[Catalog Layer: JSON manifests]
B -->|validate| D[Source Assets]
C -->|index| D
D -->|skills| E[skills/]
D -->|commands| F[commands/]
D -->|mcp configs| G[mcp/]
D -->|hooks| H[hooks/]
D -->|workflows| I[workflows/]
D -->|agents-md| J[agents-md/]
D -->|plugins| K[plugins/]
B -->|install to| L[Target Agent Root]
L -->|codex| M[Codex agents]
L -->|claude-code| N[Claude Code agents]
L -->|gemini| O[Gemini CLI agents]
```
## CLI Interface (apx)
The `apx` CLI is the primary user interface for Agent Powerups. It is implemented in TypeScript and published as the `agent-powerups` npm package.
### Installation
```sh
npm install -g agent-powerups
```
The CLI requires **Node.js >= 20** and is published at `npm:agent-powerups`.
### Core Commands
| Command | Description |
|---------|-------------|
| `apx list` | List all available skills, commands, and assets |
| `apx info ` | Display detailed information about a specific asset |
| `apx check ` | Validate requirements for an asset |
| `apx doctor` | Run health checks on the local installation |
| `apx setup ` | Install Agent Powerups to a target agent's root |
| `apx install ` | Native install of all assets to agent root |
| `apx plugins list` | List available plugin bundles |
| `apx plugins install ` | Install a plugin bundle to target |
| `apx commands run ` | Execute a command pack |
| `apx hooks run ` | Execute a hook script |
| `apx mcp check ` | Validate an MCP configuration |
| `apx mcp smoke ` | Run smoke tests for an MCP server |
| `apx relay init ` | Initialize a persistent relay session |
| `apx profiles list` | List available user-intent profiles |
| `apx ask-claude` | Query Claude for advice via local CLI |
| `apx ask-gemini` | Query Gemini for advice via local CLI |
| `apx ask-codex` | Query Codex for advice via local CLI |
资料来源：[package.json:16](https://github.com/yeaight7/agent-powerups/blob/main/package.json)
## Asset Catalog
### Skills
Skills are Markdown files that encode reusable agent workflows. Each skill follows a standardized structure with frontmatter metadata.
Current shipped skills include:
| Skill Name | Purpose |
|------------|---------|
| `systematic-debugging` | Structured debugging methodology |
| `no-fluff` | Concise output filtering |
| `writing-plans` | Project planning workflow |
| `ai-slop-cleaner` | Clean AI-generated code artifacts |
| `bigquery-cost-audit` | GCP BigQuery cost analysis |
| `data-quality` | Data validation and quality checks |
| `dbt-incremental-strategy-audit` | dbt incremental model review |
| `dbt-preflight` | dbt project pre-flight checks |
| `dbt-strategy` | dbt modeling strategy |
| `metric-impact-analyzer` | Business metric impact assessment |
| `requesting-code-review` | Code review request workflow |
| `receiving-code-review` | Code review response workflow |
| `pr-triage` | Pull request triage process |
| `repo-map` | Repository structure analysis |
| `bug-hunt` | Systematic bug investigation |
| `safe-refactor` | Safe code refactoring procedures |
| `sql-business-logic-review` | SQL logic validation |
| `defuddle` | Content extraction from documents |
| `markitdown-file-intake` | Document ingestion pipeline |
| `graphify` | Codebase visualization |
| `ask-claude` | Claude advisory workflow |
| `ask-gemini` | Gemini advisory workflow |
| `ask-codex` | Codex advisory workflow |
| `using-powerups` | Onboarding skill for Agent Powerups |
资料来源：[README.md:89-111](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
### Plugin Bundles
Plugin bundles are organized collections of skills, commands, and agents tailored for specific domains. They support multi-agent formats including Claude Code manifests and Codex plugin manifests.
| Status | Count | Example Bundles |
|--------|-------|-----------------|
| Stable | 3 | `dev-vitals`, `debugging-diagnostics`, `quality-gates` |
| Beta | 10 | `codebase-maintenance`, `data-engineering`, `documentation-systems`, `machine-learning-ops`, `codebase-intelligence`, `spec-driven-development`, `spec-quality-gates`, `context-efficiency`, `tool-integrations`, `memory-optimization` |
| Experimental | 4 | `software-engineering`, `agentic-systems`, `security-guardrails`, `agent-evaluation-lab` |
```mermaid
graph TD
A[Plugin Bundle] --> B[skills/]
A --> C[commands/]
A --> D[agents/]
A --> E[.claude-plugin/]
A --> F[.codex-plugin/]
B --> G[SKILL.md files]
C --> H[command-name.md files]
D --> I[agent-name.md files]
E --> J[plugin.json - Claude Code Manifest]
F --> K[plugin.json - Codex Manifest]
```
### User-Intent Profiles
Profiles are curated collections of skills and plugins for specific use cases. They can be inspected with `apx profiles list` and applied during setup.
资料来源：[README.md:120-130](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## Setup Modes
Agent Powerups supports three installation modes that control the scope of what gets installed:
| Mode | Description | Use Case |
|------|-------------|----------|
| `minimal` | Bootstrap setup with essential instructions only | Quick evaluation |
| `recommended` | Core skills, plugins, and instructions | Standard onboarding |
| `full` | All assets plus support documentation | Comprehensive deployment |
The setup process:
1. Creates an `agent-powerups/` directory under the agent root
2. Copies relevant asset directories based on mode
3. Optionally appends agent-powerups instructions to `AGENTS.md` or `CLAUDE.md`
4. Backs up existing instruction files before modification
资料来源：[src/cli/commands/setup.ts:14-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
```mermaid
flowchart LR
A[apx setup codex] --> B{Mode?}
B -->|minimal| C[Bootstrap instructions only]
B -->|recommended| D[Skills + plugins + instructions]
B -->|full| E[All assets + docs]
C --> F[agent-powerups/]
D --> F
E --> F
F --> G{AGENTS.md exists?}
G -->|Yes| H[Append marked block
Backup first]
G -->|No| I[Create instructions file]
H --> J[Setup complete]
I --> J
```
## Supported Agents
Agent Powerups maintains explicit compatibility with three primary agent platforms:
| Agent | Install Command | Asset Target |
|-------|-----------------|--------------|
| OpenAI Codex | `apx install codex` | `/skills/`, `/plugins/` |
| Anthropic Claude Code | `apx install claude` | `/skills/`, `/plugins/` |
| Google Gemini CLI | `apx install gemini` | `/skills/`, `/extensions/` |
The CLI uses `--target` flag to specify the destination:
```sh
apx plugins install dev-vitals --target codex --dry-run
apx plugins install dev-vitals --target claude-code --dry-run
```
资料来源：[src/cli/apx.ts:32-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
## MCP Integration
Agent Powerups ships with a local-first GitHub MCP configuration that includes:
- `apx mcp check` - Validate MCP server configuration
- `apx mcp smoke` - Run smoke tests against MCP server
- `apx mcp install` - Explicit installation workflow
The MCP integration follows a security-first model where MCP servers require explicit user approval before enablement.
资料来源：[README.md:51-54](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## Safety Model
Agent Powerups implements several safety mechanisms:
1. **Dry-run by default**: Most install commands support `--dry-run` to preview changes
2. **Explicit approval**: Interactive prompts require confirmation unless `--yes` is passed
3. **Backup before modify**: Setup creates backups of existing instruction files
4. **Requirement validation**: `apx check` verifies prerequisites before installation
5. **Security audit**: `apx security-audit` scans for dangerous patterns in scripts
Dangerous patterns flagged by the security audit:
| Pattern | Severity | Description |
|---------|----------|-------------|
| `unpinned-latest-image` | P2 | Unpinned `:latest` container images in CI |
| `broad-filesystem-write` | P1 | Broad filesystem write or `rm -rf /` patterns |
| `missing-dry-run` | P1 | Install commands without `--dry-run` guard |
资料来源：[src/cli/commands/security-audit.ts:18-28](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
## Validation and Health Checks
### Doctor Command
The `apx doctor` command performs comprehensive health checks:
| Check | What It Validates |
|-------|-------------------|
| Skill files | All skills have `SKILL.md`, valid frontmatter, and referenced support files exist |
| External scripts | Registered external scripts can be executed |
| File permissions | Asset directories are readable |
| Node.js version | Runtime version compatibility |
资料来源：[src/cli/commands/doctor.ts:35-52](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
### Requirement Checking
The `apx check` command validates asset requirements:
- Missing requirements are flagged with `MISSING` status
- Automatic installation is attempted if `--install-missing` is provided
- Human approval is requested via interactive prompt unless `--yes` is passed
```mermaid
flowchart TD
A[apx check ] --> B[Check requirements]
B --> C{All satisfied?}
C -->|Yes| D[status=OK]
C -->|No| E{installMissing?}
E -->|Yes| F[installMissingRequirements]
E -->|No| G[status=MISSING]
F --> H{Interactive?}
H -->|Yes| I[confirmInstall prompt]
H -->|No --yes| J[Auto-install]
I -->|Approved| F
I -->|Declined| K[warnings.push]
```
资料来源：[src/cli/commands/check.ts:28-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
## Directory Structure
```
agent-powerups/
├── skills/ # Root-level reusable skills
├── agents-md/ # AGENTS.md templates
├── commands/ # Command packs
│ └── generic/ # Agent-agnostic commands
├── hooks/ # Hook examples
├── workflows/ # Workflow templates
├── mcp/ # MCP configurations
│ └── generic/ # Agent-agnostic MCP configs
├── plugins/ # Plugin bundle source
├── docs/ # Documentation
├── scripts/ # Validation scripts
├── .codex-plugin/ # Codex plugin manifest
├── .claude-plugin/ # Claude Code plugin manifest
├── apx.ts # CLI entry point
├── package.json # Package manifest
├── catalog.json # Asset catalog index
├── plugin-bundles.json # Plugin bundle index
└── profiles.json # User-intent profiles
```
## Version and Release
| Property | Value |
|----------|-------|
| Package name | `agent-powerups` |
| Current version | `0.3.0` |
| License | Apache-2.0 |
| Node.js requirement | >= 20 |
| Repository | `git+https://github.com/yeaight7/agent-powerups.git` |
资料来源：[package.json:1-15](https://github.com/yeaight7/agent-powerups/blob/main/package.json)
---
## Installation Guide
### 相关页面
相关主题：[Project Overview](#overview), [apx CLI Reference](#cli-reference), [Claude Code Integration](#claude-code-integration), [Codex Integration](#codex-integration), [Gemini Integration](#gemini-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [src/cli/commands/install.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/install.ts)
- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)
- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)
- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)
- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
# Installation Guide
Agent Powerups provides multiple installation pathways to accommodate different workflows—from manual CLI installation for humans to agent-curated automated setup. This guide covers all supported methods, configuration options, and per-agent integration patterns.
## Overview
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. The installation system is designed with safety boundaries around external tools, secrets, shell profiles, and MCP enablement. 资料来源：[README.md]()
## Installation Methods
The system supports four primary installation approaches:
| Method | Command | Use Case |
|--------|---------|----------|
| **CLI Manual Install** | `apx install ` | Direct native install for humans |
| **Agent-Curated Setup** | `apx setup --mode recommended --yes` | Bootstrap an agent with curated assets |
| **Agent-Managed Setup** | Give agent repo access + run `apx setup` | Let the agent inspect and propose setup |
| **Minimal Demo** | `apx setup --agent-root --dry-run` | Review assets without mutation |
资料来源：[README.md:1-80]()
## Prerequisites
### System Requirements
- **Node.js**: Required for the `apx` CLI tool
- **npm** or **yarn**: For installing the CLI package
- **Python 3.x**: For validation scripts (`validate-skills.py`, `validate-catalog.py`, `check-requirements.py`)
- **Git**: For cloning the repository (optional, if using npm package)
### Verification Commands
Before installation, verify your environment:
```sh
apx doctor
apx list
```
The `doctor` command checks the CLI installation and dependencies. The `list` command displays all available assets. 资料来源：[examples/minimal/README.md]()
## CLI Installation
### Installing the Package
Install the `agent-powerups` package globally:
```sh
npm install -g agent-powerups
```
Or use the development version from the repository:
```sh
git clone https://github.com/yeaight7/agent-powerups.git
cd agent-powerups
npm install
npm run build
npm link
```
资料来源：[examples/minimal/README.md]()
### Global Commands Available
After installation, the `apx` command provides access to all functionality:
| Command | Description |
|---------|-------------|
| `apx doctor` | Verify CLI installation and dependencies |
| `apx list` | List all available skills, commands, hooks, and workflows |
| `apx info ` | Show detailed information about a specific asset |
| `apx check ` | Validate asset requirements |
| `apx profiles list` | List user-intent profiles for curated skill/plugin sets |
资料来源：[src/cli/apx.ts:1-100]()
## Native Install (Manual)
The `apx install` command performs a direct native installation, copying skills and plugin bundles into the selected agent root directory.
### Basic Syntax
```sh
apx install [--verbose]
apx install --full [--verbose]
```
### Default Install Behavior
| Asset Type | Destination |
|------------|-------------|
| Root `skills/` | `/skills/` |
| Codex/Claude plugin bundles | `/plugins/` |
| Gemini plugin bundles | `/extensions/` |
Human output shows counts by default. Use `--verbose` for per-file paths.
### Full Install
The `--full` flag additionally:
- Stages support assets under `agent-powerups/`
- Updates existing global instructions with a backup
```sh
apx install codex --full --verbose
```
### Dry Run
Always preview changes before applying:
```sh
apx install codex --dry-run
apx install claude --dry-run
apx install gemini --dry-run
```
### Per-Asset Installation
Install specific plugin bundles to specific targets:
```sh
apx install --target [--dry-run] [--dest ]
```
Example:
```sh
apx install dev-vitals --target codex --dry-run
apx install dev-vitals --target codex
```
资料来源：[README.md:1-150](), [src/cli/apx.ts:100-200]()
## Agent-Curated Setup
The `apx setup` command provides an agent-curated setup path with different configuration modes.
### Setup Syntax
```sh
apx setup [--mode minimal|recommended|full] [--dry-run|--yes] [--agent-root ] [--instructions-file ] [--json]
```
### Setup Modes
#### Minimal Mode (Bootstrap)
Minimal mode creates a bootstrap setup with essential references:
```sh
apx setup codex --mode minimal --yes
```
Output structure:
```
START_MARKER
## Agent Powerups
Agent Powerups assets are installed at ``.
- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.
- Use `apx` commands to discover, inspect, validate, and extend setup.
- MCP servers require explicit user approval.
- External tools require user approval before install.
This is a minimal (bootstrap) setup. To get a recommended agent environment:
apx setup ${profile.agent} --mode recommended --yes
END_MARKER
```
资料来源：[src/cli/commands/setup.ts:1-50]()
#### Recommended Mode
Recommended mode provides the main agent environment with skills, plugin bundles, and comprehensive instructions:
```sh
apx setup codex --mode recommended --yes
apx setup claude-code --mode recommended --yes
apx setup gemini --mode recommended --yes
```
This mode includes:
- All root skills from `skills/`
- Recommended plugin bundles based on agent profile
- Command templates and hook examples
- AGENTS.md templates
- MCP configuration guidance
#### Full Mode
Full mode performs a broad staging with maximum asset coverage:
```sh
apx setup codex --mode full --yes
```
## Installation Workflow Diagram
```mermaid
graph TD
A[Start: apx install or apx setup] --> B{Dry Run?}
B -->|Yes| C[Preview Changes Only]
B -->|No| D{Interactive?}
D -->|Yes| E[Confirm Changes]
D -->|No --yes| F[Auto-Approve]
C --> G[Display File Operations]
E -->|Approved| H[Execute Installation]
E -->|Declined| I[Abort]
F --> H
H --> J[Copy Skills to Agent Root]
H --> K[Copy Plugins to Agent Root]
H --> L[Update Instructions if --full]
J --> M[Verify with apx check]
K --> M
L --> M
M --> N[Installation Complete]
```
## Per-Agent Setup Guides
### Codex Setup
```sh
# Dry run first
apx setup codex --dry-run
# Safe apply with explicit root
apx setup codex --agent-root .agent-powerups-demo\codex --yes
# Inspect after setup
apx info using-powerups
apx check using-powerups
```
**Instruction File Behavior:**
- If `\AGENTS.md` exists, setup appends a marked `agent-powerups` block after creating a backup
- If it does not exist, setup writes `agent-powerups\instructions\agent-powerups.md` and reports manual steps
资料来源：[examples/codex/README.md]()
### Claude Code Setup
```sh
# Dry run first
apx setup claude-code --dry-run
# Safe apply with explicit root
apx setup claude-code --agent-root .agent-powerups-demo\claude --yes
# Inspect after setup
apx commands print ship-check --target claude-code
apx info using-powerups
```
**Instruction File Behavior:**
- If `\CLAUDE.md` exists, setup appends a marked `agent-powerups` block after creating a backup
- If it does not exist, setup writes `agent-powerups\instructions\agent-powerups.md` and reports manual steps
资料来源：[examples/claude-code/README.md]()
### Gemini Setup
```sh
apx setup gemini --dry-run
apx setup gemini --mode recommended --yes
```
Gemini plugin bundles include `gemini-extension.json` and `GEMINI.md`.
## Agent-Managed Setup
For agent-curated installation, provide the agent access to this repository and ask it to run:
```sh
apx list
apx profiles list
apx setup --mode recommended --yes
```
The agent will:
1. Inspect available skills and plugins
2. Propose a configuration plan
3. Apply the setup based on the selected mode
## Plugin Bundle Installation
### Discovering Plugins
```sh
apx plugins list
apx plugins info dev-vitals
```
### Validating Plugin Bundles
Before installation, validate bundle structure:
```sh
apx plugins validate --all
```
### Installing Plugin Bundles
```sh
apx plugins install dev-vitals --target codex --dry-run
apx plugins install dev-vitals --target codex
```
### Plugin Bundle Structure
Each plugin follows the standard agent plugin layout:
```
/
├── .claude-plugin/
│ └── plugin.json # Claude Code Manifest
├── .codex-plugin/
│ └── plugin.json # Codex Manifest
├── skills/
│ └── /
│ └── SKILL.md
├── agents/
│ └── .md
└── commands/
└── .md
```
资料来源：[plugins/README.md]()
## MCP Configuration Installation
### Available MCP Commands
| Command | Purpose |
|---------|---------|
| `apx mcp list` | List available MCP configurations |
| `apx mcp print ` | Display MCP configuration |
| `apx mcp check ` | Validate MCP configuration |
| `apx mcp smoke ` | Run smoke tests |
| `apx mcp install ` | Install MCP configuration |
### Installing GitHub MCP
```sh
apx mcp check github-local --target generic
apx mcp smoke github-local --json
apx mcp install github-local --target codex --dry-run
apx mcp install github-local --target codex
```
## Post-Installation Validation
### Run Validation Scripts
```sh
python scripts/validate-skills.py
python scripts/validate-catalog.py
python scripts/check-requirements.py
```
### Verify Setup
```sh
apx doctor
apx check using-powerups
apx hooks run no-secrets-preflight --all
```
## Minimal Demo Walkthrough
For inspecting Agent Powerups without mutating an agent's global config:
```sh
# 1. Install and link the CLI
npm install
npm run build
npm link
# 2. Verify installation
apx doctor
apx list
# 3. Dry run setup to disposable directory
apx setup codex --agent-root .agent-powerups-demo\codex --dry-run
# 4. Apply to disposable local root
apx setup codex --agent-root .agent-powerups-demo\codex --yes
# 5. Review created structure
.agent-powerups-demo/codex/agent-powerups/skills/
.agent-powerups-demo/codex/agent-powerups/commands/
.agent-powerups-demo/codex/agent-powerups/instructions/agent-powerups.md
# 6. Rollback when done
Remove-Item .agent-powerups-demo -Recurse -Force
```
资料来源：[examples/minimal/README.md]()
## Safety Considerations
The installation system implements safety boundaries around:
| Area | Safety Measure |
|------|----------------|
| External Tools | Require user approval before install |
| Secrets | Never paste into agent context unless strictly necessary |
| Shell Profiles | No automatic shell profile modifications |
| MCP Servers | Require explicit user approval via `apx mcp check` and `apx mcp smoke` |
| Hooks | Execute only when supported by host agent |
**Before loading any asset**, review it:
- 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
See [SECURITY.md](./SECURITY.md) and [docs/security-model.md](./docs/security-model.md) for full security details.
## Command Reference
### Install Command Options
| Option | Description |
|--------|-------------|
| `--dry-run` | Preview changes without applying |
| `--full` | Stage support assets and update global instructions |
| `--verbose` | Show per-file paths during installation |
| `--agent-root ` | Specify custom agent root directory |
| `--instructions-file ` | Specify custom instructions file path |
| `--force` | Overwrite existing files |
| `--json` | Output results in JSON format |
### Setup Command Options
| Option | Description |
|--------|-------------|
| `--mode minimal\|recommended\|full` | Select setup configuration mode |
| `--dry-run` | Preview changes without applying (default) |
| `--yes` | Auto-approve and apply changes |
| `--agent-root ` | Specify custom agent root directory |
| `--instructions-file ` | Specify custom instructions file path |
| `--json` | Output results in JSON format |
## Troubleshooting
### CLI Not Found
```sh
npm link
# Or reinstall globally
npm install -g agent-powerups
```
### Dry Run vs Apply
Always prefer dry-run first:
```sh
apx install codex --dry-run
apx setup codex --dry-run
apx plugins install dev-vitals --target codex --dry-run
```
### Rollback
If using explicit `--agent-root` with a disposable directory, simply delete the directory:
```sh
Remove-Item .agent-powerups-demo -Recurse -Force
```
### Agent Instructions Not Updated
Check if the agent's instruction file exists:
- Codex: `\AGENTS.md`
- Claude Code: `\CLAUDE.md`
If the file doesn't exist, setup writes to `agent-powerups\instructions\agent-powerups.md` and reports manual integration steps.
---
## apx CLI Reference
### 相关页面
相关主题：[Project Overview](#overview), [Installation Guide](#installation), [Plugin Bundles](#plugin-bundles)
Relevant Source Files
The following source files were used to generate this documentation:
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
- [src/cli/commands/list.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/list.ts)
- [src/cli/commands/plugins.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/plugins.ts)
- [src/cli/commands/profiles.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/profiles.ts)
- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)
- [src/cli/commands/validate.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/validate.ts)
# apx CLI Reference
The `apx` (Agent Powerups eXecutor) is the primary command-line interface for managing Agent Powerups assets, skills, plugins, and configurations for coding agents. It provides a unified entry point for installing, validating, and orchestrating agent powerups across multiple agent platforms including Codex, Claude Code, and Gemini.
## Overview
The `apx` CLI serves as a safe local CLI with runnable local checks, enabling users to:
- Discover and install reusable skills and plugin bundles
- Configure agent-specific instruction files
- Validate tool requirements and dependencies
- Manage MCP (Model Context Protocol) server configurations
- Execute security audits and preflight checks
- Handle persistent relay sessions for multi-agent workflows
资料来源：[src/cli/apx.ts:1-50]()
## Command Hierarchy
The `apx` CLI organizes commands into a hierarchical structure with multiple subcommand categories.
```mermaid
graph TD
A[apx] --> B[Install Commands]
A --> C[Setup Commands]
A --> D[Information Commands]
A --> E[MCP Commands]
A --> F[Plugin Commands]
A --> G[Profile Commands]
A --> H[Validation Commands]
A --> I[Security Commands]
A --> J[Relay Commands]
A --> K[Phase Commands]
B --> B1[install]
B --> B2[setup]
C --> C1[setup codex]
C --> C2[setup claude-code]
C --> C3[setup gemini]
D --> D1[list]
D --> D2[info]
D --> D3[doctor]
D --> D4[check]
E --> E1[mcp list]
E --> E2[mcp print]
E --> E3[mcp check]
E --> E4[mcp smoke]
E --> E5[mcp install]
E --> E6[mcp write]
F --> F1[plugins list]
F --> F2[plugins info]
F --> F3[plugins validate]
F --> F4[plugins install]
G --> G1[profiles list]
G --> G2[profiles info]
G --> G3[profiles plan]
G --> G4[profiles install]
```
## Installation Commands
### `apx install`
Installs assets, skills, or plugins to specified agent targets.
```sh
apx install [--full] [--dry-run] [--agent-root ] [--instructions-file ] [--force] [--verbose] [--json]
apx install --target [--dry-run] [--dest ]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes (first form) | Target agent platform |
| `` | string | Yes (second form) | Specific asset to install |
| `--target` | string | Yes (second form) | Installation target |
| `--full` | flag | No | Install with support assets |
| `--dry-run` | flag | No | Preview without applying changes |
| `--agent-root` | path | No | Custom agent root directory |
| `--instructions-file` | path | No | Custom instructions file path |
| `--force` | flag | No | Overwrite existing files |
| `--verbose` | flag | No | Show per-file installation paths |
| `--json` | flag | No | Output JSON format |
**Default Installation Paths:**
| Target | Root Location | Plugin Location |
|--------|--------------|-----------------|
| codex | `/` | `/plugins/` |
| claude-code | `/` | `/plugins/` |
| gemini | `/` | `/extensions/` |
资料来源：[src/cli/apx.ts:80-100]()
### Native Install Behavior
The default manual install copies:
- Root `skills/` → `/skills/`
- Codex/Claude plugin bundles → `/plugins/`
- Gemini plugin bundles → `/extensions/`
The `--full` flag additionally:
- Stages support assets under `agent-powerups/`
- Updates existing global instructions with a backup
## Setup Commands
### `apx setup`
Configures agent environments with curated skill and plugin sets using agent-curated setup paths.
```sh
apx setup [--mode minimal|recommended|full] [--dry-run|--yes] [--agent-root ] [--instructions-file ] [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | Target agent platform |
| `--mode` | string | No | Setup mode (default: dry-run) |
| `--dry-run` | flag | No | Preview changes (default) |
| `--yes` | flag | No | Apply changes without confirmation |
| `--agent-root` | path | No | Custom agent root directory |
| `--instructions-file` | path | No | Custom instructions file path |
| `--json` | flag | No | Output JSON format |
### Setup Modes
| Mode | Description | Use Case |
|------|-------------|----------|
| `minimal` | Bootstrap only | Quick start, minimal footprint |
| `recommended` | Main agent setup | Standard development environment |
| `full` | Broad staging | Complete feature set |
### Instruction File Behavior
- If `/AGENTS.md` (Codex) or `/CLAUDE.md` (Claude Code) exists, setup appends a marked `agent-powerups` block after creating a backup.
- If the file does not exist, setup writes `agent-powerups/instructions/agent-powerups.md` and reports manual steps.
资料来源：[src/cli/commands/setup.ts:1-60]()
## Information Commands
### `apx doctor`
Runs comprehensive diagnostics on the apx installation.
```sh
apx doctor [--full] [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--full` | flag | No | Run full diagnostic suite |
| `--json` | flag | No | Output JSON format |
### `apx list`
Lists all available assets, skills, and plugins in the catalog.
```sh
apx list [--json]
```
### `apx info`
Displays detailed information about a specific asset.
```sh
apx info [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | Name of the asset to inspect |
| `--json` | flag | No | Output JSON format |
### `apx check`
Checks dependency requirements for assets without installing.
```sh
apx check [--install-missing] [--dry-run]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | Asset to check dependencies for |
| `--install-missing` | flag | No | Automatically install missing dependencies |
| `--dry-run` | flag | No | Preview installation without applying |
资料来源：[src/cli/commands/list.ts:1-50]()
## MCP Commands
The MCP (Model Context Protocol) commands manage MCP server configurations for agent integrations.
```mermaid
graph LR
A[mcp list] --> B[Discover configs]
C[mcp check] --> D[Validate syntax]
E[mcp smoke] --> F[Test connectivity]
G[mcp install] --> H[Deploy to target]
```
### `apx mcp list`
Lists all available MCP configurations.
```sh
apx mcp list [--json]
```
### `apx mcp print`
Prints MCP configuration content for review.
```sh
apx mcp print --target [--json]
```
### `apx mcp check`
Validates MCP configuration syntax and structure.
```sh
apx mcp check --target [--json]
```
### `apx mcp smoke`
Tests MCP server connectivity and basic functionality.
```sh
apx mcp smoke [--json]
```
### `apx mcp install`
Installs MCP configuration to the specified agent target.
```sh
apx mcp install --target [--dry-run|--yes] [--agent-root ] [--dest ] [--force] [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | MCP configuration name |
| `--target` | string | Yes | Installation target |
| `--dry-run` | flag | No | Preview without applying |
| `--yes` | flag | No | Apply without confirmation |
| `--dest` | path | No | Custom destination path |
| `--force` | flag | No | Overwrite existing |
| `--json` | flag | No | JSON output |
### `apx mcp write`
Writes MCP configuration to a specified location.
```sh
apx mcp write --target --dest [--force] [--json]
```
资料来源：[src/cli/commands/mcp.ts:1-100]()
## Plugin Commands
Plugin commands manage plugin bundles with validation, inspection, and installation capabilities.
```mermaid
graph TD
A[plugins list] --> B[Discover plugins]
A --> C[plugins info]
C --> D[plugins validate]
D --> E{Valid?}
E -->|Yes| F[plugins install]
E -->|No| G[Fix errors]
F --> H[Deploy to target]
```
### `apx plugins list`
Lists all available plugin bundles.
```sh
apx plugins list [--json]
```
### `apx plugins info`
Displays detailed information about a specific plugin.
```sh
apx plugins info [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | Plugin bundle name |
| `--json` | flag | No | JSON output format |
### `apx plugins validate`
Validates plugin bundle structure and metadata.
```sh
apx plugins validate [--json]
apx plugins validate --all [--json]
```
### `apx plugins install`
Installs a plugin bundle to the specified target.
```sh
apx plugins install --target [--dest ] [--dry-run|--yes] [--force] [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | Plugin to install |
| `--target` | string | Yes | Target agent platform |
| `--dest` | path | No | Custom installation directory |
| `--dry-run` | flag | No | Preview without applying |
| `--yes` | flag | No | Apply without confirmation |
| `--force` | flag | No | Overwrite existing |
| `--json` | flag | No | JSON output |
资料来源：[src/cli/commands/plugins.ts:1-100]()
## Profile Commands
Profiles are curated skill and plugin sets designed for specific use cases or security requirements.
### `apx profiles list`
Lists all available user-intent profiles.
```sh
apx profiles list [--json]
```
### `apx profiles info`
Displays detailed information about a specific profile.
```sh
apx profiles info [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | Profile name to inspect |
| `--json` | flag | No | JSON output format |
### `apx profiles plan`
Generates an installation plan for a profile targeting a specific agent.
```sh
apx profiles plan --target [--json]
```
### `apx profiles install`
Installs a complete profile to the specified target.
```sh
apx profiles install --target [--dry-run|--yes] [--dest ] [--force] [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `` | string | Yes | Profile to install |
| `--target` | string | Yes | Target agent platform |
| `--dry-run` | flag | No | Preview without applying |
| `--yes` | flag | No | Apply without confirmation |
| `--dest` | path | No | Custom destination |
| `--force` | flag | No | Overwrite existing |
| `--json` | flag | No | JSON output |
资料来源：[src/cli/commands/profiles.ts:1-80]()
## Validation Commands
### `apx validate`
Validates skills, catalog entries, and requirements.
```sh
apx validate [--json]
apx validate skill [--json]
apx validate catalog [--json]
```
### `apx ship-check`
Runs pre-deployment checks to validate project readiness.
```sh
apx ship-check [--full] [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--full` | flag | No | Run comprehensive checks |
| `--json` | flag | No | JSON output format |
### `apx no-secrets-preflight`
Detects potential secret leaks in files before commit.
```sh
apx no-secrets-preflight [--path | --all] [--json]
```
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--path` | path | No | Specific file or directory to scan |
| `--all` | flag | No | Scan entire repository |
| `--json` | flag | No | JSON output format |
资料来源：[src/cli/commands/validate.ts:1-60]()
## Security Commands
### `apx security-audit`
Performs security analysis on project files.
```sh
apx security-audit --path [--json]
apx security-audit --all [--json]
```
### Security Checks
| Check Name | Severity | Pattern | Description |
|------------|----------|---------|-------------|
| `unpinned-image` | P2 | `image:\s+[a-z0-9_/.-]+:latest` | Unpinned `:latest` image in CI |
| `broad-filesystem-write` | P1 | `rm\s+-rf\s+\/|write_file\s+/\*\*` | Dangerous filesystem operations |
| `missing-dry-run` | P1 | `npm\s+install\|pip\s+install` without `--dry-run` | Install without dry-run guard |
资料来源：[src/cli/commands/security-audit.ts:1-50]()
## Relay Commands
Persistent relay sessions maintain context across multiple turns for multi-agent delegation.
### `apx relay init`
Initializes a new persistent relay session.
```sh
apx relay init
```
### `apx relay start`
Starts a relay session with a specified provider.
```sh
apx relay start --provider [--json]
```
### `apx relay ask`
Sends a query to an active relay session.
```sh
apx relay ask "" [--json]
```
### `apx relay status`
Checks the status of a relay session.
```sh
apx relay status
```
### `apx relay stop`
Stops an active relay session.
```sh
apx relay stop
```
## Agent Advisor Commands
### `apx ask-codex`
Queries Codex for advice or analysis.
```sh
apx ask-codex "" [--json]
```
### `apx ask-claude`
Queries Claude for advice or analysis.
```sh
apx ask-claude "" [--json]
```
### `apx ask-gemini`
Queries Gemini for advice or analysis.
```sh
apx ask-gemini "" [--json]
```
## Agent Targets
All installation and setup commands support the following target agents:
| Target | Description |
|--------|-------------|
| `codex` | OpenAI Codex / VS Code AI |
| `claude` | Anthropic Claude |
| `claude-code` | Claude Code CLI |
| `gemini` | Google Gemini |
| `generic` | Generic/unspecified agent |
## Global Flags
| Flag | Description |
|------|-------------|
| `--dry-run` | Preview changes without applying (default for most commands) |
| `--yes` | Apply changes without confirmation prompt |
| `--json` | Output results in JSON format |
| `--verbose` | Show detailed per-file information |
| `--force` | Overwrite existing files without prompting |
## Exit Codes
| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | Failure (missing dependencies, validation errors, etc.) |
## Configuration Files
The CLI reads configuration from the following locations:
- Package-level `package.json` for version detection
- Agent-specific root directories for target configuration
- `skills/`, `plugins/`, `mcp/`, `commands/`, `hooks/`, `workflows/` directories for asset discovery
资料来源：[src/cli/apx.ts:200-280]()
## Quick Reference
```sh
# Setup and installation
apx install codex --dry-run
apx install codex --yes
apx setup codex --mode recommended --yes
# Discovery and inspection
apx doctor
apx list
apx info markitdown-file-intake
apx check markitdown-file-intake
# Plugin management
apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target codex --dry-run
# MCP management
apx mcp list
apx mcp check github-local --target codex
apx mcp smoke github-local --json
apx mcp install github-local --target codex --dry-run
# Profile management
apx profiles list
apx profiles info safe-core
apx profiles plan safe-core --target codex
# Security and validation
apx ship-check --full
apx no-secrets-preflight --all
apx security-audit --path .
---
## Skills System
### 相关页面
相关主题：[Project Overview](#overview), [Plugin Bundles](#plugin-bundles)
相关源码文件
以下源码文件用于生成本页说明：
- [skills/systematic-debugging/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/systematic-debugging/SKILL.md)
- [skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)
- [skills/safe-refactor/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/safe-refactor/SKILL.md)
- [skills/bug-hunt/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/bug-hunt/SKILL.md)
- [docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)
# Skills System
## Overview
The Skills System is a core component of Agent Powerups, providing a collection of **reusable, text-based agent workflows** designed to standardize and accelerate common development tasks. Inspired by the Oh My Zsh plugin model, skills serve as modular instruction sets that coding agents can invoke to perform structured, repeatable workflows.
Skills in this system are **agent-agnostic** — they are designed as generic text-based instructions that can be understood and executed by various coding agent platforms including Codex, Claude Code, and Gemini.
资料来源：[README.md:22-24](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## Core Architecture
### Skill Structure
Each skill follows a standardized file structure:
```
skills/
└── /
├── SKILL.md # Main skill definition
└── support-files/ # Optional referenced assets
```
The primary `SKILL.md` file contains:
- **Frontmatter metadata** (YAML): name, description, version, tags, compatibility
- **Core workflow content**: Structured instructions for the agent
- **Support file references**: Paths to optional helper resources
资料来源：[docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)
### Skill Lifecycle
```mermaid
graph TD
A[Create SKILL.md] --> B[Validate Frontmatter]
B --> C[Check Required Fields]
C --> D{Valid?}
D -->|Yes| E[Publish to Catalog]
D -->|No| F[Fix Issues]
F --> B
E --> G[apx list / apx info]
G --> H[Agent Invocation]
H --> I[Execute Workflow]
I --> J[Report Results]
```
## Skill Categories
The repository ships 21 core skills organized into functional categories:
| Category | Skills | Purpose |
|----------|--------|---------|
| **Development Workflow** | `systematic-debugging`, `bug-hunt`, `safe-refactor`, `writing-plans` | Structured approaches to common coding tasks |
| **Code Quality** | `no-fluff`, `requesting-code-review`, `receiving-code-review` | Review and quality assurance processes |
| **Data Engineering** | `bigquery-cost-audit`, `data-quality`, `dbt-preflight`, `dbt-strategy`, `dbt-incremental-strategy-audit` | Data pipeline and warehouse management |
| **Business Logic** | `sql-business-logic-review`, `metric-impact-analyzer` | Analysis and validation workflows |
| **Utility** | `ai-slop-cleaner`, `defuddle`, `markitdown-file-intake`, `graphify` | Content processing and transformation |
| **Agent Integration** | `ask-claude`, `ask-gemini`, `ask-codex`, `using-powerups` | Cross-agent communication and onboarding |
资料来源：[README.md:103-130](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## Skill Frontmatter Schema
Every skill must include valid YAML frontmatter in its `SKILL.md` file:
```yaml
---
name: # Required: unique lowercase identifier
description: # Required: brief explanation
version: # Optional: default "1.0.0"
tags: # Optional: categorization
-
-
requires: # Optional: dependencies
-
compatibility: # Optional: target agent hints
- codex
- claude-code
- gemini
---
```
### Required Fields
| Field | Type | Description | Validation |
|-------|------|-------------|------------|
| `name` | string | Unique skill identifier | Must exist in frontmatter |
| `description` | string | Brief description of skill purpose | Must exist in frontmatter |
资料来源：[src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts) (lines checking for frontmatter)
## Skill Validation System
The system includes automated validation to ensure skill quality and consistency.
### Validation Checks
The `apx doctor` command performs the following validation:
1. **Frontmatter validation**: Ensures `name` and `description` exist
2. **Content length validation**: Skills must meet minimum character threshold
3. **Support file verification**: References to support files must exist
4. **Catalog alignment**: Skills must appear in the central catalog
### Validation Script
```sh
python scripts/validate-skills.py
python scripts/validate-catalog.py
```
### Doctor Check Results
| Check | Pass Condition | Failure Message |
|-------|----------------|-----------------|
| `skill-frontmatter` | All skills have `name` + `description` | X skill(s) missing name/description |
| `skill-content-length` | All skills ≥ minimum chars | X skill(s) under minimum length |
资料来源：[src/cli/commands/audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)
## Featured Skills
### systematic-debugging
A structured approach to diagnosing and resolving software defects.
**Workflow Steps:**
1. Gather error context and reproduction steps
2. Isolate the failing component
3. Form and test hypotheses
4. Implement and verify fix
5. Document root cause
资料来源：[skills/systematic-debugging/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/systematic-debugging/SKILL.md)
### writing-plans
Systematic approach to creating actionable project plans from requirements.
**Workflow Steps:**
1. Parse and clarify requirements
2. Identify dependencies and constraints
3. Break down into actionable tasks
4. Estimate effort and timeline
5. Present structured plan for review
资料来源：[skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)
### safe-refactor
Guided refactoring workflow with safety checks and rollback considerations.
**Workflow Steps:**
1. Identify refactoring scope and goals
2. Establish baseline with tests
3. Execute incremental changes
4. Verify behavior preservation
5. Clean up and document changes
资料来源：[skills/safe-refactor/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/safe-refactor/SKILL.md)
### bug-hunt
Exploratory investigation skill for tracking down elusive bugs.
**Workflow Steps:**
1. Collect available evidence
2. Define search boundaries
3. Instrument for additional data
4. Narrow down through elimination
5. Confirm and document findings
资料来源：[skills/bug-hunt/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/bug-hunt/SKILL.md)
## CLI Integration
### Discovery Commands
| Command | Description |
|---------|-------------|
| `apx list` | List all available skills in the catalog |
| `apx info ` | Display detailed information about a specific skill |
| `apx check ` | Validate a skill's structure and frontmatter |
### Installation and Setup
```sh
# Native install to agent root
apx install
# Dry-run to preview changes
apx install codex --dry-run
# Full install with support assets
apx install codex --full --verbose
```
During installation, skills from `skills/` are copied to `/skills/` (or `/agent-powerups/skills/` for full installs).
资料来源：[README.md:142-160](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## Skills vs Plugin Bundles
It's important to distinguish between **root skills** and **plugin skills**:
| Aspect | Root Skills | Plugin Skills |
|--------|-------------|---------------|
| **Location** | `skills/` | `plugins//skills/` |
| **Scope** | General-purpose, standalone | Domain-specific, deeper coverage |
| **Dependencies** | Self-contained | May reference plugin-specific assets |
| **Override behavior** | Cannot be overridden by plugins | Must not replace or override root skills |
> Root skills in `skills/` are general-purpose and standalone. Plugin skills are domain-specific and go deeper. A plugin skill may cover the same topic as a root skill — it must not replace or override it.
资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
## Catalog Schema
Skills are registered in the central catalog with metadata for discovery and filtering:
```json
{
"skills": [
{
"name": "skill-name",
"description": "Brief description",
"path": "skills/skill-name",
"tags": ["debugging", "workflow"],
"compatibility": ["codex", "claude-code"]
}
]
}
```
资料来源：[docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)
## Quality Gates for Skills
The audit system validates skills through multiple checks:
```mermaid
graph LR
A[apx audit skills] --> B[Check Frontmatter]
A --> C[Check Content Length]
A --> D[Check Support Files]
B --> E{Summary}
C --> E
D --> E
E --> F[Pass/Warn/Fail]
```
Output format:
```
audit skills: X pass, Y warn, Z fail
```
资料来源：[src/cli/commands/audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)
## Security Considerations
Skills are designed with safety boundaries:
- **Read-only by default**: Skills provide guidance, not direct system access
- **User approval required**: External tools or destructive operations require explicit confirmation
- **Dry-run support**: All install and execution commands support dry-run mode
- **Scope validation**: Skills validate inputs before execution
## Best Practices
### Writing a New Skill
1. Create `skills//SKILL.md`
2. Add required frontmatter (`name`, `description`)
3. Write clear, actionable workflow steps
4. Include success criteria and failure modes
5. Reference any support files explicitly
6. Run `apx doctor` to validate
7. Submit for catalog inclusion
### Invoking Skills
Agents can invoke skills through:
1. **Direct reference**: Ask agent to "use the systematic-debugging skill"
2. **Command dispatch**: `apx info ` then paste content
3. **Auto-discovery**: Agent reads from installed `skills/` directory
## See Also
- [Plugin Bundles System](../plugins/) — Domain-specific skill collections
- [AGENTS.md Templates](../agents-md/) — Agent instruction templates
- [CLI Reference](../cli/) — Complete apx command documentation
- [Catalog Schema](../docs/catalog-schema.md) — Skill metadata specification
---
## Plugin Bundles
### 相关页面
相关主题：[Skills System](#skills-system), [apx CLI Reference](#cli-reference)
Relevant Source Files
以下源码文件用于生成本页说明：
- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)
- [.claude-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.claude-plugin/marketplace.json)
- [.codex-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.codex-plugin/marketplace.json)
- [docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)
- [src/cli/utils/plugins.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/plugins.ts)
# Plugin Bundles
## Overview
Plugin Bundles are the core packaging mechanism for distributing collections of reusable agent assets in the Agent Powerups ecosystem. Each bundle packages together related skills, agents, commands, templates, hooks, workflows, and MCP configurations into a single installable unit that can be validated, inspected, and deployed to coding agent environments.
The bundle system follows an Oh My Zsh-inspired philosophy: provide curated, community-verified collections of assets that extend agent capabilities without requiring manual configuration. Plugin bundles serve as the primary distribution vehicle for Agent Powerups content, enabling both automated installation via the `apx` CLI and manual inspection before deployment.
资料来源：[README.md:1-10]()
## Architecture
### Bundle Structure
Each plugin bundle follows a standardized directory layout aligned with coding agent plugin conventions. The structure ensures compatibility across multiple agent platforms while maintaining platform-specific manifest files.
```
/
├── .claude-plugin/
│ └── plugin.json # Claude Code/Claude manifest
├── .codex-plugin/
│ └── plugin.json # Codex manifest
├── skills/
│ └── /
│ └── SKILL.md
├── agents/
│ └── .md
├── commands/
│ └── .md
├── templates/ (optional)
│ └── .md
├── hooks/ (optional)
│ └── .ts
├── workflows/ (optional)
│ └── .yml
└── mcp/ (optional)
└── .json
```
资料来源：[plugins/README.md:18-36]()
### Manifest Files
The plugin manifest files define bundle metadata, dependencies, and platform-specific configurations. These manifests enable the `apx` CLI to validate, install, and manage plugin bundles across different agent environments.
**Claude Plugin Manifest** (`.claude-plugin/plugin.json`)
Defines the plugin for Claude Code and Claude agent platforms, including skills, agents, commands, and hooks.
**Codex Plugin Manifest** (`.codex-plugin/plugin.json`)
Provides equivalent metadata for OpenAI Codex and related Codex-based agents.
Both manifests share a common schema but may contain platform-specific instructions or configurations.
资料来源：[plugins/README.md:20-25]()
## Bundle Inventory
### Maturity Levels
Plugin bundles are classified into three maturity levels indicating their stability and readiness for production use.
| Maturity | Count | Description |
|----------|-------|-------------|
| **Stable** | 3 | Production-ready bundles with verified functionality |
| **Beta** | 10 | Functional bundles under active development, may have minor issues |
| **Experimental** | 4 | Early-stage bundles, API/behavior may change |
资料来源：[README.md:95-105]()
### Stable Bundles
These bundles have undergone extensive testing and are recommended for production use:
| Bundle | Description |
|--------|-------------|
| `dev-vitals` | Development vitals and health metrics |
| `debugging-diagnostics` | Systematic debugging workflows |
| `quality-gates` | Code quality verification gates |
### Beta Bundles
Active development bundles with functional but evolving content:
| Bundle | Description |
|--------|-------------|
| `codebase-maintenance` | Codebase maintenance utilities |
| `data-engineering` | Data pipeline and engineering tools |
| `documentation-systems` | Documentation generation and management |
| `machine-learning-ops` | ML operations and monitoring |
| `codebase-intelligence` | Code analysis and intelligence |
| `spec-driven-development` | Specification-driven development |
| `spec-quality-gates` | Adversarial plan verification and structured code review |
| `context-efficiency` | Context-efficient dispatch routers for workflow, review, and codebase commands |
| `tool-integrations` | External tool integration templates |
| `memory-optimization` | Context and memory optimization strategies |
资料来源：[README.md:95-105]()
### Experimental Bundles
Early-stage bundles exploring new functionality:
| Bundle | Description |
|--------|-------------|
| `software-engineering` | Advanced software engineering patterns |
| `agentic-systems` | Agent orchestration and coordination |
| `security-guardrails` | Security scanning and guardrails |
| `agent-evaluation-lab` | Agent performance evaluation |
## Bundle Schema
The `plugin-bundles.json` file serves as the central registry for all plugin bundles. Each bundle entry contains comprehensive metadata following a defined JSON schema.
```json
{
"name": "bundle-name",
"description": "Human-readable bundle description",
"maturity": "stable|beta|experimental",
"version": "1.0.0",
"skills": [
{ "name": "skill-name", "path": "skills/skill-name" }
],
"agents": [
{ "name": "agent-name", "path": "agents/agent-name.md" }
],
"commands": [
{ "name": "command-name", "path": "commands/command-name.md" }
],
"templates": [
{ "name": "template-name", "path": "templates/template-name.md" }
],
"hooks": [
{ "name": "hook-name", "path": "hooks/hook-name.ts" }
],
"workflows": [
{ "name": "workflow-name", "path": "workflows/workflow-name.yml" }
]
}
```
资料来源：[docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)
## CLI Commands for Plugin Management
The `apx` CLI provides comprehensive commands for discovering, inspecting, validating, and installing plugin bundles.
### Discovery Commands
```sh
apx plugins list # List all available bundles
apx plugins info # Inspect a specific bundle
apx plugins validate --all # Verify all bundle structures
```
### Installation Commands
```sh
apx plugins install --target --dry-run
apx install # Full manual install
```
资料来源：[README.md:85-92]()
### Validation Workflow
```mermaid
graph TD
A[apx plugins validate] --> B{Plugin exists?}
B -->|No| C[Return error: plugin not found]
B -->|Yes| D{Manifest files exist?}
D -->|Missing| E[Return error: missing manifest]
D -->|Present| F{Schema valid?}
F -->|Invalid| G[Return validation errors]
F -->|Valid| H[Return success]
```
资料来源：[src/cli/utils/plugins.ts:40-60]()
## Marketplace Integration
### Claude Code Marketplace
Plugin bundles can be published to the Claude Code marketplace via the `.claude-plugin/marketplace.json` file. This manifest defines marketplace metadata including categories, keywords, screenshots, and pricing information.
### Codex Marketplace
Similarly, `.codex-plugin/marketplace.json` provides marketplace configuration for Codex-based agents, ensuring discoverability across the agent platform ecosystem.
资料来源：[.claude-plugin/marketplace.json](), [.codex-plugin/marketplace.json]()
## Installation Process
### Dry-Run Validation
Before installation, always perform a dry-run to preview changes:
```sh
apx plugins install --target codex --dry-run
```
This command displays the planned file operations without modifying the filesystem, allowing review of bundle contents before committing changes.
资料来源：[README.md:85-88]()
### Full Installation
For actual installation, the `apx setup` command stages Agent Powerups assets, including plugin bundles:
```sh
apx setup codex --mode recommended --yes
apx setup claude-code --mode recommended --yes
```
The installation process:
1. Creates the plugin directory structure in the agent root
2. Copies bundle files to the appropriate locations
3. Registers skills, agents, and commands with the agent
4. Updates configuration files with appropriate references
资料来源：[src/cli/commands/setup.ts:1-50]()
## Safety Considerations
Plugin bundles may contain assets that modify agent behavior:
- **Skills** can instruct agents to read files or execute commands
- **Hooks** can execute code when supported by the host agent
- **MCP configs** can expand tool access capabilities
- **Install commands** can modify the local environment
Always review bundle contents before installation. The CLI provides validation commands to inspect bundle structure and content without installation.
> ⚠️ **Warning**: Review assets before loading them into a trusted agent environment. Secrets should never be pasted into agent context unless strictly necessary.
资料来源：[README.md:110-120]()
## Plugin Bundle Development
### Creating a New Bundle
1. Create the bundle directory structure following the standard layout
2. Add required manifest files (`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`)
3. Include at least one skill, agent, or command
4. Register the bundle in `plugin-bundles.json`
5. Run `apx plugins validate` to verify structure
### Bundle Validation
The validation system checks:
- Presence of required manifest files
- Schema compliance of all JSON configurations
- Existence of referenced skill, agent, and command files
- File size limits for security scanning
```sh
apx plugin validate
apx plugins validate --all
```
资料来源：[src/cli/utils/plugins.ts:40-70]()
## Related Documentation
- [Catalog Schema](./catalog-schema.md) - Detailed schema for asset catalogs
- [Security Model](./security-model.md) - Security considerations for agent assets
- [Setup Guides](./setup/) - Platform-specific installation instructions
- [CLI Reference](./docs/cli-reference.md) - Complete `apx` command documentation
---
## MCP Configurations
### 相关页面
相关主题：[Installation Guide](#installation), [Claude Code Integration](#claude-code-integration), [Codex Integration](#codex-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/claude-code/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/claude-code/github-local.json)
- [mcp/codex/github-local.toml](https://github.com/yeaight7/agent-powerups/blob/main/mcp/codex/github-local.toml)
- [mcp/generic/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/generic/github-local.json)
- [docs/mcp-configs.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/mcp-configs.md)
- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)
# MCP Configurations
## Overview
MCP (Model Context Protocol) Configurations in Agent Powerups provide pre-configured MCP server definitions that extend the tool access capabilities of coding agents. These configurations enable agents to interact with external services—such as GitHub—through a standardized protocol, allowing them to perform tasks like querying repositories, managing issues, or executing API operations that would otherwise require manual user intervention.
The MCP configuration system is designed with a **local-first** approach. Configurations are reviewed before loading, with explicit install commands and smoke tests to validate functionality before integration into an agent's environment. 资料来源：[README.md](./README.md)
## Purpose and Scope
Agent Powerups ships MCP configurations as part of its core asset delivery. The primary goals of these configurations are:
| Goal | Description |
|------|-------------|
| **Extensibility** | Provide agents with additional tool capabilities beyond their default feature set |
| **Safety** | Enable explicit, reviewable MCP server enablement with dry-run support |
| **Multi-Agent Support** | Offer variant configurations for different agent surfaces (Codex, Claude Code, generic) |
| **Validation** | Include check, smoke, and install commands to verify configuration integrity |
Currently, the shipped MCP configuration is `github-local`, which enables GitHub API interaction through a local MCP server setup. 资料来源：[README.md](./README.md) 资料来源：[mcp/generic/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/generic/github-local.json)
## Architecture
### Multi-Target Configuration Model
Agent Powerups maintains MCP configurations in variant-specific directories to support different agent platforms. Each variant may use a different configuration format or require platform-specific adjustments.
```
mcp/
├── claude-code/
│ └── github-local.json # Claude Code manifest format
├── codex/
│ └── github-local.toml # Codex TOML format
└── generic/
└── github-local.json # Generic JSON format
```
The CLI automatically selects the appropriate variant based on the `--target` parameter when executing MCP commands. 资料来源：[src/cli/commands/mcp.ts:51-55](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts) 资料来源：[docs/mcp-configs.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/mcp-configs.md)
### Configuration Resolution Flow
```mermaid
graph TD
A[apx mcp command] --> B{Which target?}
B -->|codex| C[Select TOML variant]
B -->|claude-code| D[Select JSON variant]
B -->|generic| E[Select JSON variant]
C --> F[Resolve target path]
D --> F
E --> F
F --> G{Command type?}
G -->|check| H[Validate config structure]
G -->|smoke| I[Execute smoke test]
G -->|install| J[Copy to agent root]
H --> K[Return validation result]
I --> L[Run server test]
J --> M[Write config to target]
```
## Available MCP Configurations
### github-local
The `github-local` MCP configuration provides GitHub API integration for coding agents. It requires environment variables for authentication and supports local-first operation without relying on cloud-based MCP routing.
| Property | Value |
|----------|-------|
| **Asset Name** | `github-local` |
| **Type** | mcp-config |
| **Required Env Vars** | `GITHUB_TOKEN` |
| **Target Support** | codex, claude-code, generic |
#### Variant Differences
| Agent | File Format | Manifest Location |
|-------|-------------|-------------------|
| Claude Code | JSON | `.claude-plugin/plugin.json` |
| Codex | TOML | `.codex-plugin/plugin.json` |
| Generic | JSON | Standard MCP JSON format |
资料来源：[mcp/generic/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/generic/github-local.json) 资料来源：[mcp/claude-code/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/claude-code/github-local.json) 资料来源：[mcp/codex/github-local.toml](https://github.com/yeaight7/agent-powerups/blob/main/mcp/codex/github-local.toml)
## MCP CLI Commands
The `apx` CLI provides several commands for working with MCP configurations. 资料来源：[src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)
### Command Reference
| Command | Description | Key Options |
|---------|-------------|-------------|
| `apx mcp list` | List all available MCP configurations | - |
| `apx mcp check --target ` | Validate configuration structure | `--json` for structured output |
| `apx mcp smoke ` | Execute smoke test against config | `--json` for structured output |
| `apx mcp print --target ` | Display configuration content | - |
| `apx mcp install --target ` | Install config to agent root | `--dry-run` for preview |
| `apx mcp write --target --dest ` | Write config to specific location | - |
### Target Parameters
| Target | Description |
|--------|-------------|
| `codex` | OpenAI Codex agent |
| `claude-code` | Anthropic Claude Code agent |
| `generic` | Platform-agnostic MCP configuration |
### Usage Examples
```bash
# Check configuration validity
apx mcp check github-local --target generic --json
# Smoke test the MCP server
apx mcp smoke github-local --json
# Preview installation
apx mcp install github-local --target codex --dry-run
# Install to Claude Code
apx mcp install github-local --target claude-code --dry-run
# Write to custom location
apx mcp write github-local --target generic --dest .agent-powerups/github-local.json
```
资料来源：[README.md](./README.md) 资料来源：[src/cli/commands/mcp.ts:51-55](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)
## Configuration Validation
### Check Command
The `check` command validates the structural integrity of an MCP configuration. It verifies:
- Required environment variables are documented
- Configuration file is valid JSON/TOML
- All referenced resources are present
```typescript
export async function runMcpCheckCommand(
service: CatalogService,
assetName: string,
target: InstallTarget,
env: NodeJS.ProcessEnv = process.env,
): Promise>
```
The command returns the required environment variables and their current status:
```json
{
"required_env": [
{ "name": "GITHUB_TOKEN", "set": true }
]
}
```
资料来源：[src/cli/commands/mcp.ts:57-75](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)
### Smoke Test
The `smoke` command performs a lightweight runtime verification of the MCP configuration. It attempts to initialize the MCP server with the provided configuration to ensure it can start without errors.
## Security Considerations
MCP configurations expand an agent's tool access capabilities. Review all configurations before loading them into a trusted agent environment.
### Security Warnings
| Warning | Description |
|---------|-------------|
| **Token Handling** | Replace placeholders like `${GITHUB_TOKEN}` or `YOUR_TOKEN_HERE` with actual values locally; never commit real tokens |
| **Tool Expansion** | MCP servers can significantly expand what actions an agent can perform |
| **Explicit Approval** | MCP servers require explicit user approval; always run `apx mcp check` and `apx mcp smoke` before enabling |
资料来源：[src/cli/commands/mcp.ts:40-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts) 资料来源：[README.md](./README.md)
### Safety Best Practices
1. **Review First**: Always inspect configuration content with `apx mcp print` before installing
2. **Dry Run**: Use `--dry-run` to preview all installation actions
3. **Smoke Test**: Run `apx mcp smoke` to verify the configuration works
4. **Environment Isolation**: Use environment variables for secrets rather than hardcoding
5. **Version Control**: Do not commit configuration files containing real credentials
## Integration with Setup Commands
MCP configurations can be installed as part of the broader agent setup process. When running `apx setup`, MCP configurations under `agent-powerups/mcp/` are included in the staging area.
```bash
# Setup includes MCP configs by default
apx setup codex --mode recommended --yes
# MCP configs are review-only in copied files
# Do not paste tokens into copied files
```
资料来源：[examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md) 资料来源：[examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)
## Adding New MCP Configurations
To add a new MCP configuration to Agent Powerups:
### 1. Create Configuration Files
Create variant-specific configurations in the appropriate subdirectories:
```
mcp/
├── /
│ └── .
├── /
│ └── .
└── generic/
└── .json
```
### 2. Register in Catalog
Add the configuration to the asset catalog with proper metadata:
```json
{
"name": "",
"type": "mcp-config",
"path": "mcp/generic/.json",
"targets": {
"codex": "mcp/codex/.toml",
"claude-code": "mcp/claude-code/.json"
},
"mcp": {
"required_env": ["API_TOKEN"],
"warning": "Requires valid API token"
}
}
```
### 3. Validate Structure
Test the configuration with the validation commands:
```bash
apx mcp check --target generic --json
apx mcp smoke --json
apx plugins validate --all # If part of a plugin bundle
```
## Summary
MCP Configurations in Agent Powerups provide a standardized, safe mechanism for extending coding agent capabilities through the Model Context Protocol. Key features include:
- **Multi-target support** for Codex, Claude Code, and generic agents
- **Local-first design** with explicit review and validation steps
- **Comprehensive CLI tooling** for check, smoke, and install operations
- **Security-first approach** requiring explicit approval and dry-run support
- **Variant-specific configurations** to accommodate different agent platforms
---
## Hooks and Commands
### 相关页面
相关主题：[Skills System](#skills-system), [Plugin Bundles](#plugin-bundles)
相关源码文件
以下源码文件用于生成本页说明：
- [hooks/productivity/no-secrets-preflight.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/no-secrets-preflight.md)
- [hooks/productivity/handoff-summary.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/handoff-summary.md)
- [hooks/quality/lint-check.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/lint-check.md)
- [hooks/quality/test-gate.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/test-gate.md)
- [commands/ship-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/ship-check.md)
- [commands/triage.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/triage.md)
- [docs/tool-requirements.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/tool-requirements.md)
# Hooks and Commands
## Overview
Hooks and Commands are two complementary systems within Agent Powerups that extend the capabilities of coding agents through structured automation and guided workflows. While both systems enhance agent behavior, they serve distinct purposes:
- **Hooks** are automated triggers that execute at specific points during agent operations, acting as pre-flight checks or post-action summaries
- **Commands** are structured, review-first prompts that guide agents through complex multi-step workflows
资料来源：[README.md]()
## Architecture Overview
```mermaid
graph TD
subgraph "Agent Environment"
A[Agent] --> |triggers| H[Hooks System]
A --> |invokes| C[Commands System]
end
subgraph "Hooks"
H --> |productivity| HP1[no-secrets-preflight]
H --> |productivity| HP2[handoff-summary]
H --> |quality| HQ1[lint-check]
H --> |quality| HQ2[test-gate]
end
subgraph "Commands"
C --> |ship| CS[ship-check]
C --> |triage| CT[triage]
end
H --> |execution| F[File System / API]
C --> |review prompts| R[Review Output]
```
## Hooks System
### Purpose and Scope
Hooks are lightweight automation units that execute automatically at defined points in an agent's lifecycle. They serve as:
1. **Pre-flight checks** - Validate conditions before actions proceed
2. **Post-action summaries** - Generate documentation after handoffs
3. **Quality gates** - Ensure code meets standards before progression
资料来源：[hooks/productivity/no-secrets-preflight.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/no-secrets-preflight.md)
### Hook Categories
| Category | Purpose | Hooks |
|----------|---------|-------|
| `productivity` | Workflow efficiency and safety | `no-secrets-preflight`, `handoff-summary` |
| `quality` | Code quality enforcement | `lint-check`, `test-gate` |
### Available Hooks
#### no-secrets-preflight
A productivity hook that scans files for potential secret exposure before agent operations proceed.
**Trigger**: Before file operations or commit actions
**Behavior**:
- Scans specified files and paths for patterns matching API keys, tokens, and credentials
- Flags common secret formats: AWS keys, GitHub tokens, database connection strings
- Reports findings without blocking (advisory mode)
资料来源：[hooks/productivity/no-secrets-preflight.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/no-secrets-preflight.md)
#### handoff-summary
A productivity hook that generates structured summaries during agent-to-agent or session-to-session handoffs.
**Trigger**: End of session or before context transfer
**Output**:
- Current work status
- Pending tasks and blockers
- Relevant context for the receiving agent
- File modifications summary
资料来源：[hooks/productivity/handoff-summary.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/handoff-summary.md)
#### lint-check
A quality hook that validates code style and linting compliance.
**Trigger**: Before commit or pull request creation
**Checks**:
- ESLint/Prettier compliance (TypeScript/JavaScript)
- Language-specific linting standards
- Configured rule violations
资料来源：[hooks/quality/lint-check.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/lint-check.md)
#### test-gate
A quality hook that ensures test coverage meets minimum thresholds before code progression.
**Trigger**: Before merge or deployment
**Thresholds**:
- Minimum coverage percentage (configurable)
- Required test categories passed
- No failing test suites
资料来源：[hooks/quality/test-gate.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/test-gate.md)
### Hook Execution
```mermaid
graph LR
A[apx hooks run] --> B[Load Hook Config]
B --> C[Scan Target Path]
C --> D{Hook Type?}
D -->|preflight| E[Execute Checks]
D -->|summary| F[Generate Report]
D -->|quality| G[Run Validations]
E --> H[Report Results]
F --> H
G --> I{Checks Pass?}
I -->|Yes| H
I -->|No| J[Block Action]
```
### Hook CLI Commands
| Command | Description |
|---------|-------------|
| `apx hooks list` | List all available hooks |
| `apx hooks print ` | Display hook definition and instructions |
| `apx hooks run --path ` | Execute hook on specified path |
| `apx hooks run --all` | Execute hook across entire workspace |
资料来源：[README.md]()
## Commands System
### Purpose and Scope
Commands are structured, review-first prompts designed for complex multi-step workflows. Unlike hooks which run automatically, commands are explicitly invoked by agents or users to:
1. **Guide complex processes** - Step-by-step workflows with checkpoints
2. **Enforce review points** - Mandatory review stages before progression
3. **Provide safe runnable checks** - Validated automation with human oversight
资料来源：[commands/ship-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/ship-check.md)
### Available Commands
#### ship-check
A comprehensive pre-release validation command that ensures code is ready for shipping.
**Stages**:
1. **Code Quality Review**
- Linting compliance
- Type checking
- Formatting standards
2. **Test Verification**
- Unit test coverage
- Integration test status
- E2E test results
3. **Security Scan**
- Secret detection
- Dependency vulnerability check
- License compliance
4. **Documentation Review**
- README completeness
- Changelog updates
- API documentation
5. **Final Review**
- Breaking change detection
- Version bump validation
- Release notes generation
资料来源：[commands/ship-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/ship-check.md)
#### triage
A command for systematic issue and PR triage workflow.
**Purpose**: Streamline the process of reviewing, categorizing, and prioritizing incoming issues and pull requests.
**Workflow**:
1. Extract issue/PR metadata
2. Assess priority and complexity
3. Assign appropriate labels
4. Route to relevant team members or skill sets
5. Document triage decision
资料来源：[commands/triage.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/triage.md)
### Command CLI Commands
| Command | Description |
|---------|-------------|
| `apx commands list` | List all available commands |
| `apx commands print --target ` | Print command for specific agent |
| `apx commands run --full` | Execute command with full details |
| `apx commands run --json` | Execute command with JSON output |
资料来源：[README.md]()
## Integration with Agent Workflows
### Hook-Command Relationship
```mermaid
graph TD
subgraph "Workflow"
C1[Start Task] --> H1[Hook: preflight check]
H1 --> |pass| C2[Plan Review]
H1 --> |fail| C3[Fix Issues]
C3 --> H1
C2 --> CMD1[Command: ship-check]
CMD1 --> H2[Hook: quality gate]
H2 --> |pass| CMD2[Command: triage]
H2 --> |fail| C3
CMD2 --> H3[Hook: handoff summary]
H3 --> C4[Complete]
end
```
### Target Agent Compatibility
| Asset | Codex | Claude Code | Gemini |
|-------|-------|-------------|--------|
| Hooks | ✅ | ✅ | ✅ |
| Commands | ✅ | ✅ | ✅ |
## Tool Requirements
Hooks and Commands may require external tools for full functionality:
### Required Tools by Hook
| Hook | Required Tools |
|------|----------------|
| `no-secrets-preflight` | `grep`, `find` |
| `lint-check` | `eslint`, `prettier` (or language-specific linter) |
| `test-gate` | `jest`, `pytest`, `go test` (language-specific) |
### Required Tools by Command
| Command | Required Tools |
|---------|----------------|
| `ship-check` | `git`, `npm`/`pip`/`cargo`, `eslint`/`ruff`, `jest`/`pytest` |
| `triage` | `gh` (GitHub CLI), `git` |
资料来源：[docs/tool-requirements.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/tool-requirements.md)
## Usage Examples
### Running a Single Hook
```bash
# Check for secrets in specific file
apx hooks run no-secrets-preflight --path ./config/secrets.yaml
# Check entire project
apx hooks run no-secrets-preflight --all
```
### Running a Command
```bash
# Execute ship-check with full output
apx commands run ship-check --full
# Get JSON output for automation
apx commands run ship-check --json
```
### Custom Hook Integration
Hooks can be integrated into agent workflows by adding to agent configuration:
```markdown
## Pre-Task Hooks
Before any file modification:
1. Run `apx hooks run no-secrets-preflight --path {target}`
## Post-Task Hooks
After task completion:
1. Run `apx hooks run handoff-summary --path {workspace}`
```
## Security Considerations
> **Warning**: Hooks can execute code when supported by the host agent. Review assets before loading them into a trusted agent environment.
资料来源：[README.md]()
### Security Best Practices
1. **Review hooks before enabling** - Examine hook logic for unintended side effects
2. **Limit hook scope** - Run hooks on specific paths rather than entire filesystem
3. **Validate tool access** - Ensure required tools are from trusted sources
4. **Monitor hook output** - Review all hook execution logs
## Extension Points
### Creating Custom Hooks
Custom hooks follow the same structure as shipped hooks:
```
hooks/
└── /
└── .md
```
### Creating Custom Commands
Custom commands follow the command structure:
```
commands/
└── .md
```
Both custom hooks and commands can be discovered and managed through the `apx` CLI using the standard `list`, `print`, and `run` subcommands.
## Summary
Hooks and Commands form the operational backbone of Agent Powerups, enabling:
- **Automated quality assurance** through hooks like `lint-check` and `test-gate`
- **Security pre-flight checks** via `no-secrets-preflight`
- **Workflow continuity** with `handoff-summary`
- **Guided complex workflows** through `ship-check` and `triage` commands
Together, they provide a framework for maintaining code quality, security, and consistent workflows across agent interactions.
---
## Claude Code Integration
### 相关页面
相关主题：[Installation Guide](#installation), [Codex Integration](#codex-integration), [Gemini Integration](#gemini-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)
- [docs/setup/claude-code.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/claude-code.md)
- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)
# Claude Code Integration
Claude Code Integration enables Agent Powerups assets to be installed and utilized within Claude Code agent environments. This integration provides a structured approach for staging reusable skills, plugin bundles, MCP configurations, and AGENTS.md templates specifically tailored for Claude Code workflows.
## Overview
Agent Powerups positions itself as "Oh My Zsh for coding agents," and Claude Code represents one of the primary supported agent surfaces. The integration allows Claude Code to access:
- Reusable skills located at `agent-powerups/skills/`
- Plugin bundles under `agent-powerups/plugins/`
- Command packs for specialized workflows
- MCP server configurations
- AGENTS.md instruction templates
资料来源：[README.md:1-50]()
## Agent Profile Configuration
Claude Code has a dedicated agent profile defined in the CLI setup system. This profile controls installation paths, environment variables, and instruction file locations.
| Configuration Key | Value |
|-------------------|-------|
| Agent identifier | `claude-code` |
| Display name | Claude Code |
| Instruction file | `CLAUDE.md` |
| Default root env vars | `CLAUDE_CONFIG_DIR`, `CLAUDE_HOME` |
| Default root directory | `~/.claude` |
| Command target directory | `claude-code` |
| MCP target directory | `claude-code` |
资料来源：[src/cli/commands/setup.ts:50-65]()
### Environment Variable Resolution
The setup system resolves the Claude Code root directory by checking environment variables in priority order:
1. `CLAUDE_CONFIG_DIR`
2. `CLAUDE_HOME`
3. Fallback to `~/.claude`
```mermaid
graph TD
A[Resolve Claude Code Root] --> B{CLAUDE_CONFIG_DIR set?}
B -->|Yes| C[Use CLAUDE_CONFIG_DIR]
B -->|No| D{CLAUDE_HOME set?}
D -->|Yes| E[Use CLAUDE_HOME]
D -->|No| F[Use ~/.claude]
C --> G[Install assets under resolved root]
E --> G
F --> G
```
资料来源：[src/cli/commands/setup.ts:50-65]()
## Installation Modes
Claude Code setup supports three installation modes that control the scope of assets deployed:
### Minimal Mode
Bootstrap setup that installs only essential skills. Recommended as a starting point for new users.
```powershell
apx setup claude-code --mode minimal --yes
```
Installed skills in minimal mode:
- `using-powerups`
- `no-fluff`
- `repo-map`
- `writing-plans`
- `verification-before-completion`
- `search-before-building`
资料来源：[src/cli/commands/setup.ts:95-100]()
### Recommended Mode
Full recommended setup that installs all stable plugin bundles and the complete skill catalog.
```powershell
apx setup claude-code --mode recommended --yes
```
This mode installs the stable plugin bundles:
- `dev-vitals`
- `debugging-diagnostics`
- `quality-gates`
资料来源：[src/cli/commands/setup.ts:100-105]()
### Full Mode
Comprehensive staging that includes support assets under `agent-powerups/` and updates existing global instructions with backup preservation.
```powershell
apx setup claude-code --mode full --yes
```
## Setup Workflow
### Dry-Run Validation
Before applying any changes, perform a dry-run to preview installation actions:
```powershell
apx setup claude-code --dry-run
```
This command displays what would be installed without making filesystem modifications.
### Instruction File Handling
The setup system handles existing `CLAUDE.md` files with the following logic:
```mermaid
graph TD
A[Setup Claude Code] --> B{CLAUDE.md exists?}
B -->|Yes| C[Create backup of CLAUDE.md]
B -->|Yes| D[Append agent-powerups block]
B -->|No| E[Create instructions directory]
B -->|No| F[Write agent-powerups.md]
D --> G[Report manual steps]
F --> G
```
When `CLAUDE.md` exists, the setup appends a marked block between `` and `` markers. When the file does not exist, setup writes instructions to `agent-powerups\instructions\agent-powerups.md` and reports manual steps required.
资料来源：[examples/claude-code/README.md:1-25]()
### Explicit Root Installation
For safer installation to a specific directory:
```powershell
apx setup claude-code --agent-root .agent-powerups-demo\claude --yes
```
This approach isolates the installation to a disposable location for review before committing to the actual Claude Code configuration.
## Asset Deployment Structure
The setup system copies assets to the following structure under the Claude Code root:
| Source Directory | Target Directory |
|-----------------|------------------|
| `skills/` | `agent-powerups/skills/` |
| `agents-md/` | `agent-powerups/agents-md/` |
| `hooks/` | `agent-powerups/hooks/` |
| `workflows/` | `agent-powerups/workflows/` |
| `commands/generic/` | `agent-powerups/commands/generic/` |
| `mcp/generic/` | `agent-powerups/mcp/generic/` |
| `docs/setup/` | `agent-powerups/docs/setup/` |
资料来源：[src/cli/commands/setup.ts:150-160]()
## MCP Configuration for Claude Code
Claude Code has a dedicated MCP target directory. MCP configurations are placed under `agent-powerups/mcp/claude-code/` for review purposes.
### MCP Check Command
Validate an MCP configuration for Claude Code:
```powershell
apx mcp check github-local --target claude-code
```
### MCP Smoke Test
Perform a smoke test on MCP configuration:
```powershell
apx mcp smoke github-local --json
```
### MCP Install Preview
Preview a managed Claude Code MCP installation:
```powershell
apx mcp install github-local --target claude-code --dry-run
```
资料来源：[src/cli/commands/mcp.ts:1-30]()
### Security Notes
MCP snippets under `agent-powerups/mcp/` are marked as review-only. Users should not paste tokens into copied files without local substitution of placeholders.
## Post-Installation Verification
After setup, verify the installation using these commands:
```powershell
apx commands print ship-check --target claude-code
apx info using-powerups
```
### Available Commands for Claude Code
| Command | Purpose |
|---------|---------|
| `ship-check` | Run pre-ship validation checks |
| `using-powerups` | Guide for using Agent Powerups |
### Available Skills
After installation, Claude Code has access to skills including:
- `systematic-debugging`
- `no-fluff`
- `writing-plans`
- `ai-slop-cleaner`
- `bigquery-cost-audit`
- `data-quality`
- `dbt-incremental-strategy-audit`
- `dbt-preflight`
- `dbt-strategy`
- `metric-impact-analyzer`
- `requesting-code-review`
- `receiving-code-review`
- `pr-triage`
- `repo-map`
- `bug-hunt`
- `safe-refactor`
- `sql-business-logic-review`
- `defuddle`
- `markitdown-file-intake`
- `graphify`
## Plugin Bundles
Claude Code supports installation of plugin bundles that group related skills, agents, and commands.
### Stable Plugin Bundles
| Bundle | Description |
|--------|-------------|
| `dev-vitals` | Development vitals monitoring |
| `debugging-diagnostics` | Debugging and diagnostic tools |
| `quality-gates` | Code quality enforcement |
### Beta Plugin Bundles
Available beta bundles include `codebase-maintenance`, `data-engineering`, `documentation-systems`, `machine-learning-ops`, `codebase-intelligence`, `spec-driven-development`, `spec-quality-gates`, `context-efficiency`, `tool-integrations`, and `memory-optimization`.
### Plugin Installation
```powershell
apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target claude-code --dry-run
```
## Rollback and Cleanup
To remove an Agent Powerups installation from Claude Code:
```powershell
Remove-Item .agent-powerups-demo -Recurse -Force
```
Replace `.agent-powerups-demo` with the actual installation path if a custom root was specified.
## Example: Complete Setup Workflow
```mermaid
graph LR
A[apx doctor] --> B[apx list]
B --> C[apx setup claude-code --dry-run]
C --> D[apx setup claude-code --mode recommended --yes]
D --> E[apx commands print ship-check --target claude-code]
E --> F[apx plugins install dev-vitals --target claude-code]
```
1. Run system diagnostics:
```powershell
apx doctor
```
2. List available assets:
```powershell
apx list
```
3. Preview setup:
```powershell
apx setup claude-code --dry-run
```
4. Apply recommended setup:
```powershell
apx setup claude-code --mode recommended --yes
```
5. Verify command availability:
```powershell
apx commands print ship-check --target claude-code
```
6. Install desired plugin bundle:
```powershell
apx plugins install dev-vitals --target claude-code
```
资料来源：[examples/claude-code/README.md:1-30]()
## Limitations and Considerations
- The integration does not modify Claude Code's core configuration files directly
- MCP server tokens must be replaced locally and should never be committed
- External tools require explicit user approval before installation
- Skills may instruct Claude Code to read local files or run commands—review assets before loading them into a trusted agent environment
- Shell profiles, secrets, background processes, hooks, and MCP servers are not automatically enabled
---
## Codex Integration
### 相关页面
相关主题：[Installation Guide](#installation), [Claude Code Integration](#claude-code-integration), [Gemini Integration](#gemini-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)
- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)
- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)
# Codex Integration
## Overview
The Codex Integration module provides native installation, configuration, and management capabilities for deploying Agent Powerups assets into a Codex agent environment. Codex, developed by OpenAI, is a coding agent that can read and modify codebases, execute commands, and assist with software development tasks. The integration layer bridges Agent Powerups' skill system, plugin bundles, MCP configurations, and command templates with Codex's agent surface.
Agent Powerups acts as an "Oh My Zsh for coding agents" — providing reusable workflows, skills, and configurations that extend the native capabilities of supported agent platforms. For Codex specifically, the integration handles:
- Copying skills and plugin bundles to the appropriate directory structure
- Managing the `AGENTS.md` instruction file with marked powerups blocks
- Configuring MCP server snippets for GitHub integration
- Validating requirements and performing pre-flight checks
- Providing a safe, review-first workflow before any mutations occur
资料来源：[README.md](./README.md)
## Architecture
### Agent Profile Configuration
The Codex agent profile defines the target environment for all installation operations. The profile is defined in `setup.ts` and establishes critical path mappings:
| Parameter | Value | Purpose |
|-----------|-------|---------|
| `agent` | `codex` | Agent identifier |
| `displayName` | `Codex` | Human-readable name |
| `defaultRootEnv` | `["CODEX_HOME"]` | Environment variable for agent root |
| `defaultRootDir` | `~/.codex` | Default installation directory |
| `instructionFileName` | `AGENTS.md` | Primary instruction file |
| `commandTargetDir` | `codex` | Subdirectory for command assets |
| `mcpTargetDir` | `codex` | Subdirectory for MCP configurations |
资料来源：[src/cli/commands/setup.ts:46-58](src/cli/commands/setup.ts#L46-L58)
### Directory Structure
After successful integration, the following structure is created under `/agent-powerups/`:
```
/
├── agent-powerups/
│ ├── skills/ # Reusable agent workflows
│ ├── plugins/ # Plugin bundles
│ ├── agents-md/ # AGENTS.md templates
│ ├── commands/codex/ # Codex-specific commands
│ ├── mcp/codex/ # MCP server configurations
│ ├── hooks/ # Hook examples
│ ├── workflows/ # Workflow templates
│ └── docs/setup/ # Setup documentation
└── AGENTS.md # Updated with powerups block
```
资料来源：[src/cli/commands/setup.ts:120-135](src/cli/commands/setup.ts#L120-L135)
## Installation Modes
Agent Powerups supports three installation modes for Codex, each catering to different use cases and risk tolerances.
### Mode Comparison
| Mode | Description | Use Case |
|------|-------------|----------|
| `minimal` | Bootstrap only with core skills | Testing, constrained environments |
| `recommended` | Full skill set with stable plugin bundles | Standard development workflow |
| `full` | Complete staging with all assets | Thorough setup, maximum coverage |
资料来源：[README.md](./README.md)
### Minimal Mode Skills
The minimal mode installs a curated set of essential skills that provide fundamental capabilities without overwhelming the agent with specialized workflows:
```typescript
const MINIMAL_SKILLS = [
"using-powerups", // Orientation to Agent Powerups system
"no-fluff", // Concise, actionable responses
"repo-map", // Repository structure understanding
"writing-plans", // Structured planning capabilities
"verification-before-completion", // Output validation
"search-before-building", // Existing code investigation
] as const;
```
资料来源：[src/cli/commands/setup.ts:80-87](src/cli/commands/setup.ts#L80-L87)
### Recommended Mode Additions
The recommended mode includes the minimal skills plus stable plugin bundles that enhance development productivity:
```typescript
const RECOMMENDED_PLUGIN_BUNDLES = [
"dev-vitals", // Development health metrics
"debugging-diagnostics", // Systematic debugging workflows
"quality-gates", // Code quality checkpoints
] as const;
```
资料来源：[src/cli/commands/setup.ts:89-93](src/cli/commands/setup.ts#L89-L93)
## Workflows
### Manual Native Install
The primary installation path for humans is the `apx install` command, which writes native skills and plugin bundles directly to the agent root.
```sh
# Dry run to preview changes
apx install codex --dry-run
# Standard install with output summary
apx install codex
# Verbose mode showing per-file paths
apx install codex --verbose
# Full install including support assets and instruction updates
apx install codex --full
```
资料来源：[README.md](./README.md)
### Agent-Curated Setup
For agent-managed installations, the setup workflow provides an interactive planning phase:
```sh
# Preview what will happen
apx setup codex --dry-run
# Apply recommended setup
apx setup codex --mode recommended --yes
```
The agent will inspect available skills and plugins, propose a plan, and apply it after user approval.
资料来源：[README.md](./README.md)
### MCP Server Integration
The GitHub MCP server can be integrated with Codex for extended GitHub functionality:
```sh
# Check MCP configuration validity
apx mcp check github-local --target codex --json
# Smoke test the MCP setup
apx mcp smoke github-local --json
# Dry run before installation
apx mcp install github-local --target codex --dry-run
# Print MCP configuration for review
apx mcp print github-local --target codex
```
资料来源：[README.md](./README.md)
### Plugin Bundle Installation
Individual plugin bundles can be installed for specific functionality:
```sh
# List available bundles
apx plugins list
# Inspect a specific bundle
apx plugins info dev-vitals
# Validate bundle structure
apx plugins validate --all
# Install to Codex with dry run
apx plugins install dev-vitals --target codex --dry-run
```
资料来源：[README.md](./README.md)
## Instruction File Management
### Block Format
The integration uses HTML comment markers to wrap the Agent Powerups section in `AGENTS.md`:
```markdown
## Agent Powerups
Agent Powerups assets are installed at `/agent-powerups/`.
Use these local assets when relevant:
- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.
- Use `apx` commands to discover, inspect, validate, and extend setup.
- Skills are at `agent-powerups/skills/`.
- Plugin bundles are at `agent-powerups/plugins/`.
```
### Instruction Generation Logic
The instruction block content varies based on the selected mode:
| Mode | Instruction Content |
|------|---------------------|
| `minimal` | Bootstrap guidance with `apx setup` command for recommended mode |
| `recommended` | Full asset paths, skill locations, MCP guidance, and external tool approval workflow |
| `full` | Complete instructions with all assets and configuration details |
资料来源：[src/cli/commands/setup.ts:20-50](src/cli/commands/setup.ts#L20-L50)
### Safe Update Behavior
The system implements safe update patterns to protect existing configurations:
1. If `AGENTS.md` exists, a backup is created before modification
2. The system searches for existing `agent-powerups` blocks
3. If a block exists, it is replaced; otherwise, a new block is appended
4. If `AGENTS.md` does not exist, instructions are written to `agent-powerups/instructions/agent-powerups.md` with manual steps reported
资料来源：[examples/codex/README.md](examples/codex/README.md)
## Validation and Health Checks
### Doctor Command
The `apx doctor` command performs comprehensive health checks on the installation:
```sh
apx doctor
```
Doctor checks include:
- Validating `SKILL.md` frontmatter (name and description required)
- Verifying support file references exist
- Checking referenced support files are present
```typescript
const frontmatter = parseFrontmatter(content);
if (!frontmatter?.name || !frontmatter?.description) {
issues.push(`${entry.name}: missing required frontmatter`);
}
for (const ref of referencedSupportFiles(content)) {
if (!(await supportRefExists(skillDir, ref))) {
issues.push(`${entry.name}: missing referenced support file ${ref}`);
}
}
```
资料来源：[src/cli/commands/doctor.ts:60-75](src/cli/commands/doctor.ts#L60-L75)
### Requirement Checks
The `apx check` command validates that requirements are met:
```sh
apx check
```
This includes:
- Parsing requirement declarations from skill and command files
- Verifying installed versions match requirements
- Optionally installing missing requirements with user approval
```typescript
const hasFailures = statuses.some((status) => status.status === "MISSING");
if (hasFailures) {
failures += 1;
if (installOptions?.installMissing) {
const installResult = await installMissingRequirements(...);
}
}
```
资料来源：[src/cli/commands/check.ts:45-60](src/cli/commands/check.ts#L45-L60)
### Security Audit
The security audit command scans for potential vulnerabilities in configuration files:
```sh
apx security-audit
```
Detectable patterns include:
- Unpinned `:latest` container images
- Broad filesystem write patterns
- Install commands without `--dry-run` guards
- Exposed secrets in configuration
```typescript
{
name: "broad-filesystem-write",
severity: "P1",
pattern: /(?:rm\s+-rf\s+\/|"path"\s*:\s*"\*\*|write_file\s+\/\*\*)/i,
detail: () => `broad filesystem write or recursive delete pattern`,
},
{
name: "missing-dry-run",
severity: "P1",
pattern: /(?:npm\s+install|pip\s+install|cargo\s+install|gem\s+install)\b(?!.*(?:--dry-run|-n\b))/i,
detail: (m) => `install command without --dry-run guard: ${m.trim().slice(0, 60)}`,
},
```
资料来源：[src/cli/commands/security-audit.ts:25-40](src/cli/commands/security-audit.ts#L25-L40)
## Example Workflow
### Setting Up for Codex Review
A typical workflow for staging Agent Powerups for Codex review:
```powershell
# 1. Preview installation changes
apx setup codex --dry-run
# 2. Apply with explicit root directory
apx setup codex --agent-root .agent-powerups-demo\codex --yes
# 3. Inspect installed skills
apx info using-powerups
apx check using-powerups
# 4. List available commands
apx commands list
# 5. Run pre-flight checks
apx commands run ship-check
apx hooks run no-secrets-preflight --all
# 6. Validate MCP configuration
apx mcp check github-local --target codex --json
apx mcp smoke github-local --json
```
资料来源：[examples/codex/README.md](examples/codex/README.md)
### Rollback Procedure
To remove the integration and restore the original state:
```powershell
Remove-Item .agent-powerups-demo -Recurse -Force
```
资料来源：[examples/minimal/README.md](examples/minimal/README.md)
## Safety Model
The integration implements safety boundaries around several areas:
| Category | Protection Mechanism |
|----------|---------------------|
| External tools | Require explicit user approval |
| Secrets | Never paste into agent context unless strictly necessary |
| Shell profiles | Not modified automatically |
| MCP enablement | Requires explicit user approval after `apx mcp check` and `apx mcp smoke` |
| Installation | Default to dry-run; require `--yes` for mutations |
资料来源：[README.md](./README.md)
The security audit further enforces safety by detecting:
- Unpinned container images in CI configurations
- Dangerous filesystem operations
- Install commands without dry-run guards
资料来源：[src/cli/commands/security-audit.ts:25-45](src/cli/commands/security-audit.ts#L25-L45)
## Requirements Installation
When requirements are missing, the system can automatically install them:
```sh
apx check --install-missing --yes
```
The installation flow:
1. Identifies supported installers for the platform (npm, pip, cargo, gem)
2. Generates dry-run output if `--dry-run` is specified
3. Prompts for confirmation in interactive mode
4. Executes approved installers with appropriate arguments
```typescript
const approved = options.yes || (await confirmInstall(assetName, installers));
if (!approved) {
return {
output: "install-missing: declined or non-interactive without --yes",
warnings: [`${assetName}: install-missing not approved`],
actions: [],
};
}
```
资料来源：[src/cli/utils/requirements.ts:35-55](src/cli/utils/requirements.ts#L35-L55)
## External Commands Execution
When running external commands (e.g., during doctor checks or requirement installation), the system handles platform differences:
```typescript
const launchCommand = process.platform === "win32" && command.endsWith(".cmd")
? "cmd.exe"
: command;
const launchArgs = process.platform === "win32" && command.endsWith(".cmd")
? ["/d", "/s", "/c", command, ...args]
: args;
```
This ensures proper execution on Windows while maintaining cross-platform compatibility.
资料来源：[src/cli/commands/doctor.ts:78-83](src/cli/commands/doctor.ts#L78-L83)
---
## Gemini Integration
### 相关页面
相关主题：[Installation Guide](#installation), [Claude Code Integration](#claude-code-integration), [Codex Integration](#codex-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md)
- [GEMINI.md](https://github.com/yeaight7/agent-powerups/blob/main/GEMINI.md)
- [gemini-extension.json](https://github.com/yeaight7/agent-powerups/blob/main/gemini-extension.json)
- [workflows/agent-relay.md](https://github.com/yeaight7/agent-powerups/blob/main/workflows/agent-relay.md)
- [src/cli/commands/relay.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/relay.ts)
- [src/cli/commands/ask.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/ask.ts)
# Gemini Integration
## Overview
Gemini Integration in Agent Powerups provides a persistent secondary-agent delegation system that enables coding agents to leverage Google's Gemini AI as a reliable backup or complementary reasoning engine. The integration supports both one-shot queries via the `ask` CLI command and persistent relay sessions that maintain context across multiple conversation turns.
The Gemini integration follows the same Oh My Zsh-style philosophy as the rest of Agent Powerups—providing reusable, composable assets that extend agent capabilities without requiring deep configuration or manual setup. 资料来源：[README.md](./README.md)
## Architecture
The Gemini Integration consists of three primary layers working in concert:
```mermaid
graph TD
subgraph "CLI Layer"
A["apx ask-gemini"] --> B["ask.ts"]
C["apx relay"] --> D["relay.ts"]
end
subgraph "Integration Layer"
B --> E["Gemini API"]
D --> E
F["gemini-extension.json"] --> G["Plugin Bundle"]
end
subgraph "Agent Layer"
G --> H["Claude Code"]
G --> I["Codex"]
E --> J["Persistent Context"]
end
```
### Core Components
| Component | Type | Purpose |
|-----------|------|---------|
| `gemini-extension.json` | Plugin Bundle | Claude Code manifest with Gemini extension configuration |
| `GEMINI.md` | Context File | Default context instructions for Gemini integration |
| `ask-gemini` | Skill | One-shot delegation skill for single queries |
| `agent-relay` | Workflow | Persistent relay session workflow |
| `ask.ts` | CLI Command | Single query execution handler |
| `relay.ts` | CLI Command | Persistent session management |
资料来源：[gemini-extension.json](https://github.com/yeaight7/agent-powerups/blob/main/gemini-extension.json) | [src/cli/commands/ask.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/ask.ts) | [src/cli/commands/relay.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/relay.ts)
## Setup and Configuration
### Prerequisites
Before using Gemini Integration, ensure the following are available:
- Node.js environment with `apx` CLI installed
- Valid Google AI API credentials (Gemini API key)
- Agent Powerups installed via `npm install && npm run build && npm link`
资料来源：[docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md)
### Installation Methods
Agent Powerups supports multiple installation paths for Gemini integration:
#### Manual Native Install
```sh
apx install gemini --dry-run
apx install gemini
apx install gemini --full --verbose
```
The `--full` flag stages support assets under `agent-powerups/` and updates existing global instructions with a backup. 资料来源：[README.md](./README.md)
#### Agent-Curated Setup
```sh
apx setup gemini --dry-run
apx setup gemini --mode minimal --yes # bootstrap only
apx setup gemini --mode recommended --yes # recommended setup
apx setup gemini --mode full --yes # broad staging
```
The setup process appends a marked `agent-powerups` block to the agent's instructions file after creating a backup. 资料来源：[docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md) | [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
### Environment Variables
The following environment variables are required or optional:
| Variable | Required | Description |
|----------|----------|-------------|
| `GEMINI_API_KEY` | Yes | Google AI API key for Gemini access |
| `GEMINI_MODEL` | No | Specific Gemini model variant (defaults to provider default) |
## One-Shot Query Mode
The `ask-gemini` command provides immediate delegation for single queries without maintaining conversation state:
```sh
apx ask-gemini "Return OK only" --json
```
### Usage Patterns
```sh
# Basic query with JSON output
apx ask-gemini "Review this plan" --json
# Check dependencies without execution
apx check ask-gemini
# Preview missing dependencies
apx check ask-gemini --install-missing --dry-run
```
资料来源：[README.md](./README.md)
### Data Flow
```mermaid
sequenceDiagram
participant User
participant CLI as apx ask-gemini
participant API as Gemini API
participant Output as JSON Response
User->>CLI: apx ask-gemini "query" --json
CLI->>API: POST request with prompt
API->>Output: JSON response
Output-->>User: Structured result
```
## Persistent Relay Sessions
The relay system maintains persistent context across multiple conversation turns, enabling more coherent multi-turn workflows:
```sh
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
```
### Session Lifecycle
| Command | Purpose |
|---------|---------|
| `apx relay init ` | Initialize a new relay session |
| `apx relay start --provider gemini` | Start the session with Gemini provider |
| `apx relay ask ""` | Send a query within the session |
| `apx relay status ` | Check session status |
| `apx relay stop ` | Terminate the session |
资料来源：[workflows/agent-relay.md](https://github.com/yeaight7/agent-powerups/blob/main/workflows/agent-relay.md) | [src/cli/commands/relay.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/relay.ts)
### Relay Workflow Architecture
```mermaid
graph LR
A[User Request] --> B[Relay Init]
B --> C[Relay Start]
C --> D[Context Established]
D --> E[Relay Ask Query]
E --> F[Gemini API]
F --> G[Response + Updated Context]
G --> E
G --> H[Relay Stop]
```
## Plugin Bundle Structure
The Gemini extension plugin bundle includes manifests for multiple agent surfaces:
```
gemini-extension/
├── .claude-plugin/
│ └── plugin.json # Claude Code Manifest
├── .codex-plugin/
│ └── plugin.json # Codex Manifest
├── GEMINI.md # Context instructions
└── skills/
└── ask-gemini/
└── SKILL.md
```
### Manifest Validation
The `apx doctor` command validates plugin bundle integrity across all agent targets:
```sh
apx doctor --full --json
```
Validation checks include:
- File existence in all required paths
- Manifest name consistency
- Manifest version alignment (must be `0.1.0`)
- Context filename verification (`GEMINI.md` for Gemini)
资料来源：[src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts) | [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
## Integration with Profiles
Gemini Integration can be accessed through user-intent profiles that bundle relevant skills and plugins:
```sh
apx profiles list
apx profiles info safe-core
apx profiles plan safe-core --target codex
```
Profiles provide curated skill/plugin sets optimized for specific use cases, potentially including `ask-gemini` as part of a secondary-opinion workflow. 资料来源：[README.md](./README.md)
## Safety Considerations
### Security Warnings
The Gemini integration follows Agent Powerups security model:
- **External Tools**: Require explicit user approval before installation
- **API Keys**: Never paste tokens directly into agent context unless strictly necessary
- **MCP Servers**: Require explicit user approval via `apx mcp check` and `apx mcp smoke` before enabling
```sh
# Verify MCP configuration before enabling
apx mcp check github-local --target generic
apx mcp smoke github-local --json
```
资料来源：[README.md](./README.md) | [docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md)
### Dry-Run First
Always preview operations before execution:
```sh
# Preview setup without applying
apx setup gemini --dry-run
# Preview installation without writing
apx install gemini --dry-run
```
Dry-run mode shows the planned actions without modifying any files, allowing review of changes before acceptance. 资料来源：[docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md)
## Command Reference
### Quick Reference Table
| Command | Description |
|---------|-------------|
| `apx install gemini` | Install Gemini integration natively |
| `apx setup gemini --dry-run` | Preview Gemini setup |
| `apx setup gemini --mode recommended --yes` | Apply recommended Gemini setup |
| `apx ask-gemini "" --json` | One-shot Gemini query |
| `apx relay init ` | Initialize relay session |
| `apx relay start --provider gemini` | Start Gemini relay |
| `apx relay ask "" --json` | Query in relay session |
| `apx check ask-gemini` | Verify Gemini dependencies |
| `apx plugins info gemini-extension` | Inspect plugin bundle |
| `apx plugins install gemini-extension --target --dry-run` | Preview plugin install |
### Workflow Integration
The Gemini integration supports the `agent-relay` workflow for complex multi-turn scenarios:
```sh
apx workflows list
apx workflows print feature-iteration
apx workflows print agent-relay
```
This enables using Gemini as a persistent second opinion during feature development iterations. 资料来源：[workflows/agent-relay.md](https://github.com/yeaight7/agent-powerups/blob/main/workflows/agent-relay.md) | [README.md](./README.md)
---
---
## Doramagic 踩坑日志
项目：yeaight7/agent-powerups
摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。
## 1. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `agent-powerups` 与安装入口 `markitdown` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`pip install markitdown`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown
## 2. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code
## 3. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass.
## 4. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing
## 5. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium
## 6. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium
## 7. 安全/权限坑 · 来源证据：v0.1.4
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 8. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown
## 9. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown