{
"canonical_name": "yeaight7/agent-powerups",
"compilation_id": "pack_7532049be2574c22b0041ab7a8ac5fd3",
"created_at": "2026-05-19T05:00:18.736967+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install markitdown` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install markitdown",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_d90e80de2dca46afa236e228cedd7728"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_ceb60fe2fa1323e2f024fff027828339",
"canonical_name": "yeaight7/agent-powerups",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/yeaight7/agent-powerups",
"slug": "agent-powerups",
"source_packet_id": "phit_c5745398d684433eb2d00c82003f72bf",
"source_validation_id": "dval_46a15f0d1ac6497ebd20b0b26688a543"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 4,
"one_liner_en": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"one_liner_zh": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:code, coding, git"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "agent-powerups",
"title_zh": "agent-powerups 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_c5745398d684433eb2d00c82003f72bf",
"page_model": {
"artifacts": {
"artifact_slug": "agent-powerups",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install markitdown",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/yeaight7/agent-powerups#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "仓库名 `agent-powerups` 与安装入口 `markitdown` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.1.4",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 4
},
"source_url": "https://github.com/yeaight7/agent-powerups",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"title": "agent-powerups 能力包",
"trial_prompt": "# agent-powerups - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for yeaight7/agent-powerups.\n\nProject:\n- Name: agent-powerups\n- Repository: https://github.com/yeaight7/agent-powerups\n- Summary: Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more\n- Host target: mcp_host, claude, claude_code\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. writing-plans: Source-backed workflow step 1. Produce one small intermediate artifact and wait for confirmation.\n2. systematic-debugging: Source-backed workflow step 2. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/yeaight7/agent-powerups\n- https://github.com/yeaight7/agent-powerups#readme\n- plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md\n- plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md\n- plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md\n- plugins/agentic-systems/skills/agent-harness-design/SKILL.md\n- plugins/agentic-systems/skills/canonical-advisor-routing/SKILL.md\n- plugins/agentic-systems/skills/context-retrieval-loop/SKILL.md\n- plugins/agentic-systems/skills/model-routing/SKILL.md\n- plugins/agentic-systems/skills/tri-model-review/SKILL.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v0.1.4（https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4）；github/github_release: v0.1.2（https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v0.1.4",
"url": "https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.1.2",
"url": "https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.2"
}
],
"status": "已收录 2 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"effort": "安装已验证",
"forks": 0,
"icon": "code",
"name": "agent-powerups 能力包",
"risk": "需复核",
"slug": "agent-powerups",
"stars": 4,
"tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/yeaight7/agent-powerups 项目说明书\n\n生成时间：2026-05-15 17:26:54 UTC\n\n## 目录\n\n- [Project Overview](#overview)\n- [Installation Guide](#installation)\n- [apx CLI Reference](#cli-reference)\n- [Skills System](#skills-system)\n- [Plugin Bundles](#plugin-bundles)\n- [MCP Configurations](#mcp-configurations)\n- [Hooks and Commands](#hooks-commands)\n- [Claude Code Integration](#claude-code-integration)\n- [Codex Integration](#codex-integration)\n- [Gemini Integration](#gemini-integration)\n\n\n\n## Project Overview\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [apx CLI Reference](#cli-reference), [Skills System](#skills-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [package.json](https://github.com/yeaight7/agent-powerups/blob/main/package.json)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n \n\n# Project Overview\n\nAgent 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.\n\n## Project Purpose\n\nThe 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.\n\nKey objectives:\n\n- Provide **portable, validated skills** that encode best-practice workflows (debugging, code review, planning)\n- Enable **explicit, auditable installation** of agent extensions rather than opaque粘贴\n- Support **multi-agent compatibility** with a single codebase\n- Maintain **safety boundaries** around secrets, shell access, and MCP server enablement\n- Offer **graduated onboarding** through user-intent profiles and dry-run validation\n\n## Architecture Overview\n\nAgent Powerups follows a layered architecture with three primary concerns:\n\n1. **Catalog Layer**: JSON manifests (`catalog.json`, `plugin-bundles.json`, `profiles.json`) that index all available assets\n2. **CLI Layer**: The `apx` command-line interface that provides discovery, validation, and installation\n3. **Asset Layer**: The actual skill files, command packs, MCP configs, hooks, and workflow templates\n\n```mermaid\ngraph TD\n A[User / Agent] -->|apx commands| B[CLI Layer: apx]\n B -->|read| C[Catalog Layer: JSON manifests]\n B -->|validate| D[Source Assets]\n C -->|index| D\n D -->|skills| E[skills/]\n D -->|commands| F[commands/]\n D -->|mcp configs| G[mcp/]\n D -->|hooks| H[hooks/]\n D -->|workflows| I[workflows/]\n D -->|agents-md| J[agents-md/]\n D -->|plugins| K[plugins/]\n B -->|install to| L[Target Agent Root]\n L -->|codex| M[Codex agents]\n L -->|claude-code| N[Claude Code agents]\n L -->|gemini| O[Gemini CLI agents]\n```\n\n## CLI Interface (apx)\n\nThe `apx` CLI is the primary user interface for Agent Powerups. It is implemented in TypeScript and published as the `agent-powerups` npm package.\n\n### Installation\n\n```sh\nnpm install -g agent-powerups\n```\n\nThe CLI requires **Node.js >= 20** and is published at `npm:agent-powerups`.\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `apx list` | List all available skills, commands, and assets |\n| `apx info ` | Display detailed information about a specific asset |\n| `apx check ` | Validate requirements for an asset |\n| `apx doctor` | Run health checks on the local installation |\n| `apx setup ` | Install Agent Powerups to a target agent's root |\n| `apx install ` | Native install of all assets to agent root |\n| `apx plugins list` | List available plugin bundles |\n| `apx plugins install ` | Install a plugin bundle to target |\n| `apx commands run ` | Execute a command pack |\n| `apx hooks run ` | Execute a hook script |\n| `apx mcp check ` | Validate an MCP configuration |\n| `apx mcp smoke ` | Run smoke tests for an MCP server |\n| `apx relay init ` | Initialize a persistent relay session |\n| `apx profiles list` | List available user-intent profiles |\n| `apx ask-claude` | Query Claude for advice via local CLI |\n| `apx ask-gemini` | Query Gemini for advice via local CLI |\n| `apx ask-codex` | Query Codex for advice via local CLI |\n\n资料来源：[package.json:16](https://github.com/yeaight7/agent-powerups/blob/main/package.json)\n\n## Asset Catalog\n\n### Skills\n\nSkills are Markdown files that encode reusable agent workflows. Each skill follows a standardized structure with frontmatter metadata.\n\nCurrent shipped skills include:\n\n| Skill Name | Purpose |\n|------------|---------|\n| `systematic-debugging` | Structured debugging methodology |\n| `no-fluff` | Concise output filtering |\n| `writing-plans` | Project planning workflow |\n| `ai-slop-cleaner` | Clean AI-generated code artifacts |\n| `bigquery-cost-audit` | GCP BigQuery cost analysis |\n| `data-quality` | Data validation and quality checks |\n| `dbt-incremental-strategy-audit` | dbt incremental model review |\n| `dbt-preflight` | dbt project pre-flight checks |\n| `dbt-strategy` | dbt modeling strategy |\n| `metric-impact-analyzer` | Business metric impact assessment |\n| `requesting-code-review` | Code review request workflow |\n| `receiving-code-review` | Code review response workflow |\n| `pr-triage` | Pull request triage process |\n| `repo-map` | Repository structure analysis |\n| `bug-hunt` | Systematic bug investigation |\n| `safe-refactor` | Safe code refactoring procedures |\n| `sql-business-logic-review` | SQL logic validation |\n| `defuddle` | Content extraction from documents |\n| `markitdown-file-intake` | Document ingestion pipeline |\n| `graphify` | Codebase visualization |\n| `ask-claude` | Claude advisory workflow |\n| `ask-gemini` | Gemini advisory workflow |\n| `ask-codex` | Codex advisory workflow |\n| `using-powerups` | Onboarding skill for Agent Powerups |\n\n资料来源：[README.md:89-111](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n### Plugin Bundles\n\nPlugin 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.\n\n| Status | Count | Example Bundles |\n|--------|-------|-----------------|\n| Stable | 3 | `dev-vitals`, `debugging-diagnostics`, `quality-gates` |\n| 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` |\n| Experimental | 4 | `software-engineering`, `agentic-systems`, `security-guardrails`, `agent-evaluation-lab` |\n\n```mermaid\ngraph TD\n A[Plugin Bundle] --> B[skills/]\n A --> C[commands/]\n A --> D[agents/]\n A --> E[.claude-plugin/]\n A --> F[.codex-plugin/]\n B --> G[SKILL.md files]\n C --> H[command-name.md files]\n D --> I[agent-name.md files]\n E --> J[plugin.json - Claude Code Manifest]\n F --> K[plugin.json - Codex Manifest]\n```\n\n### User-Intent Profiles\n\nProfiles are curated collections of skills and plugins for specific use cases. They can be inspected with `apx profiles list` and applied during setup.\n\n资料来源：[README.md:120-130](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## Setup Modes\n\nAgent Powerups supports three installation modes that control the scope of what gets installed:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `minimal` | Bootstrap setup with essential instructions only | Quick evaluation |\n| `recommended` | Core skills, plugins, and instructions | Standard onboarding |\n| `full` | All assets plus support documentation | Comprehensive deployment |\n\nThe setup process:\n\n1. Creates an `agent-powerups/` directory under the agent root\n2. Copies relevant asset directories based on mode\n3. Optionally appends agent-powerups instructions to `AGENTS.md` or `CLAUDE.md`\n4. Backs up existing instruction files before modification\n\n资料来源：[src/cli/commands/setup.ts:14-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n\n```mermaid\nflowchart LR\n A[apx setup codex] --> B{Mode?}\n B -->|minimal| C[Bootstrap instructions only]\n B -->|recommended| D[Skills + plugins + instructions]\n B -->|full| E[All assets + docs]\n C --> F[agent-powerups/]\n D --> F\n E --> F\n F --> G{AGENTS.md exists?}\n G -->|Yes| H[Append marked block
Backup first]\n G -->|No| I[Create instructions file]\n H --> J[Setup complete]\n I --> J\n```\n\n## Supported Agents\n\nAgent Powerups maintains explicit compatibility with three primary agent platforms:\n\n| Agent | Install Command | Asset Target |\n|-------|-----------------|--------------|\n| OpenAI Codex | `apx install codex` | `/skills/`, `/plugins/` |\n| Anthropic Claude Code | `apx install claude` | `/skills/`, `/plugins/` |\n| Google Gemini CLI | `apx install gemini` | `/skills/`, `/extensions/` |\n\nThe CLI uses `--target` flag to specify the destination:\n\n```sh\napx plugins install dev-vitals --target codex --dry-run\napx plugins install dev-vitals --target claude-code --dry-run\n```\n\n资料来源：[src/cli/apx.ts:32-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n## MCP Integration\n\nAgent Powerups ships with a local-first GitHub MCP configuration that includes:\n\n- `apx mcp check` - Validate MCP server configuration\n- `apx mcp smoke` - Run smoke tests against MCP server\n- `apx mcp install` - Explicit installation workflow\n\nThe MCP integration follows a security-first model where MCP servers require explicit user approval before enablement.\n\n资料来源：[README.md:51-54](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## Safety Model\n\nAgent Powerups implements several safety mechanisms:\n\n1. **Dry-run by default**: Most install commands support `--dry-run` to preview changes\n2. **Explicit approval**: Interactive prompts require confirmation unless `--yes` is passed\n3. **Backup before modify**: Setup creates backups of existing instruction files\n4. **Requirement validation**: `apx check` verifies prerequisites before installation\n5. **Security audit**: `apx security-audit` scans for dangerous patterns in scripts\n\nDangerous patterns flagged by the security audit:\n\n| Pattern | Severity | Description |\n|---------|----------|-------------|\n| `unpinned-latest-image` | P2 | Unpinned `:latest` container images in CI |\n| `broad-filesystem-write` | P1 | Broad filesystem write or `rm -rf /` patterns |\n| `missing-dry-run` | P1 | Install commands without `--dry-run` guard |\n\n资料来源：[src/cli/commands/security-audit.ts:18-28](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n\n## Validation and Health Checks\n\n### Doctor Command\n\nThe `apx doctor` command performs comprehensive health checks:\n\n| Check | What It Validates |\n|-------|-------------------|\n| Skill files | All skills have `SKILL.md`, valid frontmatter, and referenced support files exist |\n| External scripts | Registered external scripts can be executed |\n| File permissions | Asset directories are readable |\n| Node.js version | Runtime version compatibility |\n\n资料来源：[src/cli/commands/doctor.ts:35-52](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n### Requirement Checking\n\nThe `apx check` command validates asset requirements:\n\n- Missing requirements are flagged with `MISSING` status\n- Automatic installation is attempted if `--install-missing` is provided\n- Human approval is requested via interactive prompt unless `--yes` is passed\n\n```mermaid\nflowchart TD\n A[apx check ] --> B[Check requirements]\n B --> C{All satisfied?}\n C -->|Yes| D[status=OK]\n C -->|No| E{installMissing?}\n E -->|Yes| F[installMissingRequirements]\n E -->|No| G[status=MISSING]\n F --> H{Interactive?}\n H -->|Yes| I[confirmInstall prompt]\n H -->|No --yes| J[Auto-install]\n I -->|Approved| F\n I -->|Declined| K[warnings.push]\n```\n\n资料来源：[src/cli/commands/check.ts:28-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n\n## Directory Structure\n\n```\nagent-powerups/\n├── skills/ # Root-level reusable skills\n├── agents-md/ # AGENTS.md templates\n├── commands/ # Command packs\n│ └── generic/ # Agent-agnostic commands\n├── hooks/ # Hook examples\n├── workflows/ # Workflow templates\n├── mcp/ # MCP configurations\n│ └── generic/ # Agent-agnostic MCP configs\n├── plugins/ # Plugin bundle source\n├── docs/ # Documentation\n├── scripts/ # Validation scripts\n├── .codex-plugin/ # Codex plugin manifest\n├── .claude-plugin/ # Claude Code plugin manifest\n├── apx.ts # CLI entry point\n├── package.json # Package manifest\n├── catalog.json # Asset catalog index\n├── plugin-bundles.json # Plugin bundle index\n└── profiles.json # User-intent profiles\n```\n\n## Version and Release\n\n| Property | Value |\n|----------|-------|\n| Package name | `agent-powerups` |\n| Current version | `0.3.0` |\n| License | Apache-2.0 |\n| Node.js requirement | >= 20 |\n| Repository | `git+https://github.com/yeaight7/agent-powerups.git` |\n\n资料来源：[package.json:1-15](https://github.com/yeaight7/agent-powerups/blob/main/package.json)\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Project Overview](#overview), [apx CLI Reference](#cli-reference), [Claude Code Integration](#claude-code-integration), [Codex Integration](#codex-integration), [Gemini Integration](#gemini-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/install.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/install.ts)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)\n- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)\n- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n \n\n# Installation Guide\n\nAgent 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.\n\n## Overview\n\nAgent Powerups is an Oh My Zsh-style collection of reusable skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for coding agents. The installation system is designed with safety boundaries around external tools, secrets, shell profiles, and MCP enablement. 资料来源：[README.md]()\n\n## Installation Methods\n\nThe system supports four primary installation approaches:\n\n| Method | Command | Use Case |\n|--------|---------|----------|\n| **CLI Manual Install** | `apx install ` | Direct native install for humans |\n| **Agent-Curated Setup** | `apx setup --mode recommended --yes` | Bootstrap an agent with curated assets |\n| **Agent-Managed Setup** | Give agent repo access + run `apx setup` | Let the agent inspect and propose setup |\n| **Minimal Demo** | `apx setup --agent-root --dry-run` | Review assets without mutation |\n\n资料来源：[README.md:1-80]()\n\n## Prerequisites\n\n### System Requirements\n\n- **Node.js**: Required for the `apx` CLI tool\n- **npm** or **yarn**: For installing the CLI package\n- **Python 3.x**: For validation scripts (`validate-skills.py`, `validate-catalog.py`, `check-requirements.py`)\n- **Git**: For cloning the repository (optional, if using npm package)\n\n### Verification Commands\n\nBefore installation, verify your environment:\n\n```sh\napx doctor\napx list\n```\n\nThe `doctor` command checks the CLI installation and dependencies. The `list` command displays all available assets. 资料来源：[examples/minimal/README.md]()\n\n## CLI Installation\n\n### Installing the Package\n\nInstall the `agent-powerups` package globally:\n\n```sh\nnpm install -g agent-powerups\n```\n\nOr use the development version from the repository:\n\n```sh\ngit clone https://github.com/yeaight7/agent-powerups.git\ncd agent-powerups\nnpm install\nnpm run build\nnpm link\n```\n\n资料来源：[examples/minimal/README.md]()\n\n### Global Commands Available\n\nAfter installation, the `apx` command provides access to all functionality:\n\n| Command | Description |\n|---------|-------------|\n| `apx doctor` | Verify CLI installation and dependencies |\n| `apx list` | List all available skills, commands, hooks, and workflows |\n| `apx info ` | Show detailed information about a specific asset |\n| `apx check ` | Validate asset requirements |\n| `apx profiles list` | List user-intent profiles for curated skill/plugin sets |\n\n资料来源：[src/cli/apx.ts:1-100]()\n\n## Native Install (Manual)\n\nThe `apx install` command performs a direct native installation, copying skills and plugin bundles into the selected agent root directory.\n\n### Basic Syntax\n\n```sh\napx install [--verbose]\napx install --full [--verbose]\n```\n\n### Default Install Behavior\n\n| Asset Type | Destination |\n|------------|-------------|\n| Root `skills/` | `/skills/` |\n| Codex/Claude plugin bundles | `/plugins/` |\n| Gemini plugin bundles | `/extensions/` |\n\nHuman output shows counts by default. Use `--verbose` for per-file paths.\n\n### Full Install\n\nThe `--full` flag additionally:\n\n- Stages support assets under `agent-powerups/`\n- Updates existing global instructions with a backup\n\n```sh\napx install codex --full --verbose\n```\n\n### Dry Run\n\nAlways preview changes before applying:\n\n```sh\napx install codex --dry-run\napx install claude --dry-run\napx install gemini --dry-run\n```\n\n### Per-Asset Installation\n\nInstall specific plugin bundles to specific targets:\n\n```sh\napx install --target [--dry-run] [--dest ]\n```\n\nExample:\n\n```sh\napx install dev-vitals --target codex --dry-run\napx install dev-vitals --target codex\n```\n\n资料来源：[README.md:1-150](), [src/cli/apx.ts:100-200]()\n\n## Agent-Curated Setup\n\nThe `apx setup` command provides an agent-curated setup path with different configuration modes.\n\n### Setup Syntax\n\n```sh\napx setup [--mode minimal|recommended|full] [--dry-run|--yes] [--agent-root ] [--instructions-file ] [--json]\n```\n\n### Setup Modes\n\n#### Minimal Mode (Bootstrap)\n\nMinimal mode creates a bootstrap setup with essential references:\n\n```sh\napx setup codex --mode minimal --yes\n```\n\nOutput structure:\n\n```\nSTART_MARKER\n## Agent Powerups\nAgent Powerups assets are installed at ``.\n- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.\n- Use `apx` commands to discover, inspect, validate, and extend setup.\n- MCP servers require explicit user approval.\n- External tools require user approval before install.\nThis is a minimal (bootstrap) setup. To get a recommended agent environment:\n apx setup ${profile.agent} --mode recommended --yes\nEND_MARKER\n```\n\n资料来源：[src/cli/commands/setup.ts:1-50]()\n\n#### Recommended Mode\n\nRecommended mode provides the main agent environment with skills, plugin bundles, and comprehensive instructions:\n\n```sh\napx setup codex --mode recommended --yes\napx setup claude-code --mode recommended --yes\napx setup gemini --mode recommended --yes\n```\n\nThis mode includes:\n\n- All root skills from `skills/`\n- Recommended plugin bundles based on agent profile\n- Command templates and hook examples\n- AGENTS.md templates\n- MCP configuration guidance\n\n#### Full Mode\n\nFull mode performs a broad staging with maximum asset coverage:\n\n```sh\napx setup codex --mode full --yes\n```\n\n## Installation Workflow Diagram\n\n```mermaid\ngraph TD\n A[Start: apx install or apx setup] --> B{Dry Run?}\n B -->|Yes| C[Preview Changes Only]\n B -->|No| D{Interactive?}\n D -->|Yes| E[Confirm Changes]\n D -->|No --yes| F[Auto-Approve]\n C --> G[Display File Operations]\n E -->|Approved| H[Execute Installation]\n E -->|Declined| I[Abort]\n F --> H\n H --> J[Copy Skills to Agent Root]\n H --> K[Copy Plugins to Agent Root]\n H --> L[Update Instructions if --full]\n J --> M[Verify with apx check]\n K --> M\n L --> M\n M --> N[Installation Complete]\n```\n\n## Per-Agent Setup Guides\n\n### Codex Setup\n\n```sh\n# Dry run first\napx setup codex --dry-run\n\n# Safe apply with explicit root\napx setup codex --agent-root .agent-powerups-demo\\codex --yes\n\n# Inspect after setup\napx info using-powerups\napx check using-powerups\n```\n\n**Instruction File Behavior:**\n- If `\\AGENTS.md` exists, setup appends a marked `agent-powerups` block after creating a backup\n- If it does not exist, setup writes `agent-powerups\\instructions\\agent-powerups.md` and reports manual steps\n\n资料来源：[examples/codex/README.md]()\n\n### Claude Code Setup\n\n```sh\n# Dry run first\napx setup claude-code --dry-run\n\n# Safe apply with explicit root\napx setup claude-code --agent-root .agent-powerups-demo\\claude --yes\n\n# Inspect after setup\napx commands print ship-check --target claude-code\napx info using-powerups\n```\n\n**Instruction File Behavior:**\n- If `\\CLAUDE.md` exists, setup appends a marked `agent-powerups` block after creating a backup\n- If it does not exist, setup writes `agent-powerups\\instructions\\agent-powerups.md` and reports manual steps\n\n资料来源：[examples/claude-code/README.md]()\n\n### Gemini Setup\n\n```sh\napx setup gemini --dry-run\napx setup gemini --mode recommended --yes\n```\n\nGemini plugin bundles include `gemini-extension.json` and `GEMINI.md`.\n\n## Agent-Managed Setup\n\nFor agent-curated installation, provide the agent access to this repository and ask it to run:\n\n```sh\napx list\napx profiles list\napx setup --mode recommended --yes\n```\n\nThe agent will:\n1. Inspect available skills and plugins\n2. Propose a configuration plan\n3. Apply the setup based on the selected mode\n\n## Plugin Bundle Installation\n\n### Discovering Plugins\n\n```sh\napx plugins list\napx plugins info dev-vitals\n```\n\n### Validating Plugin Bundles\n\nBefore installation, validate bundle structure:\n\n```sh\napx plugins validate --all\n```\n\n### Installing Plugin Bundles\n\n```sh\napx plugins install dev-vitals --target codex --dry-run\napx plugins install dev-vitals --target codex\n```\n\n### Plugin Bundle Structure\n\nEach plugin follows the standard agent plugin layout:\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code Manifest\n├── .codex-plugin/\n│ └── plugin.json # Codex Manifest\n├── skills/\n│ └── /\n│ └── SKILL.md\n├── agents/\n│ └── .md\n└── commands/\n └── .md\n```\n\n资料来源：[plugins/README.md]()\n\n## MCP Configuration Installation\n\n### Available MCP Commands\n\n| Command | Purpose |\n|---------|---------|\n| `apx mcp list` | List available MCP configurations |\n| `apx mcp print ` | Display MCP configuration |\n| `apx mcp check ` | Validate MCP configuration |\n| `apx mcp smoke ` | Run smoke tests |\n| `apx mcp install ` | Install MCP configuration |\n\n### Installing GitHub MCP\n\n```sh\napx mcp check github-local --target generic\napx mcp smoke github-local --json\napx mcp install github-local --target codex --dry-run\napx mcp install github-local --target codex\n```\n\n## Post-Installation Validation\n\n### Run Validation Scripts\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\npython scripts/check-requirements.py\n```\n\n### Verify Setup\n\n```sh\napx doctor\napx check using-powerups\napx hooks run no-secrets-preflight --all\n```\n\n## Minimal Demo Walkthrough\n\nFor inspecting Agent Powerups without mutating an agent's global config:\n\n```sh\n# 1. Install and link the CLI\nnpm install\nnpm run build\nnpm link\n\n# 2. Verify installation\napx doctor\napx list\n\n# 3. Dry run setup to disposable directory\napx setup codex --agent-root .agent-powerups-demo\\codex --dry-run\n\n# 4. Apply to disposable local root\napx setup codex --agent-root .agent-powerups-demo\\codex --yes\n\n# 5. Review created structure\n.agent-powerups-demo/codex/agent-powerups/skills/\n.agent-powerups-demo/codex/agent-powerups/commands/\n.agent-powerups-demo/codex/agent-powerups/instructions/agent-powerups.md\n\n# 6. Rollback when done\nRemove-Item .agent-powerups-demo -Recurse -Force\n```\n\n资料来源：[examples/minimal/README.md]()\n\n## Safety Considerations\n\nThe installation system implements safety boundaries around:\n\n| Area | Safety Measure |\n|------|----------------|\n| External Tools | Require user approval before install |\n| Secrets | Never paste into agent context unless strictly necessary |\n| Shell Profiles | No automatic shell profile modifications |\n| MCP Servers | Require explicit user approval via `apx mcp check` and `apx mcp smoke` |\n| Hooks | Execute only when supported by host agent |\n\n**Before loading any asset**, review it:\n\n- Skills can instruct an agent to read local files or run commands\n- Hooks can execute code when supported by the host agent\n- MCP configs can expand tool access\n- Install commands can modify the local environment\n\nSee [SECURITY.md](./SECURITY.md) and [docs/security-model.md](./docs/security-model.md) for full security details.\n\n## Command Reference\n\n### Install Command Options\n\n| Option | Description |\n|--------|-------------|\n| `--dry-run` | Preview changes without applying |\n| `--full` | Stage support assets and update global instructions |\n| `--verbose` | Show per-file paths during installation |\n| `--agent-root ` | Specify custom agent root directory |\n| `--instructions-file ` | Specify custom instructions file path |\n| `--force` | Overwrite existing files |\n| `--json` | Output results in JSON format |\n\n### Setup Command Options\n\n| Option | Description |\n|--------|-------------|\n| `--mode minimal\\|recommended\\|full` | Select setup configuration mode |\n| `--dry-run` | Preview changes without applying (default) |\n| `--yes` | Auto-approve and apply changes |\n| `--agent-root ` | Specify custom agent root directory |\n| `--instructions-file ` | Specify custom instructions file path |\n| `--json` | Output results in JSON format |\n\n## Troubleshooting\n\n### CLI Not Found\n\n```sh\nnpm link\n# Or reinstall globally\nnpm install -g agent-powerups\n```\n\n### Dry Run vs Apply\n\nAlways prefer dry-run first:\n\n```sh\napx install codex --dry-run\napx setup codex --dry-run\napx plugins install dev-vitals --target codex --dry-run\n```\n\n### Rollback\n\nIf using explicit `--agent-root` with a disposable directory, simply delete the directory:\n\n```sh\nRemove-Item .agent-powerups-demo -Recurse -Force\n```\n\n### Agent Instructions Not Updated\n\nCheck if the agent's instruction file exists:\n\n- Codex: `\\AGENTS.md`\n- Claude Code: `\\CLAUDE.md`\n\nIf the file doesn't exist, setup writes to `agent-powerups\\instructions\\agent-powerups.md` and reports manual integration steps.\n\n---\n\n\n\n## apx CLI Reference\n\n### 相关页面\n\n相关主题：[Project Overview](#overview), [Installation Guide](#installation), [Plugin Bundles](#plugin-bundles)\n\n\nRelevant Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [src/cli/commands/list.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/list.ts)\n- [src/cli/commands/plugins.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/plugins.ts)\n- [src/cli/commands/profiles.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/profiles.ts)\n- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)\n- [src/cli/commands/validate.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/validate.ts)\n \n\n# apx CLI Reference\n\nThe `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.\n\n## Overview\n\nThe `apx` CLI serves as a safe local CLI with runnable local checks, enabling users to:\n\n- Discover and install reusable skills and plugin bundles\n- Configure agent-specific instruction files\n- Validate tool requirements and dependencies\n- Manage MCP (Model Context Protocol) server configurations\n- Execute security audits and preflight checks\n- Handle persistent relay sessions for multi-agent workflows\n\n资料来源：[src/cli/apx.ts:1-50]()\n\n## Command Hierarchy\n\nThe `apx` CLI organizes commands into a hierarchical structure with multiple subcommand categories.\n\n```mermaid\ngraph TD\n A[apx] --> B[Install Commands]\n A --> C[Setup Commands]\n A --> D[Information Commands]\n A --> E[MCP Commands]\n A --> F[Plugin Commands]\n A --> G[Profile Commands]\n A --> H[Validation Commands]\n A --> I[Security Commands]\n A --> J[Relay Commands]\n A --> K[Phase Commands]\n \n B --> B1[install]\n B --> B2[setup]\n \n C --> C1[setup codex]\n C --> C2[setup claude-code]\n C --> C3[setup gemini]\n \n D --> D1[list]\n D --> D2[info]\n D --> D3[doctor]\n D --> D4[check]\n \n E --> E1[mcp list]\n E --> E2[mcp print]\n E --> E3[mcp check]\n E --> E4[mcp smoke]\n E --> E5[mcp install]\n E --> E6[mcp write]\n \n F --> F1[plugins list]\n F --> F2[plugins info]\n F --> F3[plugins validate]\n F --> F4[plugins install]\n \n G --> G1[profiles list]\n G --> G2[profiles info]\n G --> G3[profiles plan]\n G --> G4[profiles install]\n```\n\n## Installation Commands\n\n### `apx install`\n\nInstalls assets, skills, or plugins to specified agent targets.\n\n```sh\napx install [--full] [--dry-run] [--agent-root ] [--instructions-file ] [--force] [--verbose] [--json]\napx install --target [--dry-run] [--dest ]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes (first form) | Target agent platform |\n| `` | string | Yes (second form) | Specific asset to install |\n| `--target` | string | Yes (second form) | Installation target |\n| `--full` | flag | No | Install with support assets |\n| `--dry-run` | flag | No | Preview without applying changes |\n| `--agent-root` | path | No | Custom agent root directory |\n| `--instructions-file` | path | No | Custom instructions file path |\n| `--force` | flag | No | Overwrite existing files |\n| `--verbose` | flag | No | Show per-file installation paths |\n| `--json` | flag | No | Output JSON format |\n\n**Default Installation Paths:**\n\n| Target | Root Location | Plugin Location |\n|--------|--------------|-----------------|\n| codex | `/` | `/plugins/` |\n| claude-code | `/` | `/plugins/` |\n| gemini | `/` | `/extensions/` |\n\n资料来源：[src/cli/apx.ts:80-100]()\n\n### Native Install Behavior\n\nThe default manual install copies:\n- Root `skills/` → `/skills/`\n- Codex/Claude plugin bundles → `/plugins/`\n- Gemini plugin bundles → `/extensions/`\n\nThe `--full` flag additionally:\n- Stages support assets under `agent-powerups/`\n- Updates existing global instructions with a backup\n\n## Setup Commands\n\n### `apx setup`\n\nConfigures agent environments with curated skill and plugin sets using agent-curated setup paths.\n\n```sh\napx setup [--mode minimal|recommended|full] [--dry-run|--yes] [--agent-root ] [--instructions-file ] [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Target agent platform |\n| `--mode` | string | No | Setup mode (default: dry-run) |\n| `--dry-run` | flag | No | Preview changes (default) |\n| `--yes` | flag | No | Apply changes without confirmation |\n| `--agent-root` | path | No | Custom agent root directory |\n| `--instructions-file` | path | No | Custom instructions file path |\n| `--json` | flag | No | Output JSON format |\n\n### Setup Modes\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `minimal` | Bootstrap only | Quick start, minimal footprint |\n| `recommended` | Main agent setup | Standard development environment |\n| `full` | Broad staging | Complete feature set |\n\n### Instruction File Behavior\n\n- If `/AGENTS.md` (Codex) or `/CLAUDE.md` (Claude Code) exists, setup appends a marked `agent-powerups` block after creating a backup.\n- If the file does not exist, setup writes `agent-powerups/instructions/agent-powerups.md` and reports manual steps.\n\n资料来源：[src/cli/commands/setup.ts:1-60]()\n\n## Information Commands\n\n### `apx doctor`\n\nRuns comprehensive diagnostics on the apx installation.\n\n```sh\napx doctor [--full] [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `--full` | flag | No | Run full diagnostic suite |\n| `--json` | flag | No | Output JSON format |\n\n### `apx list`\n\nLists all available assets, skills, and plugins in the catalog.\n\n```sh\napx list [--json]\n```\n\n### `apx info`\n\nDisplays detailed information about a specific asset.\n\n```sh\napx info [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Name of the asset to inspect |\n| `--json` | flag | No | Output JSON format |\n\n### `apx check`\n\nChecks dependency requirements for assets without installing.\n\n```sh\napx check [--install-missing] [--dry-run]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Asset to check dependencies for |\n| `--install-missing` | flag | No | Automatically install missing dependencies |\n| `--dry-run` | flag | No | Preview installation without applying |\n\n资料来源：[src/cli/commands/list.ts:1-50]()\n\n## MCP Commands\n\nThe MCP (Model Context Protocol) commands manage MCP server configurations for agent integrations.\n\n```mermaid\ngraph LR\n A[mcp list] --> B[Discover configs]\n C[mcp check] --> D[Validate syntax]\n E[mcp smoke] --> F[Test connectivity]\n G[mcp install] --> H[Deploy to target]\n```\n\n### `apx mcp list`\n\nLists all available MCP configurations.\n\n```sh\napx mcp list [--json]\n```\n\n### `apx mcp print`\n\nPrints MCP configuration content for review.\n\n```sh\napx mcp print --target [--json]\n```\n\n### `apx mcp check`\n\nValidates MCP configuration syntax and structure.\n\n```sh\napx mcp check --target [--json]\n```\n\n### `apx mcp smoke`\n\nTests MCP server connectivity and basic functionality.\n\n```sh\napx mcp smoke [--json]\n```\n\n### `apx mcp install`\n\nInstalls MCP configuration to the specified agent target.\n\n```sh\napx mcp install --target [--dry-run|--yes] [--agent-root ] [--dest ] [--force] [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | MCP configuration name |\n| `--target` | string | Yes | Installation target |\n| `--dry-run` | flag | No | Preview without applying |\n| `--yes` | flag | No | Apply without confirmation |\n| `--dest` | path | No | Custom destination path |\n| `--force` | flag | No | Overwrite existing |\n| `--json` | flag | No | JSON output |\n\n### `apx mcp write`\n\nWrites MCP configuration to a specified location.\n\n```sh\napx mcp write --target --dest [--force] [--json]\n```\n\n资料来源：[src/cli/commands/mcp.ts:1-100]()\n\n## Plugin Commands\n\nPlugin commands manage plugin bundles with validation, inspection, and installation capabilities.\n\n```mermaid\ngraph TD\n A[plugins list] --> B[Discover plugins]\n A --> C[plugins info]\n C --> D[plugins validate]\n D --> E{Valid?}\n E -->|Yes| F[plugins install]\n E -->|No| G[Fix errors]\n F --> H[Deploy to target]\n```\n\n### `apx plugins list`\n\nLists all available plugin bundles.\n\n```sh\napx plugins list [--json]\n```\n\n### `apx plugins info`\n\nDisplays detailed information about a specific plugin.\n\n```sh\napx plugins info [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Plugin bundle name |\n| `--json` | flag | No | JSON output format |\n\n### `apx plugins validate`\n\nValidates plugin bundle structure and metadata.\n\n```sh\napx plugins validate [--json]\napx plugins validate --all [--json]\n```\n\n### `apx plugins install`\n\nInstalls a plugin bundle to the specified target.\n\n```sh\napx plugins install --target [--dest ] [--dry-run|--yes] [--force] [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Plugin to install |\n| `--target` | string | Yes | Target agent platform |\n| `--dest` | path | No | Custom installation directory |\n| `--dry-run` | flag | No | Preview without applying |\n| `--yes` | flag | No | Apply without confirmation |\n| `--force` | flag | No | Overwrite existing |\n| `--json` | flag | No | JSON output |\n\n资料来源：[src/cli/commands/plugins.ts:1-100]()\n\n## Profile Commands\n\nProfiles are curated skill and plugin sets designed for specific use cases or security requirements.\n\n### `apx profiles list`\n\nLists all available user-intent profiles.\n\n```sh\napx profiles list [--json]\n```\n\n### `apx profiles info`\n\nDisplays detailed information about a specific profile.\n\n```sh\napx profiles info [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Profile name to inspect |\n| `--json` | flag | No | JSON output format |\n\n### `apx profiles plan`\n\nGenerates an installation plan for a profile targeting a specific agent.\n\n```sh\napx profiles plan --target [--json]\n```\n\n### `apx profiles install`\n\nInstalls a complete profile to the specified target.\n\n```sh\napx profiles install --target [--dry-run|--yes] [--dest ] [--force] [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `` | string | Yes | Profile to install |\n| `--target` | string | Yes | Target agent platform |\n| `--dry-run` | flag | No | Preview without applying |\n| `--yes` | flag | No | Apply without confirmation |\n| `--dest` | path | No | Custom destination |\n| `--force` | flag | No | Overwrite existing |\n| `--json` | flag | No | JSON output |\n\n资料来源：[src/cli/commands/profiles.ts:1-80]()\n\n## Validation Commands\n\n### `apx validate`\n\nValidates skills, catalog entries, and requirements.\n\n```sh\napx validate [--json]\napx validate skill [--json]\napx validate catalog [--json]\n```\n\n### `apx ship-check`\n\nRuns pre-deployment checks to validate project readiness.\n\n```sh\napx ship-check [--full] [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `--full` | flag | No | Run comprehensive checks |\n| `--json` | flag | No | JSON output format |\n\n### `apx no-secrets-preflight`\n\nDetects potential secret leaks in files before commit.\n\n```sh\napx no-secrets-preflight [--path | --all] [--json]\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `--path` | path | No | Specific file or directory to scan |\n| `--all` | flag | No | Scan entire repository |\n| `--json` | flag | No | JSON output format |\n\n资料来源：[src/cli/commands/validate.ts:1-60]()\n\n## Security Commands\n\n### `apx security-audit`\n\nPerforms security analysis on project files.\n\n```sh\napx security-audit --path [--json]\napx security-audit --all [--json]\n```\n\n### Security Checks\n\n| Check Name | Severity | Pattern | Description |\n|------------|----------|---------|-------------|\n| `unpinned-image` | P2 | `image:\\s+[a-z0-9_/.-]+:latest` | Unpinned `:latest` image in CI |\n| `broad-filesystem-write` | P1 | `rm\\s+-rf\\s+\\/|write_file\\s+/\\*\\*` | Dangerous filesystem operations |\n| `missing-dry-run` | P1 | `npm\\s+install\\|pip\\s+install` without `--dry-run` | Install without dry-run guard |\n\n资料来源：[src/cli/commands/security-audit.ts:1-50]()\n\n## Relay Commands\n\nPersistent relay sessions maintain context across multiple turns for multi-agent delegation.\n\n### `apx relay init`\n\nInitializes a new persistent relay session.\n\n```sh\napx relay init \n```\n\n### `apx relay start`\n\nStarts a relay session with a specified provider.\n\n```sh\napx relay start --provider [--json]\n```\n\n### `apx relay ask`\n\nSends a query to an active relay session.\n\n```sh\napx relay ask \"\" [--json]\n```\n\n### `apx relay status`\n\nChecks the status of a relay session.\n\n```sh\napx relay status \n```\n\n### `apx relay stop`\n\nStops an active relay session.\n\n```sh\napx relay stop \n```\n\n## Agent Advisor Commands\n\n### `apx ask-codex`\n\nQueries Codex for advice or analysis.\n\n```sh\napx ask-codex \"\" [--json]\n```\n\n### `apx ask-claude`\n\nQueries Claude for advice or analysis.\n\n```sh\napx ask-claude \"\" [--json]\n```\n\n### `apx ask-gemini`\n\nQueries Gemini for advice or analysis.\n\n```sh\napx ask-gemini \"\" [--json]\n```\n\n## Agent Targets\n\nAll installation and setup commands support the following target agents:\n\n| Target | Description |\n|--------|-------------|\n| `codex` | OpenAI Codex / VS Code AI |\n| `claude` | Anthropic Claude |\n| `claude-code` | Claude Code CLI |\n| `gemini` | Google Gemini |\n| `generic` | Generic/unspecified agent |\n\n## Global Flags\n\n| Flag | Description |\n|------|-------------|\n| `--dry-run` | Preview changes without applying (default for most commands) |\n| `--yes` | Apply changes without confirmation prompt |\n| `--json` | Output results in JSON format |\n| `--verbose` | Show detailed per-file information |\n| `--force` | Overwrite existing files without prompting |\n\n## Exit Codes\n\n| Code | Description |\n|------|-------------|\n| `0` | Success |\n| `1` | Failure (missing dependencies, validation errors, etc.) |\n\n## Configuration Files\n\nThe CLI reads configuration from the following locations:\n\n- Package-level `package.json` for version detection\n- Agent-specific root directories for target configuration\n- `skills/`, `plugins/`, `mcp/`, `commands/`, `hooks/`, `workflows/` directories for asset discovery\n\n资料来源：[src/cli/apx.ts:200-280]()\n\n## Quick Reference\n\n```sh\n# Setup and installation\napx install codex --dry-run\napx install codex --yes\napx setup codex --mode recommended --yes\n\n# Discovery and inspection\napx doctor\napx list\napx info markitdown-file-intake\napx check markitdown-file-intake\n\n# Plugin management\napx plugins list\napx plugins info dev-vitals\napx plugins validate --all\napx plugins install dev-vitals --target codex --dry-run\n\n# MCP management\napx mcp list\napx mcp check github-local --target codex\napx mcp smoke github-local --json\napx mcp install github-local --target codex --dry-run\n\n# Profile management\napx profiles list\napx profiles info safe-core\napx profiles plan safe-core --target codex\n\n# Security and validation\napx ship-check --full\napx no-secrets-preflight --all\napx security-audit --path .\n\n---\n\n\n\n## Skills System\n\n### 相关页面\n\n相关主题：[Project Overview](#overview), [Plugin Bundles](#plugin-bundles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [skills/systematic-debugging/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/systematic-debugging/SKILL.md)\n- [skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)\n- [skills/safe-refactor/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/safe-refactor/SKILL.md)\n- [skills/bug-hunt/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/bug-hunt/SKILL.md)\n- [docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)\n \n\n# Skills System\n\n## Overview\n\nThe 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.\n\nSkills 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.\n\n资料来源：[README.md:22-24](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## Core Architecture\n\n### Skill Structure\n\nEach skill follows a standardized file structure:\n\n```\nskills/\n└── /\n ├── SKILL.md # Main skill definition\n └── support-files/ # Optional referenced assets\n```\n\nThe primary `SKILL.md` file contains:\n\n- **Frontmatter metadata** (YAML): name, description, version, tags, compatibility\n- **Core workflow content**: Structured instructions for the agent\n- **Support file references**: Paths to optional helper resources\n\n资料来源：[docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)\n\n### Skill Lifecycle\n\n```mermaid\ngraph TD\n A[Create SKILL.md] --> B[Validate Frontmatter]\n B --> C[Check Required Fields]\n C --> D{Valid?}\n D -->|Yes| E[Publish to Catalog]\n D -->|No| F[Fix Issues]\n F --> B\n E --> G[apx list / apx info]\n G --> H[Agent Invocation]\n H --> I[Execute Workflow]\n I --> J[Report Results]\n```\n\n## Skill Categories\n\nThe repository ships 21 core skills organized into functional categories:\n\n| Category | Skills | Purpose |\n|----------|--------|---------|\n| **Development Workflow** | `systematic-debugging`, `bug-hunt`, `safe-refactor`, `writing-plans` | Structured approaches to common coding tasks |\n| **Code Quality** | `no-fluff`, `requesting-code-review`, `receiving-code-review` | Review and quality assurance processes |\n| **Data Engineering** | `bigquery-cost-audit`, `data-quality`, `dbt-preflight`, `dbt-strategy`, `dbt-incremental-strategy-audit` | Data pipeline and warehouse management |\n| **Business Logic** | `sql-business-logic-review`, `metric-impact-analyzer` | Analysis and validation workflows |\n| **Utility** | `ai-slop-cleaner`, `defuddle`, `markitdown-file-intake`, `graphify` | Content processing and transformation |\n| **Agent Integration** | `ask-claude`, `ask-gemini`, `ask-codex`, `using-powerups` | Cross-agent communication and onboarding |\n\n资料来源：[README.md:103-130](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## Skill Frontmatter Schema\n\nEvery skill must include valid YAML frontmatter in its `SKILL.md` file:\n\n```yaml\n---\nname: # Required: unique lowercase identifier\ndescription: # Required: brief explanation\nversion: # Optional: default \"1.0.0\"\ntags: # Optional: categorization\n - \n - \nrequires: # Optional: dependencies\n - \ncompatibility: # Optional: target agent hints\n - codex\n - claude-code\n - gemini\n---\n```\n\n### Required Fields\n\n| Field | Type | Description | Validation |\n|-------|------|-------------|------------|\n| `name` | string | Unique skill identifier | Must exist in frontmatter |\n| `description` | string | Brief description of skill purpose | Must exist in frontmatter |\n\n资料来源：[src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts) (lines checking for frontmatter)\n\n## Skill Validation System\n\nThe system includes automated validation to ensure skill quality and consistency.\n\n### Validation Checks\n\nThe `apx doctor` command performs the following validation:\n\n1. **Frontmatter validation**: Ensures `name` and `description` exist\n2. **Content length validation**: Skills must meet minimum character threshold\n3. **Support file verification**: References to support files must exist\n4. **Catalog alignment**: Skills must appear in the central catalog\n\n### Validation Script\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\n```\n\n### Doctor Check Results\n\n| Check | Pass Condition | Failure Message |\n|-------|----------------|-----------------|\n| `skill-frontmatter` | All skills have `name` + `description` | X skill(s) missing name/description |\n| `skill-content-length` | All skills ≥ minimum chars | X skill(s) under minimum length |\n\n资料来源：[src/cli/commands/audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n\n## Featured Skills\n\n### systematic-debugging\n\nA structured approach to diagnosing and resolving software defects.\n\n**Workflow Steps:**\n\n1. Gather error context and reproduction steps\n2. Isolate the failing component\n3. Form and test hypotheses\n4. Implement and verify fix\n5. Document root cause\n\n资料来源：[skills/systematic-debugging/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/systematic-debugging/SKILL.md)\n\n### writing-plans\n\nSystematic approach to creating actionable project plans from requirements.\n\n**Workflow Steps:**\n\n1. Parse and clarify requirements\n2. Identify dependencies and constraints\n3. Break down into actionable tasks\n4. Estimate effort and timeline\n5. Present structured plan for review\n\n资料来源：[skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)\n\n### safe-refactor\n\nGuided refactoring workflow with safety checks and rollback considerations.\n\n**Workflow Steps:**\n\n1. Identify refactoring scope and goals\n2. Establish baseline with tests\n3. Execute incremental changes\n4. Verify behavior preservation\n5. Clean up and document changes\n\n资料来源：[skills/safe-refactor/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/safe-refactor/SKILL.md)\n\n### bug-hunt\n\nExploratory investigation skill for tracking down elusive bugs.\n\n**Workflow Steps:**\n\n1. Collect available evidence\n2. Define search boundaries\n3. Instrument for additional data\n4. Narrow down through elimination\n5. Confirm and document findings\n\n资料来源：[skills/bug-hunt/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/bug-hunt/SKILL.md)\n\n## CLI Integration\n\n### Discovery Commands\n\n| Command | Description |\n|---------|-------------|\n| `apx list` | List all available skills in the catalog |\n| `apx info ` | Display detailed information about a specific skill |\n| `apx check ` | Validate a skill's structure and frontmatter |\n\n### Installation and Setup\n\n```sh\n# Native install to agent root\napx install \n\n# Dry-run to preview changes\napx install codex --dry-run\n\n# Full install with support assets\napx install codex --full --verbose\n```\n\nDuring installation, skills from `skills/` are copied to `/skills/` (or `/agent-powerups/skills/` for full installs).\n\n资料来源：[README.md:142-160](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## Skills vs Plugin Bundles\n\nIt's important to distinguish between **root skills** and **plugin skills**:\n\n| Aspect | Root Skills | Plugin Skills |\n|--------|-------------|---------------|\n| **Location** | `skills/` | `plugins//skills/` |\n| **Scope** | General-purpose, standalone | Domain-specific, deeper coverage |\n| **Dependencies** | Self-contained | May reference plugin-specific assets |\n| **Override behavior** | Cannot be overridden by plugins | Must not replace or override root skills |\n\n> 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.\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## Catalog Schema\n\nSkills are registered in the central catalog with metadata for discovery and filtering:\n\n```json\n{\n \"skills\": [\n {\n \"name\": \"skill-name\",\n \"description\": \"Brief description\",\n \"path\": \"skills/skill-name\",\n \"tags\": [\"debugging\", \"workflow\"],\n \"compatibility\": [\"codex\", \"claude-code\"]\n }\n ]\n}\n```\n\n资料来源：[docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)\n\n## Quality Gates for Skills\n\nThe audit system validates skills through multiple checks:\n\n```mermaid\ngraph LR\n A[apx audit skills] --> B[Check Frontmatter]\n A --> C[Check Content Length]\n A --> D[Check Support Files]\n B --> E{Summary}\n C --> E\n D --> E\n E --> F[Pass/Warn/Fail]\n```\n\nOutput format:\n\n```\naudit skills: X pass, Y warn, Z fail\n```\n\n资料来源：[src/cli/commands/audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n\n## Security Considerations\n\nSkills are designed with safety boundaries:\n\n- **Read-only by default**: Skills provide guidance, not direct system access\n- **User approval required**: External tools or destructive operations require explicit confirmation\n- **Dry-run support**: All install and execution commands support dry-run mode\n- **Scope validation**: Skills validate inputs before execution\n\n## Best Practices\n\n### Writing a New Skill\n\n1. Create `skills//SKILL.md`\n2. Add required frontmatter (`name`, `description`)\n3. Write clear, actionable workflow steps\n4. Include success criteria and failure modes\n5. Reference any support files explicitly\n6. Run `apx doctor` to validate\n7. Submit for catalog inclusion\n\n### Invoking Skills\n\nAgents can invoke skills through:\n\n1. **Direct reference**: Ask agent to \"use the systematic-debugging skill\"\n2. **Command dispatch**: `apx info ` then paste content\n3. **Auto-discovery**: Agent reads from installed `skills/` directory\n\n## See Also\n\n- [Plugin Bundles System](../plugins/) — Domain-specific skill collections\n- [AGENTS.md Templates](../agents-md/) — Agent instruction templates\n- [CLI Reference](../cli/) — Complete apx command documentation\n- [Catalog Schema](../docs/catalog-schema.md) — Skill metadata specification\n\n---\n\n\n\n## Plugin Bundles\n\n### 相关页面\n\n相关主题：[Skills System](#skills-system), [apx CLI Reference](#cli-reference)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)\n- [.claude-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.claude-plugin/marketplace.json)\n- [.codex-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.codex-plugin/marketplace.json)\n- [docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)\n- [src/cli/utils/plugins.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/plugins.ts)\n \n\n# Plugin Bundles\n\n## Overview\n\nPlugin 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.\n\nThe 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.\n\n资料来源：[README.md:1-10]()\n\n## Architecture\n\n### Bundle Structure\n\nEach 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.\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code/Claude manifest\n├── .codex-plugin/\n│ └── plugin.json # Codex manifest\n├── skills/\n│ └── /\n│ └── SKILL.md\n├── agents/\n│ └── .md\n├── commands/\n│ └── .md\n├── templates/ (optional)\n│ └── .md\n├── hooks/ (optional)\n│ └── .ts\n├── workflows/ (optional)\n│ └── .yml\n└── mcp/ (optional)\n └── .json\n```\n\n资料来源：[plugins/README.md:18-36]()\n\n### Manifest Files\n\nThe 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.\n\n**Claude Plugin Manifest** (`.claude-plugin/plugin.json`)\n\nDefines the plugin for Claude Code and Claude agent platforms, including skills, agents, commands, and hooks.\n\n**Codex Plugin Manifest** (`.codex-plugin/plugin.json`)\n\nProvides equivalent metadata for OpenAI Codex and related Codex-based agents.\n\nBoth manifests share a common schema but may contain platform-specific instructions or configurations.\n\n资料来源：[plugins/README.md:20-25]()\n\n## Bundle Inventory\n\n### Maturity Levels\n\nPlugin bundles are classified into three maturity levels indicating their stability and readiness for production use.\n\n| Maturity | Count | Description |\n|----------|-------|-------------|\n| **Stable** | 3 | Production-ready bundles with verified functionality |\n| **Beta** | 10 | Functional bundles under active development, may have minor issues |\n| **Experimental** | 4 | Early-stage bundles, API/behavior may change |\n\n资料来源：[README.md:95-105]()\n\n### Stable Bundles\n\nThese bundles have undergone extensive testing and are recommended for production use:\n\n| Bundle | Description |\n|--------|-------------|\n| `dev-vitals` | Development vitals and health metrics |\n| `debugging-diagnostics` | Systematic debugging workflows |\n| `quality-gates` | Code quality verification gates |\n\n### Beta Bundles\n\nActive development bundles with functional but evolving content:\n\n| Bundle | Description |\n|--------|-------------|\n| `codebase-maintenance` | Codebase maintenance utilities |\n| `data-engineering` | Data pipeline and engineering tools |\n| `documentation-systems` | Documentation generation and management |\n| `machine-learning-ops` | ML operations and monitoring |\n| `codebase-intelligence` | Code analysis and intelligence |\n| `spec-driven-development` | Specification-driven development |\n| `spec-quality-gates` | Adversarial plan verification and structured code review |\n| `context-efficiency` | Context-efficient dispatch routers for workflow, review, and codebase commands |\n| `tool-integrations` | External tool integration templates |\n| `memory-optimization` | Context and memory optimization strategies |\n\n资料来源：[README.md:95-105]()\n\n### Experimental Bundles\n\nEarly-stage bundles exploring new functionality:\n\n| Bundle | Description |\n|--------|-------------|\n| `software-engineering` | Advanced software engineering patterns |\n| `agentic-systems` | Agent orchestration and coordination |\n| `security-guardrails` | Security scanning and guardrails |\n| `agent-evaluation-lab` | Agent performance evaluation |\n\n## Bundle Schema\n\nThe `plugin-bundles.json` file serves as the central registry for all plugin bundles. Each bundle entry contains comprehensive metadata following a defined JSON schema.\n\n```json\n{\n \"name\": \"bundle-name\",\n \"description\": \"Human-readable bundle description\",\n \"maturity\": \"stable|beta|experimental\",\n \"version\": \"1.0.0\",\n \"skills\": [\n { \"name\": \"skill-name\", \"path\": \"skills/skill-name\" }\n ],\n \"agents\": [\n { \"name\": \"agent-name\", \"path\": \"agents/agent-name.md\" }\n ],\n \"commands\": [\n { \"name\": \"command-name\", \"path\": \"commands/command-name.md\" }\n ],\n \"templates\": [\n { \"name\": \"template-name\", \"path\": \"templates/template-name.md\" }\n ],\n \"hooks\": [\n { \"name\": \"hook-name\", \"path\": \"hooks/hook-name.ts\" }\n ],\n \"workflows\": [\n { \"name\": \"workflow-name\", \"path\": \"workflows/workflow-name.yml\" }\n ]\n}\n```\n\n资料来源：[docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)\n\n## CLI Commands for Plugin Management\n\nThe `apx` CLI provides comprehensive commands for discovering, inspecting, validating, and installing plugin bundles.\n\n### Discovery Commands\n\n```sh\napx plugins list # List all available bundles\napx plugins info # Inspect a specific bundle\napx plugins validate --all # Verify all bundle structures\n```\n\n### Installation Commands\n\n```sh\napx plugins install --target --dry-run\napx install # Full manual install\n```\n\n资料来源：[README.md:85-92]()\n\n### Validation Workflow\n\n```mermaid\ngraph TD\n A[apx plugins validate] --> B{Plugin exists?}\n B -->|No| C[Return error: plugin not found]\n B -->|Yes| D{Manifest files exist?}\n D -->|Missing| E[Return error: missing manifest]\n D -->|Present| F{Schema valid?}\n F -->|Invalid| G[Return validation errors]\n F -->|Valid| H[Return success]\n```\n\n资料来源：[src/cli/utils/plugins.ts:40-60]()\n\n## Marketplace Integration\n\n### Claude Code Marketplace\n\nPlugin 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.\n\n### Codex Marketplace\n\nSimilarly, `.codex-plugin/marketplace.json` provides marketplace configuration for Codex-based agents, ensuring discoverability across the agent platform ecosystem.\n\n资料来源：[.claude-plugin/marketplace.json](), [.codex-plugin/marketplace.json]()\n\n## Installation Process\n\n### Dry-Run Validation\n\nBefore installation, always perform a dry-run to preview changes:\n\n```sh\napx plugins install --target codex --dry-run\n```\n\nThis command displays the planned file operations without modifying the filesystem, allowing review of bundle contents before committing changes.\n\n资料来源：[README.md:85-88]()\n\n### Full Installation\n\nFor actual installation, the `apx setup` command stages Agent Powerups assets, including plugin bundles:\n\n```sh\napx setup codex --mode recommended --yes\napx setup claude-code --mode recommended --yes\n```\n\nThe installation process:\n\n1. Creates the plugin directory structure in the agent root\n2. Copies bundle files to the appropriate locations\n3. Registers skills, agents, and commands with the agent\n4. Updates configuration files with appropriate references\n\n资料来源：[src/cli/commands/setup.ts:1-50]()\n\n## Safety Considerations\n\nPlugin bundles may contain assets that modify agent behavior:\n\n- **Skills** can instruct agents to read files or execute commands\n- **Hooks** can execute code when supported by the host agent\n- **MCP configs** can expand tool access capabilities\n- **Install commands** can modify the local environment\n\nAlways review bundle contents before installation. The CLI provides validation commands to inspect bundle structure and content without installation.\n\n> ⚠️ **Warning**: Review assets before loading them into a trusted agent environment. Secrets should never be pasted into agent context unless strictly necessary.\n\n资料来源：[README.md:110-120]()\n\n## Plugin Bundle Development\n\n### Creating a New Bundle\n\n1. Create the bundle directory structure following the standard layout\n2. Add required manifest files (`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`)\n3. Include at least one skill, agent, or command\n4. Register the bundle in `plugin-bundles.json`\n5. Run `apx plugins validate` to verify structure\n\n### Bundle Validation\n\nThe validation system checks:\n\n- Presence of required manifest files\n- Schema compliance of all JSON configurations\n- Existence of referenced skill, agent, and command files\n- File size limits for security scanning\n\n```sh\napx plugin validate \napx plugins validate --all\n```\n\n资料来源：[src/cli/utils/plugins.ts:40-70]()\n\n## Related Documentation\n\n- [Catalog Schema](./catalog-schema.md) - Detailed schema for asset catalogs\n- [Security Model](./security-model.md) - Security considerations for agent assets\n- [Setup Guides](./setup/) - Platform-specific installation instructions\n- [CLI Reference](./docs/cli-reference.md) - Complete `apx` command documentation\n\n---\n\n\n\n## MCP Configurations\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Claude Code Integration](#claude-code-integration), [Codex Integration](#codex-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp/claude-code/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/claude-code/github-local.json)\n- [mcp/codex/github-local.toml](https://github.com/yeaight7/agent-powerups/blob/main/mcp/codex/github-local.toml)\n- [mcp/generic/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/generic/github-local.json)\n- [docs/mcp-configs.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/mcp-configs.md)\n- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)\n \n\n# MCP Configurations\n\n## Overview\n\nMCP (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.\n\nThe 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)\n\n## Purpose and Scope\n\nAgent Powerups ships MCP configurations as part of its core asset delivery. The primary goals of these configurations are:\n\n| Goal | Description |\n|------|-------------|\n| **Extensibility** | Provide agents with additional tool capabilities beyond their default feature set |\n| **Safety** | Enable explicit, reviewable MCP server enablement with dry-run support |\n| **Multi-Agent Support** | Offer variant configurations for different agent surfaces (Codex, Claude Code, generic) |\n| **Validation** | Include check, smoke, and install commands to verify configuration integrity |\n\nCurrently, 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)\n\n## Architecture\n\n### Multi-Target Configuration Model\n\nAgent 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.\n\n```\nmcp/\n├── claude-code/\n│ └── github-local.json # Claude Code manifest format\n├── codex/\n│ └── github-local.toml # Codex TOML format\n└── generic/\n └── github-local.json # Generic JSON format\n```\n\nThe 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)\n\n### Configuration Resolution Flow\n\n```mermaid\ngraph TD\n A[apx mcp command] --> B{Which target?}\n B -->|codex| C[Select TOML variant]\n B -->|claude-code| D[Select JSON variant]\n B -->|generic| E[Select JSON variant]\n C --> F[Resolve target path]\n D --> F\n E --> F\n F --> G{Command type?}\n G -->|check| H[Validate config structure]\n G -->|smoke| I[Execute smoke test]\n G -->|install| J[Copy to agent root]\n H --> K[Return validation result]\n I --> L[Run server test]\n J --> M[Write config to target]\n```\n\n## Available MCP Configurations\n\n### github-local\n\nThe `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.\n\n| Property | Value |\n|----------|-------|\n| **Asset Name** | `github-local` |\n| **Type** | mcp-config |\n| **Required Env Vars** | `GITHUB_TOKEN` |\n| **Target Support** | codex, claude-code, generic |\n\n#### Variant Differences\n\n| Agent | File Format | Manifest Location |\n|-------|-------------|-------------------|\n| Claude Code | JSON | `.claude-plugin/plugin.json` |\n| Codex | TOML | `.codex-plugin/plugin.json` |\n| Generic | JSON | Standard MCP JSON format |\n\n资料来源：[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)\n\n## MCP CLI Commands\n\nThe `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)\n\n### Command Reference\n\n| Command | Description | Key Options |\n|---------|-------------|-------------|\n| `apx mcp list` | List all available MCP configurations | - |\n| `apx mcp check --target ` | Validate configuration structure | `--json` for structured output |\n| `apx mcp smoke ` | Execute smoke test against config | `--json` for structured output |\n| `apx mcp print --target ` | Display configuration content | - |\n| `apx mcp install --target ` | Install config to agent root | `--dry-run` for preview |\n| `apx mcp write --target --dest ` | Write config to specific location | - |\n\n### Target Parameters\n\n| Target | Description |\n|--------|-------------|\n| `codex` | OpenAI Codex agent |\n| `claude-code` | Anthropic Claude Code agent |\n| `generic` | Platform-agnostic MCP configuration |\n\n### Usage Examples\n\n```bash\n# Check configuration validity\napx mcp check github-local --target generic --json\n\n# Smoke test the MCP server\napx mcp smoke github-local --json\n\n# Preview installation\napx mcp install github-local --target codex --dry-run\n\n# Install to Claude Code\napx mcp install github-local --target claude-code --dry-run\n\n# Write to custom location\napx mcp write github-local --target generic --dest .agent-powerups/github-local.json\n```\n\n资料来源：[README.md](./README.md) 资料来源：[src/cli/commands/mcp.ts:51-55](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)\n\n## Configuration Validation\n\n### Check Command\n\nThe `check` command validates the structural integrity of an MCP configuration. It verifies:\n\n- Required environment variables are documented\n- Configuration file is valid JSON/TOML\n- All referenced resources are present\n\n```typescript\nexport async function runMcpCheckCommand(\n service: CatalogService,\n assetName: string,\n target: InstallTarget,\n env: NodeJS.ProcessEnv = process.env,\n): Promise>\n```\n\nThe command returns the required environment variables and their current status:\n\n```json\n{\n \"required_env\": [\n { \"name\": \"GITHUB_TOKEN\", \"set\": true }\n ]\n}\n```\n\n资料来源：[src/cli/commands/mcp.ts:57-75](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)\n\n### Smoke Test\n\nThe `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.\n\n## Security Considerations\n\nMCP configurations expand an agent's tool access capabilities. Review all configurations before loading them into a trusted agent environment.\n\n### Security Warnings\n\n| Warning | Description |\n|---------|-------------|\n| **Token Handling** | Replace placeholders like `${GITHUB_TOKEN}` or `YOUR_TOKEN_HERE` with actual values locally; never commit real tokens |\n| **Tool Expansion** | MCP servers can significantly expand what actions an agent can perform |\n| **Explicit Approval** | MCP servers require explicit user approval; always run `apx mcp check` and `apx mcp smoke` before enabling |\n\n资料来源：[src/cli/commands/mcp.ts:40-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts) 资料来源：[README.md](./README.md)\n\n### Safety Best Practices\n\n1. **Review First**: Always inspect configuration content with `apx mcp print` before installing\n2. **Dry Run**: Use `--dry-run` to preview all installation actions\n3. **Smoke Test**: Run `apx mcp smoke` to verify the configuration works\n4. **Environment Isolation**: Use environment variables for secrets rather than hardcoding\n5. **Version Control**: Do not commit configuration files containing real credentials\n\n## Integration with Setup Commands\n\nMCP 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.\n\n```bash\n# Setup includes MCP configs by default\napx setup codex --mode recommended --yes\n\n# MCP configs are review-only in copied files\n# Do not paste tokens into copied files\n```\n\n资料来源：[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)\n\n## Adding New MCP Configurations\n\nTo add a new MCP configuration to Agent Powerups:\n\n### 1. Create Configuration Files\n\nCreate variant-specific configurations in the appropriate subdirectories:\n\n```\nmcp/\n├── /\n│ └── .\n├── /\n│ └── .\n└── generic/\n └── .json\n```\n\n### 2. Register in Catalog\n\nAdd the configuration to the asset catalog with proper metadata:\n\n```json\n{\n \"name\": \"\",\n \"type\": \"mcp-config\",\n \"path\": \"mcp/generic/.json\",\n \"targets\": {\n \"codex\": \"mcp/codex/.toml\",\n \"claude-code\": \"mcp/claude-code/.json\"\n },\n \"mcp\": {\n \"required_env\": [\"API_TOKEN\"],\n \"warning\": \"Requires valid API token\"\n }\n}\n```\n\n### 3. Validate Structure\n\nTest the configuration with the validation commands:\n\n```bash\napx mcp check --target generic --json\napx mcp smoke --json\napx plugins validate --all # If part of a plugin bundle\n```\n\n## Summary\n\nMCP Configurations in Agent Powerups provide a standardized, safe mechanism for extending coding agent capabilities through the Model Context Protocol. Key features include:\n\n- **Multi-target support** for Codex, Claude Code, and generic agents\n- **Local-first design** with explicit review and validation steps\n- **Comprehensive CLI tooling** for check, smoke, and install operations\n- **Security-first approach** requiring explicit approval and dry-run support\n- **Variant-specific configurations** to accommodate different agent platforms\n\n---\n\n\n\n## Hooks and Commands\n\n### 相关页面\n\n相关主题：[Skills System](#skills-system), [Plugin Bundles](#plugin-bundles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hooks/productivity/no-secrets-preflight.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/no-secrets-preflight.md)\n- [hooks/productivity/handoff-summary.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/handoff-summary.md)\n- [hooks/quality/lint-check.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/lint-check.md)\n- [hooks/quality/test-gate.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/test-gate.md)\n- [commands/ship-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/ship-check.md)\n- [commands/triage.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/triage.md)\n- [docs/tool-requirements.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/tool-requirements.md)\n \n\n# Hooks and Commands\n\n## Overview\n\nHooks 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:\n\n- **Hooks** are automated triggers that execute at specific points during agent operations, acting as pre-flight checks or post-action summaries\n- **Commands** are structured, review-first prompts that guide agents through complex multi-step workflows\n\n资料来源：[README.md]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"Agent Environment\"\n A[Agent] --> |triggers| H[Hooks System]\n A --> |invokes| C[Commands System]\n end\n \n subgraph \"Hooks\"\n H --> |productivity| HP1[no-secrets-preflight]\n H --> |productivity| HP2[handoff-summary]\n H --> |quality| HQ1[lint-check]\n H --> |quality| HQ2[test-gate]\n end\n \n subgraph \"Commands\"\n C --> |ship| CS[ship-check]\n C --> |triage| CT[triage]\n end\n \n H --> |execution| F[File System / API]\n C --> |review prompts| R[Review Output]\n```\n\n## Hooks System\n\n### Purpose and Scope\n\nHooks are lightweight automation units that execute automatically at defined points in an agent's lifecycle. They serve as:\n\n1. **Pre-flight checks** - Validate conditions before actions proceed\n2. **Post-action summaries** - Generate documentation after handoffs\n3. **Quality gates** - Ensure code meets standards before progression\n\n资料来源：[hooks/productivity/no-secrets-preflight.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/no-secrets-preflight.md)\n\n### Hook Categories\n\n| Category | Purpose | Hooks |\n|----------|---------|-------|\n| `productivity` | Workflow efficiency and safety | `no-secrets-preflight`, `handoff-summary` |\n| `quality` | Code quality enforcement | `lint-check`, `test-gate` |\n\n### Available Hooks\n\n#### no-secrets-preflight\n\nA productivity hook that scans files for potential secret exposure before agent operations proceed.\n\n**Trigger**: Before file operations or commit actions\n\n**Behavior**:\n- Scans specified files and paths for patterns matching API keys, tokens, and credentials\n- Flags common secret formats: AWS keys, GitHub tokens, database connection strings\n- Reports findings without blocking (advisory mode)\n\n资料来源：[hooks/productivity/no-secrets-preflight.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/no-secrets-preflight.md)\n\n#### handoff-summary\n\nA productivity hook that generates structured summaries during agent-to-agent or session-to-session handoffs.\n\n**Trigger**: End of session or before context transfer\n\n**Output**:\n- Current work status\n- Pending tasks and blockers\n- Relevant context for the receiving agent\n- File modifications summary\n\n资料来源：[hooks/productivity/handoff-summary.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/productivity/handoff-summary.md)\n\n#### lint-check\n\nA quality hook that validates code style and linting compliance.\n\n**Trigger**: Before commit or pull request creation\n\n**Checks**:\n- ESLint/Prettier compliance (TypeScript/JavaScript)\n- Language-specific linting standards\n- Configured rule violations\n\n资料来源：[hooks/quality/lint-check.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/lint-check.md)\n\n#### test-gate\n\nA quality hook that ensures test coverage meets minimum thresholds before code progression.\n\n**Trigger**: Before merge or deployment\n\n**Thresholds**:\n- Minimum coverage percentage (configurable)\n- Required test categories passed\n- No failing test suites\n\n资料来源：[hooks/quality/test-gate.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/quality/test-gate.md)\n\n### Hook Execution\n\n```mermaid\ngraph LR\n A[apx hooks run] --> B[Load Hook Config]\n B --> C[Scan Target Path]\n C --> D{Hook Type?}\n D -->|preflight| E[Execute Checks]\n D -->|summary| F[Generate Report]\n D -->|quality| G[Run Validations]\n E --> H[Report Results]\n F --> H\n G --> I{Checks Pass?}\n I -->|Yes| H\n I -->|No| J[Block Action]\n```\n\n### Hook CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `apx hooks list` | List all available hooks |\n| `apx hooks print ` | Display hook definition and instructions |\n| `apx hooks run --path ` | Execute hook on specified path |\n| `apx hooks run --all` | Execute hook across entire workspace |\n\n资料来源：[README.md]()\n\n## Commands System\n\n### Purpose and Scope\n\nCommands 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:\n\n1. **Guide complex processes** - Step-by-step workflows with checkpoints\n2. **Enforce review points** - Mandatory review stages before progression\n3. **Provide safe runnable checks** - Validated automation with human oversight\n\n资料来源：[commands/ship-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/ship-check.md)\n\n### Available Commands\n\n#### ship-check\n\nA comprehensive pre-release validation command that ensures code is ready for shipping.\n\n**Stages**:\n\n1. **Code Quality Review**\n - Linting compliance\n - Type checking\n - Formatting standards\n\n2. **Test Verification**\n - Unit test coverage\n - Integration test status\n - E2E test results\n\n3. **Security Scan**\n - Secret detection\n - Dependency vulnerability check\n - License compliance\n\n4. **Documentation Review**\n - README completeness\n - Changelog updates\n - API documentation\n\n5. **Final Review**\n - Breaking change detection\n - Version bump validation\n - Release notes generation\n\n资料来源：[commands/ship-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/ship-check.md)\n\n#### triage\n\nA command for systematic issue and PR triage workflow.\n\n**Purpose**: Streamline the process of reviewing, categorizing, and prioritizing incoming issues and pull requests.\n\n**Workflow**:\n1. Extract issue/PR metadata\n2. Assess priority and complexity\n3. Assign appropriate labels\n4. Route to relevant team members or skill sets\n5. Document triage decision\n\n资料来源：[commands/triage.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/triage.md)\n\n### Command CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `apx commands list` | List all available commands |\n| `apx commands print --target ` | Print command for specific agent |\n| `apx commands run --full` | Execute command with full details |\n| `apx commands run --json` | Execute command with JSON output |\n\n资料来源：[README.md]()\n\n## Integration with Agent Workflows\n\n### Hook-Command Relationship\n\n```mermaid\ngraph TD\n subgraph \"Workflow\"\n C1[Start Task] --> H1[Hook: preflight check]\n H1 --> |pass| C2[Plan Review]\n H1 --> |fail| C3[Fix Issues]\n C3 --> H1\n C2 --> CMD1[Command: ship-check]\n CMD1 --> H2[Hook: quality gate]\n H2 --> |pass| CMD2[Command: triage]\n H2 --> |fail| C3\n CMD2 --> H3[Hook: handoff summary]\n H3 --> C4[Complete]\n end\n```\n\n### Target Agent Compatibility\n\n| Asset | Codex | Claude Code | Gemini |\n|-------|-------|-------------|--------|\n| Hooks | ✅ | ✅ | ✅ |\n| Commands | ✅ | ✅ | ✅ |\n\n## Tool Requirements\n\nHooks and Commands may require external tools for full functionality:\n\n### Required Tools by Hook\n\n| Hook | Required Tools |\n|------|----------------|\n| `no-secrets-preflight` | `grep`, `find` |\n| `lint-check` | `eslint`, `prettier` (or language-specific linter) |\n| `test-gate` | `jest`, `pytest`, `go test` (language-specific) |\n\n### Required Tools by Command\n\n| Command | Required Tools |\n|---------|----------------|\n| `ship-check` | `git`, `npm`/`pip`/`cargo`, `eslint`/`ruff`, `jest`/`pytest` |\n| `triage` | `gh` (GitHub CLI), `git` |\n\n资料来源：[docs/tool-requirements.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/tool-requirements.md)\n\n## Usage Examples\n\n### Running a Single Hook\n\n```bash\n# Check for secrets in specific file\napx hooks run no-secrets-preflight --path ./config/secrets.yaml\n\n# Check entire project\napx hooks run no-secrets-preflight --all\n```\n\n### Running a Command\n\n```bash\n# Execute ship-check with full output\napx commands run ship-check --full\n\n# Get JSON output for automation\napx commands run ship-check --json\n```\n\n### Custom Hook Integration\n\nHooks can be integrated into agent workflows by adding to agent configuration:\n\n```markdown\n## Pre-Task Hooks\nBefore any file modification:\n1. Run `apx hooks run no-secrets-preflight --path {target}`\n\n## Post-Task Hooks \nAfter task completion:\n1. Run `apx hooks run handoff-summary --path {workspace}`\n```\n\n## Security Considerations\n\n> **Warning**: Hooks can execute code when supported by the host agent. Review assets before loading them into a trusted agent environment.\n\n资料来源：[README.md]()\n\n### Security Best Practices\n\n1. **Review hooks before enabling** - Examine hook logic for unintended side effects\n2. **Limit hook scope** - Run hooks on specific paths rather than entire filesystem\n3. **Validate tool access** - Ensure required tools are from trusted sources\n4. **Monitor hook output** - Review all hook execution logs\n\n## Extension Points\n\n### Creating Custom Hooks\n\nCustom hooks follow the same structure as shipped hooks:\n\n```\nhooks/\n└── /\n └── .md\n```\n\n### Creating Custom Commands\n\nCustom commands follow the command structure:\n\n```\ncommands/\n└── .md\n```\n\nBoth custom hooks and commands can be discovered and managed through the `apx` CLI using the standard `list`, `print`, and `run` subcommands.\n\n## Summary\n\nHooks and Commands form the operational backbone of Agent Powerups, enabling:\n\n- **Automated quality assurance** through hooks like `lint-check` and `test-gate`\n- **Security pre-flight checks** via `no-secrets-preflight`\n- **Workflow continuity** with `handoff-summary`\n- **Guided complex workflows** through `ship-check` and `triage` commands\n\nTogether, they provide a framework for maintaining code quality, security, and consistent workflows across agent interactions.\n\n---\n\n\n\n## Claude Code Integration\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Codex Integration](#codex-integration), [Gemini Integration](#gemini-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)\n- [docs/setup/claude-code.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/claude-code.md)\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)\n \n\n# Claude Code Integration\n\nClaude 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.\n\n## Overview\n\nAgent 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:\n\n- Reusable skills located at `agent-powerups/skills/`\n- Plugin bundles under `agent-powerups/plugins/`\n- Command packs for specialized workflows\n- MCP server configurations\n- AGENTS.md instruction templates\n\n资料来源：[README.md:1-50]()\n\n## Agent Profile Configuration\n\nClaude Code has a dedicated agent profile defined in the CLI setup system. This profile controls installation paths, environment variables, and instruction file locations.\n\n| Configuration Key | Value |\n|-------------------|-------|\n| Agent identifier | `claude-code` |\n| Display name | Claude Code |\n| Instruction file | `CLAUDE.md` |\n| Default root env vars | `CLAUDE_CONFIG_DIR`, `CLAUDE_HOME` |\n| Default root directory | `~/.claude` |\n| Command target directory | `claude-code` |\n| MCP target directory | `claude-code` |\n\n资料来源：[src/cli/commands/setup.ts:50-65]()\n\n### Environment Variable Resolution\n\nThe setup system resolves the Claude Code root directory by checking environment variables in priority order:\n\n1. `CLAUDE_CONFIG_DIR`\n2. `CLAUDE_HOME`\n3. Fallback to `~/.claude`\n\n```mermaid\ngraph TD\n A[Resolve Claude Code Root] --> B{CLAUDE_CONFIG_DIR set?}\n B -->|Yes| C[Use CLAUDE_CONFIG_DIR]\n B -->|No| D{CLAUDE_HOME set?}\n D -->|Yes| E[Use CLAUDE_HOME]\n D -->|No| F[Use ~/.claude]\n C --> G[Install assets under resolved root]\n E --> G\n F --> G\n```\n\n资料来源：[src/cli/commands/setup.ts:50-65]()\n\n## Installation Modes\n\nClaude Code setup supports three installation modes that control the scope of assets deployed:\n\n### Minimal Mode\n\nBootstrap setup that installs only essential skills. Recommended as a starting point for new users.\n\n```powershell\napx setup claude-code --mode minimal --yes\n```\n\nInstalled skills in minimal mode:\n- `using-powerups`\n- `no-fluff`\n- `repo-map`\n- `writing-plans`\n- `verification-before-completion`\n- `search-before-building`\n\n资料来源：[src/cli/commands/setup.ts:95-100]()\n\n### Recommended Mode\n\nFull recommended setup that installs all stable plugin bundles and the complete skill catalog.\n\n```powershell\napx setup claude-code --mode recommended --yes\n```\n\nThis mode installs the stable plugin bundles:\n- `dev-vitals`\n- `debugging-diagnostics`\n- `quality-gates`\n\n资料来源：[src/cli/commands/setup.ts:100-105]()\n\n### Full Mode\n\nComprehensive staging that includes support assets under `agent-powerups/` and updates existing global instructions with backup preservation.\n\n```powershell\napx setup claude-code --mode full --yes\n```\n\n## Setup Workflow\n\n### Dry-Run Validation\n\nBefore applying any changes, perform a dry-run to preview installation actions:\n\n```powershell\napx setup claude-code --dry-run\n```\n\nThis command displays what would be installed without making filesystem modifications.\n\n### Instruction File Handling\n\nThe setup system handles existing `CLAUDE.md` files with the following logic:\n\n```mermaid\ngraph TD\n A[Setup Claude Code] --> B{CLAUDE.md exists?}\n B -->|Yes| C[Create backup of CLAUDE.md]\n B -->|Yes| D[Append agent-powerups block]\n B -->|No| E[Create instructions directory]\n B -->|No| F[Write agent-powerups.md]\n D --> G[Report manual steps]\n F --> G\n```\n\nWhen `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.\n\n资料来源：[examples/claude-code/README.md:1-25]()\n\n### Explicit Root Installation\n\nFor safer installation to a specific directory:\n\n```powershell\napx setup claude-code --agent-root .agent-powerups-demo\\claude --yes\n```\n\nThis approach isolates the installation to a disposable location for review before committing to the actual Claude Code configuration.\n\n## Asset Deployment Structure\n\nThe setup system copies assets to the following structure under the Claude Code root:\n\n| Source Directory | Target Directory |\n|-----------------|------------------|\n| `skills/` | `agent-powerups/skills/` |\n| `agents-md/` | `agent-powerups/agents-md/` |\n| `hooks/` | `agent-powerups/hooks/` |\n| `workflows/` | `agent-powerups/workflows/` |\n| `commands/generic/` | `agent-powerups/commands/generic/` |\n| `mcp/generic/` | `agent-powerups/mcp/generic/` |\n| `docs/setup/` | `agent-powerups/docs/setup/` |\n\n资料来源：[src/cli/commands/setup.ts:150-160]()\n\n## MCP Configuration for Claude Code\n\nClaude Code has a dedicated MCP target directory. MCP configurations are placed under `agent-powerups/mcp/claude-code/` for review purposes.\n\n### MCP Check Command\n\nValidate an MCP configuration for Claude Code:\n\n```powershell\napx mcp check github-local --target claude-code\n```\n\n### MCP Smoke Test\n\nPerform a smoke test on MCP configuration:\n\n```powershell\napx mcp smoke github-local --json\n```\n\n### MCP Install Preview\n\nPreview a managed Claude Code MCP installation:\n\n```powershell\napx mcp install github-local --target claude-code --dry-run\n```\n\n资料来源：[src/cli/commands/mcp.ts:1-30]()\n\n### Security Notes\n\nMCP snippets under `agent-powerups/mcp/` are marked as review-only. Users should not paste tokens into copied files without local substitution of placeholders.\n\n## Post-Installation Verification\n\nAfter setup, verify the installation using these commands:\n\n```powershell\napx commands print ship-check --target claude-code\napx info using-powerups\n```\n\n### Available Commands for Claude Code\n\n| Command | Purpose |\n|---------|---------|\n| `ship-check` | Run pre-ship validation checks |\n| `using-powerups` | Guide for using Agent Powerups |\n\n### Available Skills\n\nAfter installation, Claude Code has access to skills including:\n\n- `systematic-debugging`\n- `no-fluff`\n- `writing-plans`\n- `ai-slop-cleaner`\n- `bigquery-cost-audit`\n- `data-quality`\n- `dbt-incremental-strategy-audit`\n- `dbt-preflight`\n- `dbt-strategy`\n- `metric-impact-analyzer`\n- `requesting-code-review`\n- `receiving-code-review`\n- `pr-triage`\n- `repo-map`\n- `bug-hunt`\n- `safe-refactor`\n- `sql-business-logic-review`\n- `defuddle`\n- `markitdown-file-intake`\n- `graphify`\n\n## Plugin Bundles\n\nClaude Code supports installation of plugin bundles that group related skills, agents, and commands.\n\n### Stable Plugin Bundles\n\n| Bundle | Description |\n|--------|-------------|\n| `dev-vitals` | Development vitals monitoring |\n| `debugging-diagnostics` | Debugging and diagnostic tools |\n| `quality-gates` | Code quality enforcement |\n\n### Beta Plugin Bundles\n\nAvailable 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`.\n\n### Plugin Installation\n\n```powershell\napx plugins list\napx plugins info dev-vitals\napx plugins validate --all\napx plugins install dev-vitals --target claude-code --dry-run\n```\n\n## Rollback and Cleanup\n\nTo remove an Agent Powerups installation from Claude Code:\n\n```powershell\nRemove-Item .agent-powerups-demo -Recurse -Force\n```\n\nReplace `.agent-powerups-demo` with the actual installation path if a custom root was specified.\n\n## Example: Complete Setup Workflow\n\n```mermaid\ngraph LR\n A[apx doctor] --> B[apx list]\n B --> C[apx setup claude-code --dry-run]\n C --> D[apx setup claude-code --mode recommended --yes]\n D --> E[apx commands print ship-check --target claude-code]\n E --> F[apx plugins install dev-vitals --target claude-code]\n```\n\n1. Run system diagnostics:\n ```powershell\n apx doctor\n ```\n\n2. List available assets:\n ```powershell\n apx list\n ```\n\n3. Preview setup:\n ```powershell\n apx setup claude-code --dry-run\n ```\n\n4. Apply recommended setup:\n ```powershell\n apx setup claude-code --mode recommended --yes\n ```\n\n5. Verify command availability:\n ```powershell\n apx commands print ship-check --target claude-code\n ```\n\n6. Install desired plugin bundle:\n ```powershell\n apx plugins install dev-vitals --target claude-code\n ```\n\n资料来源：[examples/claude-code/README.md:1-30]()\n\n## Limitations and Considerations\n\n- The integration does not modify Claude Code's core configuration files directly\n- MCP server tokens must be replaced locally and should never be committed\n- External tools require explicit user approval before installation\n- Skills may instruct Claude Code to read local files or run commands—review assets before loading them into a trusted agent environment\n- Shell profiles, secrets, background processes, hooks, and MCP servers are not automatically enabled\n\n---\n\n\n\n## Codex Integration\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Claude Code Integration](#claude-code-integration), [Gemini Integration](#gemini-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)\n- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)\n \n\n# Codex Integration\n\n## Overview\n\nThe 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.\n\nAgent 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:\n\n- Copying skills and plugin bundles to the appropriate directory structure\n- Managing the `AGENTS.md` instruction file with marked powerups blocks\n- Configuring MCP server snippets for GitHub integration\n- Validating requirements and performing pre-flight checks\n- Providing a safe, review-first workflow before any mutations occur\n\n资料来源：[README.md](./README.md)\n\n## Architecture\n\n### Agent Profile Configuration\n\nThe Codex agent profile defines the target environment for all installation operations. The profile is defined in `setup.ts` and establishes critical path mappings:\n\n| Parameter | Value | Purpose |\n|-----------|-------|---------|\n| `agent` | `codex` | Agent identifier |\n| `displayName` | `Codex` | Human-readable name |\n| `defaultRootEnv` | `[\"CODEX_HOME\"]` | Environment variable for agent root |\n| `defaultRootDir` | `~/.codex` | Default installation directory |\n| `instructionFileName` | `AGENTS.md` | Primary instruction file |\n| `commandTargetDir` | `codex` | Subdirectory for command assets |\n| `mcpTargetDir` | `codex` | Subdirectory for MCP configurations |\n\n资料来源：[src/cli/commands/setup.ts:46-58](src/cli/commands/setup.ts#L46-L58)\n\n### Directory Structure\n\nAfter successful integration, the following structure is created under `/agent-powerups/`:\n\n```\n/\n├── agent-powerups/\n│ ├── skills/ # Reusable agent workflows\n│ ├── plugins/ # Plugin bundles\n│ ├── agents-md/ # AGENTS.md templates\n│ ├── commands/codex/ # Codex-specific commands\n│ ├── mcp/codex/ # MCP server configurations\n│ ├── hooks/ # Hook examples\n│ ├── workflows/ # Workflow templates\n│ └── docs/setup/ # Setup documentation\n└── AGENTS.md # Updated with powerups block\n```\n\n资料来源：[src/cli/commands/setup.ts:120-135](src/cli/commands/setup.ts#L120-L135)\n\n## Installation Modes\n\nAgent Powerups supports three installation modes for Codex, each catering to different use cases and risk tolerances.\n\n### Mode Comparison\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `minimal` | Bootstrap only with core skills | Testing, constrained environments |\n| `recommended` | Full skill set with stable plugin bundles | Standard development workflow |\n| `full` | Complete staging with all assets | Thorough setup, maximum coverage |\n\n资料来源：[README.md](./README.md)\n\n### Minimal Mode Skills\n\nThe minimal mode installs a curated set of essential skills that provide fundamental capabilities without overwhelming the agent with specialized workflows:\n\n```typescript\nconst MINIMAL_SKILLS = [\n \"using-powerups\", // Orientation to Agent Powerups system\n \"no-fluff\", // Concise, actionable responses\n \"repo-map\", // Repository structure understanding\n \"writing-plans\", // Structured planning capabilities\n \"verification-before-completion\", // Output validation\n \"search-before-building\", // Existing code investigation\n] as const;\n```\n\n资料来源：[src/cli/commands/setup.ts:80-87](src/cli/commands/setup.ts#L80-L87)\n\n### Recommended Mode Additions\n\nThe recommended mode includes the minimal skills plus stable plugin bundles that enhance development productivity:\n\n```typescript\nconst RECOMMENDED_PLUGIN_BUNDLES = [\n \"dev-vitals\", // Development health metrics\n \"debugging-diagnostics\", // Systematic debugging workflows\n \"quality-gates\", // Code quality checkpoints\n] as const;\n```\n\n资料来源：[src/cli/commands/setup.ts:89-93](src/cli/commands/setup.ts#L89-L93)\n\n## Workflows\n\n### Manual Native Install\n\nThe primary installation path for humans is the `apx install` command, which writes native skills and plugin bundles directly to the agent root.\n\n```sh\n# Dry run to preview changes\napx install codex --dry-run\n\n# Standard install with output summary\napx install codex\n\n# Verbose mode showing per-file paths\napx install codex --verbose\n\n# Full install including support assets and instruction updates\napx install codex --full\n```\n\n资料来源：[README.md](./README.md)\n\n### Agent-Curated Setup\n\nFor agent-managed installations, the setup workflow provides an interactive planning phase:\n\n```sh\n# Preview what will happen\napx setup codex --dry-run\n\n# Apply recommended setup\napx setup codex --mode recommended --yes\n```\n\nThe agent will inspect available skills and plugins, propose a plan, and apply it after user approval.\n\n资料来源：[README.md](./README.md)\n\n### MCP Server Integration\n\nThe GitHub MCP server can be integrated with Codex for extended GitHub functionality:\n\n```sh\n# Check MCP configuration validity\napx mcp check github-local --target codex --json\n\n# Smoke test the MCP setup\napx mcp smoke github-local --json\n\n# Dry run before installation\napx mcp install github-local --target codex --dry-run\n\n# Print MCP configuration for review\napx mcp print github-local --target codex\n```\n\n资料来源：[README.md](./README.md)\n\n### Plugin Bundle Installation\n\nIndividual plugin bundles can be installed for specific functionality:\n\n```sh\n# List available bundles\napx plugins list\n\n# Inspect a specific bundle\napx plugins info dev-vitals\n\n# Validate bundle structure\napx plugins validate --all\n\n# Install to Codex with dry run\napx plugins install dev-vitals --target codex --dry-run\n```\n\n资料来源：[README.md](./README.md)\n\n## Instruction File Management\n\n### Block Format\n\nThe integration uses HTML comment markers to wrap the Agent Powerups section in `AGENTS.md`:\n\n```markdown\n\n\n## Agent Powerups\n\nAgent Powerups assets are installed at `/agent-powerups/`.\n\nUse these local assets when relevant:\n- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.\n- Use `apx` commands to discover, inspect, validate, and extend setup.\n- Skills are at `agent-powerups/skills/`.\n- Plugin bundles are at `agent-powerups/plugins/`.\n\n\n```\n\n### Instruction Generation Logic\n\nThe instruction block content varies based on the selected mode:\n\n| Mode | Instruction Content |\n|------|---------------------|\n| `minimal` | Bootstrap guidance with `apx setup` command for recommended mode |\n| `recommended` | Full asset paths, skill locations, MCP guidance, and external tool approval workflow |\n| `full` | Complete instructions with all assets and configuration details |\n\n资料来源：[src/cli/commands/setup.ts:20-50](src/cli/commands/setup.ts#L20-L50)\n\n### Safe Update Behavior\n\nThe system implements safe update patterns to protect existing configurations:\n\n1. If `AGENTS.md` exists, a backup is created before modification\n2. The system searches for existing `agent-powerups` blocks\n3. If a block exists, it is replaced; otherwise, a new block is appended\n4. If `AGENTS.md` does not exist, instructions are written to `agent-powerups/instructions/agent-powerups.md` with manual steps reported\n\n资料来源：[examples/codex/README.md](examples/codex/README.md)\n\n## Validation and Health Checks\n\n### Doctor Command\n\nThe `apx doctor` command performs comprehensive health checks on the installation:\n\n```sh\napx doctor\n```\n\nDoctor checks include:\n- Validating `SKILL.md` frontmatter (name and description required)\n- Verifying support file references exist\n- Checking referenced support files are present\n\n```typescript\nconst frontmatter = parseFrontmatter(content);\nif (!frontmatter?.name || !frontmatter?.description) {\n issues.push(`${entry.name}: missing required frontmatter`);\n}\n\nfor (const ref of referencedSupportFiles(content)) {\n if (!(await supportRefExists(skillDir, ref))) {\n issues.push(`${entry.name}: missing referenced support file ${ref}`);\n }\n}\n```\n\n资料来源：[src/cli/commands/doctor.ts:60-75](src/cli/commands/doctor.ts#L60-L75)\n\n### Requirement Checks\n\nThe `apx check` command validates that requirements are met:\n\n```sh\napx check\n```\n\nThis includes:\n- Parsing requirement declarations from skill and command files\n- Verifying installed versions match requirements\n- Optionally installing missing requirements with user approval\n\n```typescript\nconst hasFailures = statuses.some((status) => status.status === \"MISSING\");\nif (hasFailures) {\n failures += 1;\n if (installOptions?.installMissing) {\n const installResult = await installMissingRequirements(...);\n }\n}\n```\n\n资料来源：[src/cli/commands/check.ts:45-60](src/cli/commands/check.ts#L45-L60)\n\n### Security Audit\n\nThe security audit command scans for potential vulnerabilities in configuration files:\n\n```sh\napx security-audit\n```\n\nDetectable patterns include:\n- Unpinned `:latest` container images\n- Broad filesystem write patterns\n- Install commands without `--dry-run` guards\n- Exposed secrets in configuration\n\n```typescript\n{\n name: \"broad-filesystem-write\",\n severity: \"P1\",\n pattern: /(?:rm\\s+-rf\\s+\\/|\"path\"\\s*:\\s*\"\\*\\*|write_file\\s+\\/\\*\\*)/i,\n detail: () => `broad filesystem write or recursive delete pattern`,\n},\n{\n name: \"missing-dry-run\",\n severity: \"P1\",\n pattern: /(?:npm\\s+install|pip\\s+install|cargo\\s+install|gem\\s+install)\\b(?!.*(?:--dry-run|-n\\b))/i,\n detail: (m) => `install command without --dry-run guard: ${m.trim().slice(0, 60)}`,\n},\n```\n\n资料来源：[src/cli/commands/security-audit.ts:25-40](src/cli/commands/security-audit.ts#L25-L40)\n\n## Example Workflow\n\n### Setting Up for Codex Review\n\nA typical workflow for staging Agent Powerups for Codex review:\n\n```powershell\n# 1. Preview installation changes\napx setup codex --dry-run\n\n# 2. Apply with explicit root directory\napx setup codex --agent-root .agent-powerups-demo\\codex --yes\n\n# 3. Inspect installed skills\napx info using-powerups\napx check using-powerups\n\n# 4. List available commands\napx commands list\n\n# 5. Run pre-flight checks\napx commands run ship-check\napx hooks run no-secrets-preflight --all\n\n# 6. Validate MCP configuration\napx mcp check github-local --target codex --json\napx mcp smoke github-local --json\n```\n\n资料来源：[examples/codex/README.md](examples/codex/README.md)\n\n### Rollback Procedure\n\nTo remove the integration and restore the original state:\n\n```powershell\nRemove-Item .agent-powerups-demo -Recurse -Force\n```\n\n资料来源：[examples/minimal/README.md](examples/minimal/README.md)\n\n## Safety Model\n\nThe integration implements safety boundaries around several areas:\n\n| Category | Protection Mechanism |\n|----------|---------------------|\n| External tools | Require explicit user approval |\n| Secrets | Never paste into agent context unless strictly necessary |\n| Shell profiles | Not modified automatically |\n| MCP enablement | Requires explicit user approval after `apx mcp check` and `apx mcp smoke` |\n| Installation | Default to dry-run; require `--yes` for mutations |\n\n资料来源：[README.md](./README.md)\n\nThe security audit further enforces safety by detecting:\n- Unpinned container images in CI configurations\n- Dangerous filesystem operations\n- Install commands without dry-run guards\n\n资料来源：[src/cli/commands/security-audit.ts:25-45](src/cli/commands/security-audit.ts#L25-L45)\n\n## Requirements Installation\n\nWhen requirements are missing, the system can automatically install them:\n\n```sh\napx check --install-missing --yes\n```\n\nThe installation flow:\n\n1. Identifies supported installers for the platform (npm, pip, cargo, gem)\n2. Generates dry-run output if `--dry-run` is specified\n3. Prompts for confirmation in interactive mode\n4. Executes approved installers with appropriate arguments\n\n```typescript\nconst approved = options.yes || (await confirmInstall(assetName, installers));\nif (!approved) {\n return {\n output: \"install-missing: declined or non-interactive without --yes\",\n warnings: [`${assetName}: install-missing not approved`],\n actions: [],\n };\n}\n```\n\n资料来源：[src/cli/utils/requirements.ts:35-55](src/cli/utils/requirements.ts#L35-L55)\n\n## External Commands Execution\n\nWhen running external commands (e.g., during doctor checks or requirement installation), the system handles platform differences:\n\n```typescript\nconst launchCommand = process.platform === \"win32\" && command.endsWith(\".cmd\")\n ? \"cmd.exe\"\n : command;\nconst launchArgs = process.platform === \"win32\" && command.endsWith(\".cmd\")\n ? [\"/d\", \"/s\", \"/c\", command, ...args]\n : args;\n```\n\nThis ensures proper execution on Windows while maintaining cross-platform compatibility.\n\n资料来源：[src/cli/commands/doctor.ts:78-83](src/cli/commands/doctor.ts#L78-L83)\n\n---\n\n\n\n## Gemini Integration\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [Claude Code Integration](#claude-code-integration), [Codex Integration](#codex-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md)\n- [GEMINI.md](https://github.com/yeaight7/agent-powerups/blob/main/GEMINI.md)\n- [gemini-extension.json](https://github.com/yeaight7/agent-powerups/blob/main/gemini-extension.json)\n- [workflows/agent-relay.md](https://github.com/yeaight7/agent-powerups/blob/main/workflows/agent-relay.md)\n- [src/cli/commands/relay.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/relay.ts)\n- [src/cli/commands/ask.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/ask.ts)\n \n\n# Gemini Integration\n\n## Overview\n\nGemini 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.\n\nThe 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)\n\n## Architecture\n\nThe Gemini Integration consists of three primary layers working in concert:\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n A[\"apx ask-gemini\"] --> B[\"ask.ts\"]\n C[\"apx relay\"] --> D[\"relay.ts\"]\n end\n \n subgraph \"Integration Layer\"\n B --> E[\"Gemini API\"]\n D --> E\n F[\"gemini-extension.json\"] --> G[\"Plugin Bundle\"]\n end\n \n subgraph \"Agent Layer\"\n G --> H[\"Claude Code\"]\n G --> I[\"Codex\"]\n E --> J[\"Persistent Context\"]\n end\n```\n\n### Core Components\n\n| Component | Type | Purpose |\n|-----------|------|---------|\n| `gemini-extension.json` | Plugin Bundle | Claude Code manifest with Gemini extension configuration |\n| `GEMINI.md` | Context File | Default context instructions for Gemini integration |\n| `ask-gemini` | Skill | One-shot delegation skill for single queries |\n| `agent-relay` | Workflow | Persistent relay session workflow |\n| `ask.ts` | CLI Command | Single query execution handler |\n| `relay.ts` | CLI Command | Persistent session management |\n\n资料来源：[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)\n\n## Setup and Configuration\n\n### Prerequisites\n\nBefore using Gemini Integration, ensure the following are available:\n\n- Node.js environment with `apx` CLI installed\n- Valid Google AI API credentials (Gemini API key)\n- Agent Powerups installed via `npm install && npm run build && npm link`\n\n资料来源：[docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md)\n\n### Installation Methods\n\nAgent Powerups supports multiple installation paths for Gemini integration:\n\n#### Manual Native Install\n\n```sh\napx install gemini --dry-run\napx install gemini\napx install gemini --full --verbose\n```\n\nThe `--full` flag stages support assets under `agent-powerups/` and updates existing global instructions with a backup. 资料来源：[README.md](./README.md)\n\n#### Agent-Curated Setup\n\n```sh\napx setup gemini --dry-run\napx setup gemini --mode minimal --yes # bootstrap only\napx setup gemini --mode recommended --yes # recommended setup\napx setup gemini --mode full --yes # broad staging\n```\n\nThe 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)\n\n### Environment Variables\n\nThe following environment variables are required or optional:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GEMINI_API_KEY` | Yes | Google AI API key for Gemini access |\n| `GEMINI_MODEL` | No | Specific Gemini model variant (defaults to provider default) |\n\n## One-Shot Query Mode\n\nThe `ask-gemini` command provides immediate delegation for single queries without maintaining conversation state:\n\n```sh\napx ask-gemini \"Return OK only\" --json\n```\n\n### Usage Patterns\n\n```sh\n# Basic query with JSON output\napx ask-gemini \"Review this plan\" --json\n\n# Check dependencies without execution\napx check ask-gemini\n\n# Preview missing dependencies\napx check ask-gemini --install-missing --dry-run\n```\n\n资料来源：[README.md](./README.md)\n\n### Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as apx ask-gemini\n participant API as Gemini API\n participant Output as JSON Response\n \n User->>CLI: apx ask-gemini \"query\" --json\n CLI->>API: POST request with prompt\n API->>Output: JSON response\n Output-->>User: Structured result\n```\n\n## Persistent Relay Sessions\n\nThe relay system maintains persistent context across multiple conversation turns, enabling more coherent multi-turn workflows:\n\n```sh\napx relay init second-opinion\napx relay start second-opinion --provider gemini\napx relay ask second-opinion \"Review this plan\" --json\napx relay status second-opinion\napx relay stop second-opinion\n```\n\n### Session Lifecycle\n\n| Command | Purpose |\n|---------|---------|\n| `apx relay init ` | Initialize a new relay session |\n| `apx relay start --provider gemini` | Start the session with Gemini provider |\n| `apx relay ask \"\"` | Send a query within the session |\n| `apx relay status ` | Check session status |\n| `apx relay stop ` | Terminate the session |\n\n资料来源：[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)\n\n### Relay Workflow Architecture\n\n```mermaid\ngraph LR\n A[User Request] --> B[Relay Init]\n B --> C[Relay Start]\n C --> D[Context Established]\n D --> E[Relay Ask Query]\n E --> F[Gemini API]\n F --> G[Response + Updated Context]\n G --> E\n G --> H[Relay Stop]\n```\n\n## Plugin Bundle Structure\n\nThe Gemini extension plugin bundle includes manifests for multiple agent surfaces:\n\n```\ngemini-extension/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code Manifest\n├── .codex-plugin/\n│ └── plugin.json # Codex Manifest\n├── GEMINI.md # Context instructions\n└── skills/\n └── ask-gemini/\n └── SKILL.md\n```\n\n### Manifest Validation\n\nThe `apx doctor` command validates plugin bundle integrity across all agent targets:\n\n```sh\napx doctor --full --json\n```\n\nValidation checks include:\n- File existence in all required paths\n- Manifest name consistency\n- Manifest version alignment (must be `0.1.0`)\n- Context filename verification (`GEMINI.md` for Gemini)\n\n资料来源：[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)\n\n## Integration with Profiles\n\nGemini Integration can be accessed through user-intent profiles that bundle relevant skills and plugins:\n\n```sh\napx profiles list\napx profiles info safe-core\napx profiles plan safe-core --target codex\n```\n\nProfiles 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)\n\n## Safety Considerations\n\n### Security Warnings\n\nThe Gemini integration follows Agent Powerups security model:\n\n- **External Tools**: Require explicit user approval before installation\n- **API Keys**: Never paste tokens directly into agent context unless strictly necessary\n- **MCP Servers**: Require explicit user approval via `apx mcp check` and `apx mcp smoke` before enabling\n\n```sh\n# Verify MCP configuration before enabling\napx mcp check github-local --target generic\napx mcp smoke github-local --json\n```\n\n资料来源：[README.md](./README.md) | [docs/setup/gemini.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/setup/gemini.md)\n\n### Dry-Run First\n\nAlways preview operations before execution:\n\n```sh\n# Preview setup without applying\napx setup gemini --dry-run\n\n# Preview installation without writing\napx install gemini --dry-run\n```\n\nDry-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)\n\n## Command Reference\n\n### Quick Reference Table\n\n| Command | Description |\n|---------|-------------|\n| `apx install gemini` | Install Gemini integration natively |\n| `apx setup gemini --dry-run` | Preview Gemini setup |\n| `apx setup gemini --mode recommended --yes` | Apply recommended Gemini setup |\n| `apx ask-gemini \"\" --json` | One-shot Gemini query |\n| `apx relay init ` | Initialize relay session |\n| `apx relay start --provider gemini` | Start Gemini relay |\n| `apx relay ask \"\" --json` | Query in relay session |\n| `apx check ask-gemini` | Verify Gemini dependencies |\n| `apx plugins info gemini-extension` | Inspect plugin bundle |\n| `apx plugins install gemini-extension --target --dry-run` | Preview plugin install |\n\n### Workflow Integration\n\nThe Gemini integration supports the `agent-relay` workflow for complex multi-turn scenarios:\n\n```sh\napx workflows list\napx workflows print feature-iteration\napx workflows print agent-relay\n```\n\nThis 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)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：yeaight7/agent-powerups\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agent-powerups` 与安装入口 `markitdown` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install markitdown`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：v0.1.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown\n\n\n",
"markdown_key": "agent-powerups",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1222971895",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/yeaight7/agent-powerups"
},
{
"evidence_id": "art_a5cf4f252a384e469fdfbc17a984c5ad",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/yeaight7/agent-powerups#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "agent-powerups 说明书",
"toc": [
"https://github.com/yeaight7/agent-powerups 项目说明书",
"目录",
"Project Overview",
"Project Purpose",
"Architecture Overview",
"CLI Interface (apx)",
"Asset Catalog",
"Setup Modes",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "98e37d7f877b2bdc261f8e8795c409ed0ae1adc5",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/philosophy.md",
"docs/release-checklist-v0.1.0.md",
"docs/security-model.md",
"docs/release-checklist-v0.1.1.md",
"docs/profiles-schema.md",
"docs/plugin-bundles-schema.json",
"docs/installation.md",
"docs/catalog-schema.md",
"docs/compatibility.md",
"docs/authoring-guide.md",
"docs/tool-requirements.md",
"docs/mcp-configs.md",
"docs/setup/gemini.md",
"docs/setup/codex.md",
"docs/setup/claude-code.md",
"examples/minimal/README.md",
"examples/codex/README.md",
"examples/claude-code/README.md",
"src/index.ts",
"src/cli/apx.ts",
"src/cli/utils/requirements.ts",
"src/cli/utils/paths.ts",
"src/cli/utils/catalog.ts",
"src/cli/utils/result.ts",
"src/cli/utils/profiles.ts",
"src/cli/utils/args.ts",
"src/cli/utils/plugins.ts",
"src/cli/utils/copy.ts",
"src/cli/utils/formatting.ts",
"src/cli/commands/hooks.ts",
"src/cli/commands/check.ts",
"src/cli/commands/assets.ts",
"src/cli/commands/doctor.ts",
"src/cli/commands/plugin.ts",
"src/cli/commands/validate.ts",
"src/cli/commands/setup.ts",
"src/cli/commands/run-command.ts",
"src/cli/commands/advisor-workflows.ts"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# agent-powerups - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agent-powerups 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等 Claim：`clm_0002` unverified 0.25\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `git clone https://github.com/yeaight7/agent-powerups.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `AGENTS.md`, `CLAUDE.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `AGENTS.md`, `CLAUDE.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `README.md`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：581\n- 重要文件覆盖：40/581\n- 证据索引条目：180\n- 角色 / Skill 条目：179\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 agent-powerups 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agent-powerups 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 agent-powerups 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 179 个角色 / Skill / 项目文档条目。\n\n- **prompt-evaluation-runner**（skill）：Use when evaluating prompts, LLM outputs, red-team suites, or model behavior with local eval configs and safe provider/cost controls. 激活提示：当用户任务与“prompt-evaluation-runner”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`\n- **red-team-eval-authoring**（skill）：Use when creating or reviewing red-team eval plugins, attack templates, grader rubrics, safety fixtures, or model-risk test metadata. 激活提示：当用户任务与“red-team-eval-authoring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`\n- **skill-evaluation-workbench**（skill）：Use when designing, running, debugging, or hardening deterministic eval suites for agent skills, prompts, tool workflows, or MCP-backed cases. 激活提示：当用户任务与“skill-evaluation-workbench”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`\n- **agent-harness-design**（skill）：Design agent tool sets with stable names, narrow schemas, deterministic output shapes, and explicit error paths. No catch-all tools unless unavoidable. 激活提示：当用户任务与“agent-harness-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/agent-harness-design/SKILL.md`\n- **canonical-advisor-routing**（skill）：Process-first advisor routing with artifact capture 激活提示：当用户任务与“canonical-advisor-routing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/canonical-advisor-routing/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before acting. Broad search → exact source and tests → target-specific docs and setup. Stop after enough context or report what is still missing. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/context-retrieval-loop/SKILL.md`\n- **model-routing**（skill）：Vendor-neutral routing guide for choosing the right model tier by task type. Mechanical work uses a smaller/faster model; implementation uses a standard model; architecture, security, and release audit use the most capable model. 激活提示：当用户任务与“model-routing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/model-routing/SKILL.md`\n- **tri-model-review**（skill）：Multi-model orchestration — route to two external advisors, then synthesize 激活提示：当用户任务与“tri-model-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/tri-model-review/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before acting. Broad search → exact source and tests → target-specific docs and setup. Stop after enough context or report what is still missing. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/context-retrieval-loop/SKILL.md`\n- **local-rag-mcp**（skill）：Use when querying, ingesting, or maintaining a local RAG MCP corpus for semantic document retrieval with privacy controls. 激活提示：当用户任务与“local-rag-mcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/local-rag-mcp/SKILL.md`\n- **managed-codebase-context**（skill）：Use when connecting to a managed codebase-context MCP/session service, checking stale maps, or safely using MCP-provided repository context. 激活提示：当用户任务与“managed-codebase-context”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/managed-codebase-context/SKILL.md`\n- **search-before-building**（skill）：Check existing repo capability, external libraries, MCP options, and maintenance risk before writing custom code. Decide adopt/wrap/build with explicit criteria. 激活提示：当用户任务与“search-before-building”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/search-before-building/SKILL.md`\n- **structured-code-search-mcp**（skill）：Use when designing or using MCP-backed structured code search with search, AST query, symbol inventory, and bounded extraction workflows. 激活提示：当用户任务与“structured-code-search-mcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/structured-code-search-mcp/SKILL.md`\n- **ai-slop-cleaner**（skill）：Run an anti-slop cleanup workflow on AI-generated code — regression-tests-first, smell-by-smell, behavior preserved. 激活提示：当用户任务与“ai-slop-cleaner”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/ai-slop-cleaner/SKILL.md`\n- **architecture-simplification**（skill）：Use to collapse over-engineered abstractions, remove unnecessary layers, or consolidate redundant logic. 激活提示：当用户任务与“architecture-simplification”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/architecture-simplification/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before refactoring or maintenance work. Broad search → exact source and tests → config and build setup. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/context-retrieval-loop/SKILL.md`\n- **dead-code-removal**（skill）：Use to identify and safely delete unused functions, classes, exports, and files. 激活提示：当用户任务与“dead-code-removal”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/dead-code-removal/SKILL.md`\n- **dependency-cleanup**（skill）：Use to audit and remove unused or redundant third-party dependencies from package manifests. 激活提示：当用户任务与“dependency-cleanup”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/dependency-cleanup/SKILL.md`\n- **incremental-migration**（skill）：Use when migrating APIs, libraries, or patterns across a large codebase. Ensures safe, step-by-step progress rather than risky mega-commits. 激活提示：当用户任务与“incremental-migration”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/incremental-migration/SKILL.md`\n- **naming-and-structure-cleanup**（skill）：Use to enforce consistent naming conventions and file structures across a project without changing business logic. 激活提示：当用户任务与“naming-and-structure-cleanup”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/naming-and-structure-cleanup/SKILL.md`\n- **safe-refactor**（skill）：Use when code needs restructuring without changing observable behavior. 激活提示：当用户任务与“safe-refactor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/safe-refactor/SKILL.md`\n- **test-preserving-refactor**（skill）：Use to restructure code while guaranteeing that all existing tests continue to pass. 激活提示：当用户任务与“test-preserving-refactor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/test-preserving-refactor/SKILL.md`\n- **deploy-pipeline-runbook**（skill）：Coordinate multi-system deployment steps as a review-first runbook with explicit approval before any external write or promotion action. 激活提示：当用户任务与“deploy-pipeline-runbook”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/connected-apps/skills/deploy-pipeline-runbook/SKILL.md`\n- **bigquery-cost-audit**（skill）：Analyze BigQuery usage, identify cost hotspots, repeated failures, and practical optimization opportunities. 激活提示：当用户任务与“bigquery-cost-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/bigquery-cost-audit/SKILL.md`\n- **data-quality**（skill）：Use when adding or reviewing data quality tests for dbt models in warehouse-backed analytics projects. Covers dbt generic tests, singular tests assert .sql , accepted-values macros, dbt utils patterns, cross-system consistency tests, and warehouse-oriented validation. Use when writing data tests, creating assert .sql files, testing business logic, or validating referential integrity. 激活提示：当用户任务与“data-quality”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/data-quality/SKILL.md`\n- **dbt-incremental-strategy-audit**（skill）：Audit whether a dbt incremental model uses the right incremental strategy for the repo, the data shape, and the operational constraints. 激活提示：当用户任务与“dbt-incremental-strategy-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/dbt-incremental-strategy-audit/SKILL.md`\n- **dbt-preflight**（skill）：Inspect changed dbt assets, estimate blast radius, identify missing tests, and recommend the narrowest safe validation plan. 激活提示：当用户任务与“dbt-preflight”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/dbt-preflight/SKILL.md`\n- **dbt-strategy**（skill）：Use when creating or modifying dimensional dbt models in warehouse-backed analytics projects. Covers a four-layer warehouse architecture sources/staging/core/marts , naming conventions, no-alias SQL rule, surrogate-key and missing-record patterns, incremental strategies, deduplication, and common project macros. Use when building fact tables, dimension tables, staging models, writing SQL, or designing tests. 激活提示：当用户任务与“dbt-strategy”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/dbt-strategy/SKILL.md`\n- **metric-impact-analyzer**（skill）：Evaluate metric and semantic model changes for BI/reporting breakage and business meaning drift. 激活提示：当用户任务与“metric-impact-analyzer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/metric-impact-analyzer/SKILL.md`\n- **semantic-layer-change-review**（skill）：Use when modifying dbt metrics or semantic models to ensure mathematical correctness and backwards compatibility. 激活提示：当用户任务与“semantic-layer-change-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/semantic-layer-change-review/SKILL.md`\n- **sql-business-logic-review**（skill）：Review SQL for business logic correctness, semantic drift, aggregation risk, and silent definition changes. 激活提示：当用户任务与“sql-business-logic-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/sql-business-logic-review/SKILL.md`\n- **bug-hunt**（skill）：Use when reproducing, isolating, and fixing a bug with the smallest safe change. 激活提示：当用户任务与“bug-hunt”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/bug-hunt/SKILL.md`\n- **failure-triage**（skill）：Use when confronted with an unknown failure in CI or production to rapidly categorize the issue before deep debugging. 激活提示：当用户任务与“failure-triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/failure-triage/SKILL.md`\n- **flaky-test-investigation**（skill）：Use to diagnose tests that pass and fail intermittently without code changes. 激活提示：当用户任务与“flaky-test-investigation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/flaky-test-investigation/SKILL.md`\n- **incident-readout**（skill）：Use after fixing a bug to generate a blameless post-mortem summary for human review. 激活提示：当用户任务与“incident-readout”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/incident-readout/SKILL.md`\n- **log-driven-diagnosis**（skill）：Use when debugging complex runtime failures, distributed systems, or issues where a local debugger cannot be attached. 激活提示：当用户任务与“log-driven-diagnosis”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/log-driven-diagnosis/SKILL.md`\n- **minimal-reproduction**（skill）：Use to isolate a bug from a large application into a standalone, runnable script or single test case. 激活提示：当用户任务与“minimal-reproduction”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/minimal-reproduction/SKILL.md`\n- **regression-bisecting**（skill）：Use when a bug was recently introduced but you don't know which commit caused it. 激活提示：当用户任务与“regression-bisecting”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/regression-bisecting/SKILL.md`\n- **systematic-debugging**（skill）：Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. 激活提示：当用户任务与“systematic-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/systematic-debugging/SKILL.md`\n- **agent-harness-design**（skill）：Design agent tool sets with stable names, narrow schemas, deterministic output shapes, and explicit error paths. No catch-all tools unless unavoidable. 激活提示：当用户任务与“agent-harness-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/agent-harness-design/SKILL.md`\n- **agent-runtime-patterns**（skill）：Use when optimizing agent runtime loops, card packs, MCP session lifecycle, tool-call count, or multi-agent orchestration patterns. 激活提示：当用户任务与“agent-runtime-patterns”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/agent-runtime-patterns/SKILL.md`\n- **agent-session-forensics**（skill）：Use when diagnosing agent session history, interrupted tool loops, missing tool results, timing bottlenecks, or subagent trace correlation. 激活提示：当用户任务与“agent-session-forensics”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/agent-session-forensics/SKILL.md`\n- **brainstorming**（skill）：You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. 激活提示：当用户任务与“brainstorming”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/brainstorming/SKILL.md`\n- **context-compression**（skill）：Use when conversation context is bloated, constraints are being forgotten, or a compact handoff is needed before continuing work. 激活提示：当用户任务与“context-compression”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/context-compression/SKILL.md`\n- **context-minimization**（skill）：Use continuously during long tasks. Teaches how to read less, output less, and keep the LLM context window lean and fast. 激活提示：当用户任务与“context-minimization”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/context-minimization/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before acting. Broad search → exact source and tests → target-specific docs and setup. Stop after enough context or report what is still missing. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/context-retrieval-loop/SKILL.md`\n- **dispatching-parallel-agents**（skill）：Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies 激活提示：当用户任务与“dispatching-parallel-agents”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/dispatching-parallel-agents/SKILL.md`\n- **handoff-discipline**（skill）：Use when completing a task or running out of context limit. Ensures the next session or human engineer has exactly what they need to resume work instantly. 激活提示：当用户任务与“handoff-discipline”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/handoff-discipline/SKILL.md`\n- **no-fluff**（skill）：Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says \"no fluff\", \"be concise\", \"use less tokens\", or similar. 激活提示：当用户任务与“no-fluff”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/no-fluff/SKILL.md`\n- **repo-map**（skill）：Use when the task is to understand an unfamiliar codebase, locate key entry points, or summarize architecture before editing. 激活提示：当用户任务与“repo-map”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/repo-map/SKILL.md`\n- **strategic-context-compaction**（skill）：Compact context at logical phase boundaries — after research, after planning, after debugging — rather than mid-task. Preserves useful state while clearing noise. 激活提示：当用户任务与“strategic-context-compaction”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/strategic-context-compaction/SKILL.md`\n- **task-intake**（skill）：Use at the beginning of a new task. Ensures you fully understand the requirements, boundaries, and acceptance criteria before writing code. 激活提示：当用户任务与“task-intake”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/task-intake/SKILL.md`\n- **using-powerups**（skill）：Use when starting work in a repository with Agent Powerups installed, when a task may match a reusable local skill, command, workflow, hook recipe, AGENTS.md template, or MCP feature. 激活提示：当用户任务与“using-powerups”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/using-powerups/SKILL.md`\n- **verification-before-completion**（skill）：Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always 激活提示：当用户任务与“verification-before-completion”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/verification-before-completion/SKILL.md`\n- **writing-plans**（skill）：Use when you have a spec or requirements for a multi-step task, before touching code. 激活提示：当用户任务与“writing-plans”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/writing-plans/SKILL.md`\n- **agent-readable-docs**（skill）：Use when writing technical documentation that needs to be readable by both humans and AI models, converting existing docs to HADS format, validating a HADS document, or optimizing documentation for token-efficient AI consumption. 激活提示：当用户任务与“agent-readable-docs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/agent-readable-docs/SKILL.md`\n- **api-doc-review**（skill）：Verify that API endpoints match their OpenAPI/Swagger specifications. 激活提示：当用户任务与“api-doc-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/api-doc-review/SKILL.md`\n- **architecture-decision-records**（skill）：Record why an architectural choice was made to prevent agents or humans from unintentionally reverting it. 激活提示：当用户任务与“architecture-decision-records”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/architecture-decision-records/SKILL.md`\n- **context-docs**（skill）：Maintain short, focused Markdown files per subsystem to provide agents with isolated context. 激活提示：当用户任务与“context-docs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/context-docs/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering documentation context before writing or updating docs. Broad search → exact source and existing docs → project conventions and setup. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/context-retrieval-loop/SKILL.md`\n- **doc-consistency-check**（skill）：Audit documentation for broken file paths, outdated commands, and renamed variables. 激活提示：当用户任务与“doc-consistency-check”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/doc-consistency-check/SKILL.md`\n- **handoff-documentation**（skill）：Write state-restoration documents for passing tasks between agents or engineers. 激活提示：当用户任务与“handoff-documentation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/handoff-documentation/SKILL.md`\n- **readme-hardening**（skill）：Ensure the project README provides immediate, exact commands for setup, testing, and deployment to help agents and humans bootstrap quickly. 激活提示：当用户任务与“readme-hardening”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/readme-hardening/SKILL.md`\n- **review-comment-style-mining**（skill）：Use when mining PR review comments and text diffs for reusable writing, documentation, tone, and editorial improvement patterns. 激活提示：当用户任务与“review-comment-style-mining”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/review-comment-style-mining/SKILL.md`\n- **gh-address-comments**（skill）：Address actionable GitHub pull request review feedback. Use when the user wants to inspect unresolved review threads, requested changes, or inline review comments on a PR, then implement selected fixes. 激活提示：当用户任务与“gh-address-comments”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/github-ops/skills/gh-address-comments/SKILL.md`\n- **github-ci-failure-triage**（skill）：Inspect GitHub PR checks, fetch actionable failure logs, summarize the breakage, and propose a local fix plan before changing code. 激活提示：当用户任务与“github-ci-failure-triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/github-ops/skills/github-ci-failure-triage/SKILL.md`\n- **pr-review-ci-loop**（skill）：Run a review and CI loop around a pull request with explicit approval gates for code changes, remote writes, and follow-up actions. 激活提示：当用户任务与“pr-review-ci-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/github-ops/skills/pr-review-ci-loop/SKILL.md`\n- **baseline-comparison-review**（skill）：Ensure that new complex models actually outperform simple, naive baselines. 激活提示：当用户任务与“baseline-comparison-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/baseline-comparison-review/SKILL.md`\n- **dataset-split-review**（skill）：Audit the methodology used to split data into train, validation, and test sets. 激活提示：当用户任务与“dataset-split-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/dataset-split-review/SKILL.md`\n- **experiment-tracking-review**（skill）：Verify that all hyperparameters, metrics, and data references are properly logged. 激活提示：当用户任务与“experiment-tracking-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/experiment-tracking-review/SKILL.md`\n- **ml-leakage-check**（skill）：Identify and prevent target leakage in ML preprocessing pipelines. 激活提示：当用户任务与“ml-leakage-check”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/ml-leakage-check/SKILL.md`\n- **model-evaluation-reporting**（skill）：Standardize the reporting of model metrics to ensure statistical rigor and business relevance. 激活提示：当用户任务与“model-evaluation-reporting”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/model-evaluation-reporting/SKILL.md`\n- **reproducible-training-runs**（skill）：Analyzes ML training scripts to enforce seed setting, deterministic operations, and environment tracking for exact reproducibility. 激活提示：当用户任务与“reproducible-training-runs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/reproducible-training-runs/SKILL.md`\n- **training-pipeline-debugging**（skill）：Diagnose NaN losses, out-of-memory errors, and shape mismatches in deep learning or ML pipelines. 激活提示：当用户任务与“training-pipeline-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/training-pipeline-debugging/SKILL.md`\n- **mcp-server-builder**（skill）：Design high-quality MCP servers around workflows, narrow schemas, context-aware outputs, and actionable errors. Use when building or reviewing MCP tools for real agent tasks. 激活提示：当用户任务与“mcp-server-builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/mcp-development/skills/mcp-server-builder/SKILL.md`\n- **defuddle**（skill）：Use when the user provides a URL to a standard web page and clean Markdown extraction with Defuddle would reduce clutter and token cost. 激活提示：当用户任务与“defuddle”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/defuddle/SKILL.md`\n- **graphify**（skill）：any input code, docs, papers, images → knowledge graph → clustered communities → HTML + JSON + audit report. Use when the user wants to build, inspect, or query a cross-file knowledge graph from code, docs, papers, images, or videos with upstream graphify. 激活提示：当用户任务与“graphify”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/graphify/SKILL.md`\n- **markitdown-file-intake**（skill）：Use when the user provides a MarkItDown-supported file or URL and converting it to Markdown first will make inspection easier, cheaper, or more reliable. 激活提示：当用户任务与“markitdown-file-intake”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/markitdown-file-intake/SKILL.md`\n- **memory-build-workflow**（skill）：Use when a user needs to build or refresh persistent graph memory from a mixed corpus and the right path may include graphify, incremental update, or helper conversion before ingestion. 激活提示：当用户任务与“memory-build-workflow”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/memory-build-workflow/SKILL.md`\n- **memory-optimization-workflow**（skill）：Use when deciding the lowest-cost context path for a mixed corpus, especially when choosing among direct reading, helper conversion, graph build, graph update, or graph query. 激活提示：当用户任务与“memory-optimization-workflow”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/memory-optimization-workflow/SKILL.md`\n- 其余 99 个条目见 `AI_CONTEXT_PACK.json`。\n\n## 证据索引\n\n- 共索引 180 条证据。\n\n- **Gemini Setup**（documentation）：Status: compatibility and agent-curated setup path. For manual install, prefer apx install gemini or apx install gemini --full . This document describes what apx setup gemini still does; it is not an official Gemini CLI integration claim. 证据：`docs/setup/gemini.md`\n- **Repository Guidelines**（documentation）：Project Structure & Module Organization Agent Powerups is a Node.js/TypeScript CLI plus a catalog of agent assets. Core CLI code lives in src/cli/ , with command handlers in src/cli/commands/ and shared helpers in src/cli/utils/ . Tests live in test/ as .test.ts . 证据：`AGENTS.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **Project Overview**（documentation）：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. It provides a local-first CLI tool apx for browsing, validating, running, and explicitly installing these agent powerups. 证据：`GEMINI.md`\n- **What Is Here**（documentation）：Quickstart · Plugin Bundles · Installation · Security Model · Contributing 证据：`README.md`\n- **Plugins**（documentation）：Domain-specific plugin bundles for Agent Powerups. Each plugin extends the base powerups with deeper, specialized skills, agents, and commands for a particular engineering domain. 证据：`plugins/README.md`\n- **AGENTS.md**（documentation）：- Inspect model lineage before changing SQL. - Keep metric and semantic changes explicit. - Do not change warehouse credentials or profiles. 证据：`agents-md/dbt-project/AGENTS.md`\n- **AGENTS.md**（documentation）：- Preserve seeds, splits, metrics, and experiment tracking unless requested. - Treat data changes as high-risk. - Keep model comparisons reproducible. 证据：`agents-md/ml-project/AGENTS.md`\n- **AGENTS.md**（documentation）：- Preserve public APIs and contributor workflows. - Read issue or PR context before editing. - Keep changelog, docs, and tests aligned with user-visible changes. 证据：`agents-md/open-source-maintainer/AGENTS.md`\n- **AGENTS.md**（documentation）：- Read package metadata and tests before editing. - Prefer small API-compatible changes. - Do not add dependencies or publishing config unless requested. 证据：`agents-md/python-library/AGENTS.md`\n- **AGENTS.md**（documentation）：- Read the smallest relevant set of files before editing. - Prefer minimal diffs. - Preserve the existing package manager, lint, test, and build flows. - Run the narrowest meaningful validation before claiming completion. - Do not add dependencies, secrets, or global config changes unless explicitly requested. 证据：`agents-md/typescript-app/AGENTS.md`\n- **Claude Code Setup Example**（documentation）：Goal: stage Agent Powerups for Claude Code review. 证据：`examples/claude-code/README.md`\n- **Codex Setup Example**（documentation）：Goal: stage Agent Powerups for Codex review. 证据：`examples/codex/README.md`\n- **Minimal Setup Example**（documentation）：Goal: inspect Agent Powerups without mutating an agent's global config. 证据：`examples/minimal/README.md`\n- **agent-evaluation-lab**（documentation）：Prompt, skill, red-team, and agent behavior evaluation workflows. 证据：`plugins/agent-evaluation-lab/GEMINI.md`\n- **agentic-systems**（documentation）：Multi-model orchestration and advisor routing: tri-model review and canonical advisor routing. 证据：`plugins/agentic-systems/GEMINI.md`\n- **Agents**（documentation）：Agents Experimental agentic-systems agents. 证据：`plugins/agentic-systems/agents/README.md`\n- **Commands**（documentation）：Commands Experimental agentic-systems commands. 证据：`plugins/agentic-systems/commands/README.md`\n- **codebase-intelligence**（documentation）：Search-first codebase understanding, context retrieval, mapping, pattern detection, and living project intelligence. 证据：`plugins/codebase-intelligence/GEMINI.md`\n- **codebase-maintenance**（documentation）：Safe refactoring, dead-code removal, legacy modernization, and dependency hygiene. 证据：`plugins/codebase-maintenance/GEMINI.md`\n- **connected-apps**（documentation）：Review-first runbooks for connected-app workflows and multi-system deployment sequencing. 证据：`plugins/connected-apps/GEMINI.md`\n- **context-efficiency**（documentation）：Context-efficient routing: dispatch tables for workflow, review, and codebase-intelligence commands. 证据：`plugins/context-efficiency/GEMINI.md`\n- **data-engineering**（documentation）：Analytics engineering, dbt patterns, BigQuery optimization, data quality, and pipeline workflows. 证据：`plugins/data-engineering/GEMINI.md`\n- **debugging-diagnostics**（documentation）：Error diagnosis, fault isolation, log forensics, and incident investigation. 证据：`plugins/debugging-diagnostics/GEMINI.md`\n- **dev-vitals**（documentation）：Core developer workflow skills: planning, execution, communication, and powerup discovery. 证据：`plugins/dev-vitals/GEMINI.md`\n- **documentation-systems**（documentation）：Documentation architecture, API reference authoring, ADR writing, readme hardening, and doc quality. 证据：`plugins/documentation-systems/GEMINI.md`\n- **github-ops**（documentation）：GitHub review, comment handling, and CI triage workflows with approval-gated write actions. 证据：`plugins/github-ops/GEMINI.md`\n- **machine-learning-ops**（documentation）：ML pipeline design, experiment tracking, model evaluation, training debugging, and reproducibility. 证据：`plugins/machine-learning-ops/GEMINI.md`\n- **mcp-development**（documentation）：Workflow-first MCP server design with schema-first tools, context-aware outputs, and evaluation discipline. 证据：`plugins/mcp-development/GEMINI.md`\n- **memory-optimization**（documentation）：Graph-backed memory and context optimization bundle with graphify as the primary engine and document-conversion helpers used only when they reduce noise or reread cost. 证据：`plugins/memory-optimization/GEMINI.md`\n- **CLAUDE.md stub**（documentation）：This is a stub reference file. The graphify skill references CLAUDE.md as a documentation source in the target repository. 证据：`plugins/memory-optimization/skills/graphify/references/CLAUDE.md`\n- **quality-gates**（documentation）：Quality enforcement: TDD discipline, code review workflows, release verification, and CI failure analysis. 证据：`plugins/quality-gates/GEMINI.md`\n- **security-guardrails**（documentation）：Security review guidance for agent configs, MCP and filesystem exposure, red-team scenarios, and audit prompts. 证据：`plugins/security-guardrails/GEMINI.md`\n- **Commands**（documentation）：Commands Experimental security-guardrails commands. 证据：`plugins/security-guardrails/commands/README.md`\n- **skill-authoring**（documentation）：Skill creation and extraction workflows for reusable agent guidance. 证据：`plugins/skill-authoring/GEMINI.md`\n- **software-engineering**（documentation）：Subagent orchestration, wave execution, persistent completion, autonomous delivery, and migration batching. 证据：`plugins/software-engineering/GEMINI.md`\n- **Commands**（documentation）：Commands Experimental software-engineering commands. 证据：`plugins/software-engineering/commands/README.md`\n- **spec-driven-development**（documentation）：Requirements clarification, phase planning, workstreams, and wave-based execution for reviewable delivery. 证据：`plugins/spec-driven-development/GEMINI.md`\n- **spec-quality-gates**（documentation）：Quality gates for spec-driven development: adversarial plan verification and structured code review. 证据：`plugins/spec-quality-gates/GEMINI.md`\n- **tool-integrations**（documentation）：Browser, MCP, retrieval, and agent runtime integration skills with conservative setup and safety boundaries. 证据：`plugins/tool-integrations/GEMINI.md`\n- **CLAUDE.md stub**（documentation）：This is a stub reference file. The graphify skill references CLAUDE.md as a documentation source in the target repository. 证据：`skills/graphify/references/CLAUDE.md`\n- **Core Agent Tools - Refactored Assets**（documentation）：Core Agent Tools - Refactored Assets 证据：`staging/refactor/core-agent-tools/README.md`\n- **Package**（package_manifest）：{ \"name\": \"agent-powerups\", \"version\": \"0.3.0\", \"description\": \"Local-first CLI for browsing, validating, running, and explicitly writing agent powerups.\", \"license\": \"Apache-2.0\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/yeaight7/agent-powerups.git\" }, \"bugs\": { \"url\": \"https://github.com/yeaight7/agent-powerups/issues\" }, \"homepage\": \"https://github.com/yeaight7/agent-powerups\", \"keywords\": \"claude-code\", \"codex\", \"ai-agents\", \"skills\", \"mcp\", \"developer-tools\", \"cli\", \"gemini-cli\", \"gemini\", \"skill-pack\", \"plugin\", \"gemini-cli-extension\" , \"bin\": { \"apx\": \"dist/cli/apx.js\" }, \"engines\": { \"node\": \" =20\" }, \"files\": \"dist/\", \"!dist/test/\", \"skills/\",… 证据：`package.json`\n- **Contributing to Agent Powerups**（documentation）：Keep contributions small, explicit, and portable. 证据：`CONTRIBUTING.md`\n- **Prompt Evaluation Runner**（skill_instruction）：When to use Use this skill when you need to evaluate an LLM app, test a prompt, or run red-teaming/vulnerability scans against a target model or application. 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`\n- **Red-Team Eval Authoring**（skill_instruction）：When To Use - Adding a new red-team plugin or grader. - Editing attack templates, rubric tags, or plugin metadata. - Reviewing multimodal or tool-use safety evals for false positives/negatives. 证据：`plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`\n- **Skill Evaluation Workbench**（skill_instruction）：When To Use - A skill or prompt needs repeatable quality checks across models. - A workflow needs file-based graders, command traces, or local artifact checks. - A tool/MCP skill needs a hidden service fixture or sandboxed test workspace. - A previous agent attempt failed and you need trace-driven diagnosis before editing instructions. 证据：`plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`\n- **Agent Harness Design**（skill_instruction）：Use when designing or improving how an agent invokes tools, handles errors, and decides when to stop. 证据：`plugins/agentic-systems/skills/agent-harness-design/SKILL.md`\n- **Canonical Advisor Routing**（skill_instruction）：Route a prompt through a local provider CLI and persist the result as an artifact. 证据：`plugins/agentic-systems/skills/canonical-advisor-routing/SKILL.md`\n- **Context Retrieval Loop**（skill_instruction）：Gather the right codebase context before making changes or spawning subagents. Prevents acting on incomplete information. 证据：`plugins/agentic-systems/skills/context-retrieval-loop/SKILL.md`\n- **Model Routing**（skill_instruction）：Choose the right model tier before starting a task. Overusing a capable model wastes cost and context. Underusing it produces lower quality on complex work. 证据：`plugins/agentic-systems/skills/model-routing/SKILL.md`\n- **Tri-Model Review**（skill_instruction）：Tri-model review routes through two external advisor CLIs, then synthesizes both outputs into one answer. 证据：`plugins/agentic-systems/skills/tri-model-review/SKILL.md`\n- **Context Retrieval Loop**（skill_instruction）：Gather the right codebase context before making changes or spawning subagents. Prevents acting on incomplete information. 证据：`plugins/codebase-intelligence/skills/context-retrieval-loop/SKILL.md`\n- **Local RAG MCP**（skill_instruction）：When to use Use when the task requires semantic search, document ingestion, or querying a local vector database for context retrieval, and an appropriate MCP server is available. 证据：`plugins/codebase-intelligence/skills/local-rag-mcp/SKILL.md`\n- **Managed Codebase Context**（skill_instruction）：When to use Use when managing persistent sessions, dynamic codebase mappings, or managed context states using a dedicated codebase-context MCP server. 证据：`plugins/codebase-intelligence/skills/managed-codebase-context/SKILL.md`\n- **Search Before Building**（skill_instruction）：Before implementing new functionality, verify it does not already exist and that the best option has been considered. 证据：`plugins/codebase-intelligence/skills/search-before-building/SKILL.md`\n- **Structured Code Search MCP**（skill_instruction）：When to use Use when developing a new MCP server, debugging an MCP connection, or integrating an agent with standard MCP protocols. 证据：`plugins/codebase-intelligence/skills/structured-code-search-mcp/SKILL.md`\n- **Purpose**（skill_instruction）：Reduce AI-generated code bloat through systematic, smell-by-smell cleanup that preserves existing behavior and raises signal quality. 证据：`plugins/codebase-maintenance/skills/ai-slop-cleaner/SKILL.md`\n- **Architecture Simplification**（skill_instruction）：Over time, codebases accumulate \"just in case\" abstractions. This skill guides the safe removal of unnecessary complexity. 证据：`plugins/codebase-maintenance/skills/architecture-simplification/SKILL.md`\n- **Context Retrieval Loop Codebase Maintenance**（skill_instruction）：Context Retrieval Loop Codebase Maintenance 证据：`plugins/codebase-maintenance/skills/context-retrieval-loop/SKILL.md`\n- 其余 120 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/setup/gemini.md`, `AGENTS.md`, `CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/setup/gemini.md`, `AGENTS.md`, `CLAUDE.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Project Overview**：importance `high`\n - source_paths: README.md, package.json, catalog.json\n- **Installation Guide**：importance `high`\n - source_paths: docs/installation.md, src/cli/commands/install.ts, src/cli/commands/setup.ts, src/cli/commands/doctor.ts\n- **apx CLI Reference**：importance `high`\n - source_paths: src/cli/apx.ts, src/cli/commands/list.ts, src/cli/commands/plugins.ts, src/cli/commands/profiles.ts, src/cli/commands/mcp.ts\n- **Skills System**：importance `high`\n - source_paths: skills/systematic-debugging/SKILL.md, skills/writing-plans/SKILL.md, skills/safe-refactor/SKILL.md, skills/bug-hunt/SKILL.md, docs/catalog-schema.md\n- **Plugin Bundles**：importance `high`\n - source_paths: plugins/README.md, plugin-bundles.json, .claude-plugin/marketplace.json, .codex-plugin/marketplace.json, docs/plugin-bundles-schema.json\n- **MCP Configurations**：importance `medium`\n - source_paths: mcp/claude-code/github-local.json, mcp/codex/github-local.toml, mcp/generic/github-local.json, docs/mcp-configs.md, src/cli/commands/mcp.ts\n- **Hooks and Commands**：importance `medium`\n - source_paths: hooks/productivity/no-secrets-preflight.md, hooks/productivity/handoff-summary.md, hooks/quality/lint-check.md, hooks/quality/test-gate.md, commands/ship-check.md\n- **Claude Code Integration**：importance `medium`\n - source_paths: docs/setup/claude-code.md, examples/claude-code/README.md, agents-md/typescript-app/AGENTS.md, CLAUDE.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `98e37d7f877b2bdc261f8e8795c409ed0ae1adc5`\n- inspected_files: `package.json`, `README.md`, `docs/philosophy.md`, `docs/release-checklist-v0.1.0.md`, `docs/security-model.md`, `docs/release-checklist-v0.1.1.md`, `docs/profiles-schema.md`, `docs/plugin-bundles-schema.json`, `docs/installation.md`, `docs/catalog-schema.md`, `docs/compatibility.md`, `docs/authoring-guide.md`, `docs/tool-requirements.md`, `docs/mcp-configs.md`, `docs/setup/gemini.md`, `docs/setup/codex.md`, `docs/setup/claude-code.md`, `examples/minimal/README.md`, `examples/codex/README.md`, `examples/claude-code/README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `agent-powerups` 与安装入口 `markitdown` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.1.4\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：yeaight7/agent-powerups\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/yeaight7/agent-powerups 项目说明书\n\n生成时间：2026-05-15 17:26:54 UTC\n\n## 目录\n\n- [Project Overview](#overview)\n- [Installation Guide](#installation)\n- [apx CLI Reference](#cli-reference)\n- [Skills System](#skills-system)\n- [Plugin Bundles](#plugin-bundles)\n- [MCP Configurations](#mcp-configurations)\n- [Hooks and Commands](#hooks-commands)\n- [Claude Code Integration](#claude-code-integration)\n- [Codex Integration](#codex-integration)\n- [Gemini Integration](#gemini-integration)\n\n\n\n## Project Overview\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [apx CLI Reference](#cli-reference), [Skills System](#skills-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [package.json](https://github.com/yeaight7/agent-powerups/blob/main/package.json)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n \n\n# Project Overview\n\nAgent 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.\n\n## Project Purpose\n\nThe 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.\n\nKey objectives:\n\n- Provide **portable, validated skills** that encode best-practice workflows (debugging, code review, planning)\n- Enable **explicit, auditable installation** of agent extensions rather than opaque粘贴\n- Support **multi-agent compatibility** with a single codebase\n- Maintain **safety boundaries** around secrets, shell access, and MCP server enablement\n- Offer **graduated onboarding** through user-intent profiles and dry-run validation\n\n## Architecture Overview\n\nAgent Powerups follows a layered architecture with three primary concerns:\n\n1. **Catalog Layer**: JSON manifests (`catalog.json`, `plugin-bundles.json`, `profiles.json`) that index all available assets\n2. **CLI Layer**: The `apx` command-line interface that provides discovery, validation, and installation\n3. **Asset Layer**: The actual skill files, command packs, MCP configs, hooks, and workflow templates\n\n```mermaid\ngraph TD\n A[User / Agent] -->|apx commands| B[CLI Layer: apx]\n B -->|read| C[Catalog Layer: JSON manifests]\n B -->|validate| D[Source Assets]\n C -->|index| D\n D -->|skills| E[skills/]\n D -->|commands| F[commands/]\n D -->|mcp configs| G[mcp/]\n D -->|hooks| H[hooks/]\n D -->|workflows| I[workflows/]\n D -->|agents-md| J[agents-md/]\n D -->|plugins| K[plugins/]\n B -->|install to| L[Target Agent Root]\n L -->|codex| M[Codex agents]\n L -->|claude-code| N[Claude Code agents]\n L -->|gemini| O[Gemini CLI agents]\n```\n\n## CLI Interface (apx)\n\nThe `apx` CLI is the primary user interface for Agent Powerups. It is implemented in TypeScript and published as the `agent-powerups` npm package.\n\n### Installation\n\n```sh\nnpm install -g agent-powerups\n```\n\nThe CLI requires **Node.js >= 20** and is published at `npm:agent-powerups`.\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `apx list` | List all available skills, commands, and assets |\n| `apx info ` | Display detailed information about a specific asset |\n| `apx check ` | Validate requirements for an asset |\n| `apx doctor` | Run health checks on the local installation |\n| `apx setup ` | Install Agent Powerups to a target agent's root |\n| `apx install ` | Native install of all assets to agent root |\n| `apx plugins list` | List available plugin bundles |\n| `apx plugins install ` | Install a plugin bundle to target |\n| `apx commands run ` | Execute a command pack |\n| `apx hooks run ` | Execute a hook script |\n| `apx mcp check ` | Validate an MCP configuration |\n| `apx mcp smoke ` | Run smoke tests for an MCP server |\n| `apx relay init ` | Initialize a persistent relay session |\n| `apx profiles list` | List available user-intent profiles |\n| `apx ask-claude` | Query Claude for advice via local CLI |\n| `apx ask-gemini` | Query Gemini for advice via local CLI |\n| `apx ask-codex` | Query Codex for advice via local CLI |\n\n资料来源：[package.json:16](https://github.com/yeaight7/agent-powerups/blob/main/package.json)\n\n## Asset Catalog\n\n### Skills\n\nSkills are Markdown files that encode reusable agent workflows. Each skill follows a standardized structure with frontmatter metadata.\n\nCurrent shipped skills include:\n\n| Skill Name | Purpose |\n|------------|---------|\n| `systematic-debugging` | Structured debugging methodology |\n| `no-fluff` | Concise output filtering |\n| `writing-plans` | Project planning workflow |\n| `ai-slop-cleaner` | Clean AI-generated code artifacts |\n| `bigquery-cost-audit` | GCP BigQuery cost analysis |\n| `data-quality` | Data validation and quality checks |\n| `dbt-incremental-strategy-audit` | dbt incremental model review |\n| `dbt-preflight` | dbt project pre-flight checks |\n| `dbt-strategy` | dbt modeling strategy |\n| `metric-impact-analyzer` | Business metric impact assessment |\n| `requesting-code-review` | Code review request workflow |\n| `receiving-code-review` | Code review response workflow |\n| `pr-triage` | Pull request triage process |\n| `repo-map` | Repository structure analysis |\n| `bug-hunt` | Systematic bug investigation |\n| `safe-refactor` | Safe code refactoring procedures |\n| `sql-business-logic-review` | SQL logic validation |\n| `defuddle` | Content extraction from documents |\n| `markitdown-file-intake` | Document ingestion pipeline |\n| `graphify` | Codebase visualization |\n| `ask-claude` | Claude advisory workflow |\n| `ask-gemini` | Gemini advisory workflow |\n| `ask-codex` | Codex advisory workflow |\n| `using-powerups` | Onboarding skill for Agent Powerups |\n\n资料来源：[README.md:89-111](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n### Plugin Bundles\n\nPlugin 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.\n\n| Status | Count | Example Bundles |\n|--------|-------|-----------------|\n| Stable | 3 | `dev-vitals`, `debugging-diagnostics`, `quality-gates` |\n| 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` |\n| Experimental | 4 | `software-engineering`, `agentic-systems`, `security-guardrails`, `agent-evaluation-lab` |\n\n```mermaid\ngraph TD\n A[Plugin Bundle] --> B[skills/]\n A --> C[commands/]\n A --> D[agents/]\n A --> E[.claude-plugin/]\n A --> F[.codex-plugin/]\n B --> G[SKILL.md files]\n C --> H[command-name.md files]\n D --> I[agent-name.md files]\n E --> J[plugin.json - Claude Code Manifest]\n F --> K[plugin.json - Codex Manifest]\n```\n\n### User-Intent Profiles\n\nProfiles are curated collections of skills and plugins for specific use cases. They can be inspected with `apx profiles list` and applied during setup.\n\n资料来源：[README.md:120-130](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## Setup Modes\n\nAgent Powerups supports three installation modes that control the scope of what gets installed:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `minimal` | Bootstrap setup with essential instructions only | Quick evaluation |\n| `recommended` | Core skills, plugins, and instructions | Standard onboarding |\n| `full` | All assets plus support documentation | Comprehensive deployment |\n\nThe setup process:\n\n1. Creates an `agent-powerups/` directory under the agent root\n2. Copies relevant asset directories based on mode\n3. Optionally appends agent-powerups instructions to `AGENTS.md` or `CLAUDE.md`\n4. Backs up existing instruction files before modification\n\n资料来源：[src/cli/commands/setup.ts:14-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n\n```mermaid\nflowchart LR\n A[apx setup codex] --> B{Mode?}\n B -->|minimal| C[Bootstrap instructions only]\n B -->|recommended| D[Skills + plugins + instructions]\n B -->|full| E[All assets + docs]\n C --> F[agent-powerups/]\n D --> F\n E --> F\n F --> G{AGENTS.md exists?}\n G -->|Yes| H[Append marked block
Backup first]\n G -->|No| I[Create instructions file]\n H --> J[Setup complete]\n I --> J\n```\n\n## Supported Agents\n\nAgent Powerups maintains explicit compatibility with three primary agent platforms:\n\n| Agent | Install Command | Asset Target |\n|-------|-----------------|--------------|\n| OpenAI Codex | `apx install codex` | `/skills/`, `/plugins/` |\n| Anthropic Claude Code | `apx install claude` | `/skills/`, `/plugins/` |\n| Google Gemini CLI | `apx install gemini` | `/skills/`, `/extensions/` |\n\nThe CLI uses `--target` flag to specify the destination:\n\n```sh\napx plugins install dev-vitals --target codex --dry-run\napx plugins install dev-vitals --target claude-code --dry-run\n```\n\n资料来源：[src/cli/apx.ts:32-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n## MCP Integration\n\nAgent Powerups ships with a local-first GitHub MCP configuration that includes:\n\n- `apx mcp check` - Validate MCP server configuration\n- `apx mcp smoke` - Run smoke tests against MCP server\n- `apx mcp install` - Explicit installation workflow\n\nThe MCP integration follows a security-first model where MCP servers require explicit user approval before enablement.\n\n资料来源：[README.md:51-54](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## Safety Model\n\nAgent Powerups implements several safety mechanisms:\n\n1. **Dry-run by default**: Most install commands support `--dry-run` to preview changes\n2. **Explicit approval**: Interactive prompts require confirmation unless `--yes` is passed\n3. **Backup before modify**: Setup creates backups of existing instruction files\n4. **Requirement validation**: `apx check` verifies prerequisites before installation\n5. **Security audit**: `apx security-audit` scans for dangerous patterns in scripts\n\nDangerous patterns flagged by the security audit:\n\n| Pattern | Severity | Description |\n|---------|----------|-------------|\n| `unpinned-latest-image` | P2 | Unpinned `:latest` container images in CI |\n| `broad-filesystem-write` | P1 | Broad filesystem write or `rm -rf /` patterns |\n| `missing-dry-run` | P1 | Install commands without `--dry-run` guard |\n\n资料来源：[src/cli/commands/security-audit.ts:18-28](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n\n## Validation and Health Checks\n\n### Doctor Command\n\nThe `apx doctor` command performs comprehensive health checks:\n\n| Check | What It Validates |\n|-------|-------------------|\n| Skill files | All skills have `SKILL.md`, valid frontmatter, and referenced support files exist |\n| External scripts | Registered external scripts can be executed |\n| File permissions | Asset directories are readable |\n| Node.js version | Runtime version compatibility |\n\n资料来源：[src/cli/commands/doctor.ts:35-52](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n### Requirement Checking\n\nThe `apx check` command validates asset requirements:\n\n- Missing requirements are flagged with `MISSING` status\n- Automatic installation is attempted if `--install-missing` is provided\n- Human approval is requested via interactive prompt unless `--yes` is passed\n\n```mermaid\nflowchart TD\n A[apx check ] --> B[Check requirements]\n B --> C{All satisfied?}\n C -->|Yes| D[status=OK]\n C -->|No| E{installMissing?}\n E -->|Yes| F[installMissingRequirements]\n E -->|No| G[status=MISSING]\n F --> H{Interactive?}\n H -->|Yes| I[confirmInstall prompt]\n H -->|No --yes| J[Auto-install]\n I -->|Approved| F\n I -->|Declined| K[warnings.push]\n```\n\n资料来源：[src/cli/commands/check.ts:28-45](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n\n## Directory Structure\n\n```\nagent-powerups/\n├── skills/ # Root-level reusable skills\n├── agents-md/ # AGENTS.md templates\n├── commands/ # Command packs\n│ └── generic/ # Agent-agnostic commands\n├── hooks/ # Hook examples\n├── workflows/ # Workflow templates\n├── mcp/ # MCP configurations\n│ └── generic/ # Agent-agnostic MCP configs\n├── plugins/ # Plugin bundle source\n├── docs/ # Documentation\n├── scripts/ # Validation scripts\n├── .codex-plugin/ # Codex plugin manifest\n├── .claude-plugin/ # Claude Code plugin manifest\n├── apx.ts # CLI entry point\n├── package.json # Package manifest\n├── catalog.json # Asset catalog index\n├── plugin-bundles.json # Plugin bundle index\n└── profiles.json # User-intent profiles\n```\n\n## Version and Release\n\n| Property | Value |\n|----------|-------|\n| Package name | `agent-powerups` |\n| Current version | `0.3.0` |\n| License | Apache-2.0 |\n| Node.js requirement | >= 20 |\n| Repository | `git+https://github.com/yeaight7/agent-powerups.git` |\n\n资料来源：[package.json:1-15](https://github.com/yeaight7/agent-powerups/blob/main/package.json)\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Project Overview](#overview), [apx CLI Reference](#cli-reference), [Claude Code Integration](#claude-code-integration), [Codex Integration](#codex-integration), [Gemini Integration](#gemini-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/install.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/install.ts)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)\n- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)\n- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n \n\n# Installation Guide\n\nAgent 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.\n\n## Overview\n\nAgent Powerups is an Oh My Zsh-style collection of reusable skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for coding agents. The installation system is designed with safety boundaries around external tools, secrets, shell profiles, and MCP enablement. 资料来源：[README.md]()\n\n## Installation Methods\n\nThe system supports four primary installation approaches:\n\n| Method | Command | Use Case |\n|--------|---------|----------|\n| **CLI Manual Install** | `apx install ` | Direct native install for humans |\n| **Agent-Curated Setup** | `apx setup --mode recommended --yes` | Bootstrap an agent with curated assets |\n| **Agent-Managed Setup** | Give agent repo access + run `apx setup` | Let the agent inspect and propose setup |\n| **Minimal Demo** | `apx setup --agent-root --dry-run` | Review assets without mutation |\n\n资料来源：[README.md:1-80]()\n\n## Prerequisites\n\n### System Requirements\n\n- **Node.js**: Required for the `apx` CLI tool\n- **npm** or **yarn**: For installing the CLI package\n- **Python 3.x**: For validation scripts (`validate-skills.py`, `validate-catalog.py`, `check-requirements.py`)\n- **Git**: For cloning the repository (optional, if using npm package)\n\n### Verification Commands\n\nBefore installation, verify your environment:\n\n```sh\napx doctor\napx list\n```\n\nThe `doctor` command checks the CLI installation and dependencies. The `list` command displays all available assets. 资料来源：[examples/minimal/README.md]()\n\n## CLI Installation\n\n### Installing the Package\n\nInstall the `agent-powerups` package globally:\n\n```sh\nnpm install -g agent-powerups\n```\n\nOr use the development version from the repository:\n\n```sh\ngit clone https://github.com/yeaight7/agent-powerups.git\ncd agent-powerups\nnpm install\nnpm run build\nnpm link\n```\n\n资料来源：[examples/minimal/README.md]()\n\n### Global Commands Available\n\nAfter installation, the `apx` command provides access to all functionality:\n\n| Command | Description |\n|---------|-------------|\n| `apx doctor` | Verify CLI installation and dependencies |\n| `apx list` | List all available skills, commands, hooks, and workflows |\n| `apx info ` | Show detailed information about a specific asset |\n| `apx check ` | Validate asset requirements |\n| `apx profiles list` | List user-intent profiles for curated skill/plugin sets |\n\n资料来源：[src/cli/apx.ts:1-100]()\n\n## Native Install (Manual)\n\nThe `apx install` command performs a direct native installation, copying skills and plugin bundles into the selected agent root directory.\n\n### Basic Syntax\n\n```sh\napx install [--verbose]\napx install --full [--verbose]\n```\n\n### Default Install Behavior\n\n| Asset Type | Destination |\n|------------|-------------|\n| Root `skills/` | `/skills/` |\n| Codex/Claude plugin bundles | `/plugins/` |\n| Gemini plugin bundles | `/extensions/` |\n\nHuman output shows counts by default. Use `--verbose` for per-file paths.\n\n### Full Install\n\nThe `--full` flag additionally:\n\n- Stages support assets under `agent-powerups/`\n- Updates existing global instructions with a backup\n\n```sh\napx install codex --full --verbose\n```\n\n### Dry Run\n\nAlways preview changes before applying:\n\n```sh\napx install codex --dry-run\napx install claude --dry-run\napx install gemini --dry-run\n```\n\n### Per-Asset Installation\n\nInstall specific plugin bundles to specific targets:\n\n```sh\napx install --target [--dry-run] [--dest ]\n```\n\nExample:\n\n```sh\napx install dev-vitals --target codex --dry-run\napx install dev-vitals --target codex\n```\n\n资料来源：[README.md:1-150](), [src/cli/apx.ts:100-200]()\n\n## Agent-Curated Setup\n\nThe `apx setup` command provides an agent-curated setup path with different configuration modes.\n\n### Setup Syntax\n\n```sh\napx setup [--mode minimal|recommended|full] [--dry-run|--yes] [--agent-root ] [--instructions-file ] [--json]\n```\n\n### Setup Modes\n\n#### Minimal Mode (Bootstrap)\n\nMinimal mode creates a bootstrap setup with essential references:\n\n```sh\napx setup codex --mode minimal --yes\n```\n\nOutput structure:\n\n```\nSTART_MARKER\n## Agent Powerups\nAgent Powerups assets are installed at ``.\n- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.\n- Use `apx` commands to discover, inspect, validate, and extend setup.\n- MCP servers require explicit user approval.\n- External tools require user approval before install.\nThis is a minimal (bootstrap) setup. To get a recommended agent environment:\n apx setup ${profile.agent} --mode recommended --yes\nEND_MARKER\n```\n\n资料来源：[src/cli/commands/setup.ts:1-50]()\n\n#### Recommended Mode\n\nRecommended mode provides the main agent environment with skills, plugin bundles, and comprehensive instructions:\n\n```sh\napx setup codex --mode recommended --yes\napx setup claude-code --mode recommended --yes\napx setup gemini --mode recommended --yes\n```\n\nThis mode includes:\n\n- All root skills from `skills/`\n- Recommended plugin bundles based on agent profile\n- Command templates and hook examples\n- AGENTS.md templates\n- MCP configuration guidance\n\n#### Full Mode\n\nFull mode performs a broad staging with maximum asset coverage:\n\n```sh\napx setup codex --mode full --yes\n```\n\n## Installation Workflow Diagram\n\n```mermaid\ngraph TD\n A[Start: apx install or apx setup] --> B{Dry Run?}\n B -->|Yes| C[Preview Changes Only]\n B -->|No| D{Interactive?}\n D -->|Yes| E[Confirm Changes]\n D -->|No --yes| F[Auto-Approve]\n C --> G[Display File Operations]\n E -->|Approved| H[Execute Installation]\n E -->|Declined| I[Abort]\n F --> H\n H --> J[Copy Skills to Agent Root]\n H --> K[Copy Plugins to Agent Root]\n H --> L[Update Instructions if --full]\n J --> M[Verify with apx check]\n K --> M\n L --> M\n M --> N[Installation Complete]\n```\n\n## Per-Agent Setup Guides\n\n### Codex Setup\n\n```sh\n# Dry run first\napx setup codex --dry-run\n\n# Safe apply with explicit root\napx setup codex --agent-root .agent-powerups-demo\\codex --yes\n\n# Inspect after setup\napx info using-powerups\napx check using-powerups\n```\n\n**Instruction File Behavior:**\n- If `\\AGENTS.md` exists, setup appends a marked `agent-powerups` block after creating a backup\n- If it does not exist, setup writes `agent-powerups\\instructions\\agent-powerups.md` and reports manual steps\n\n资料来源：[examples/codex/README.md]()\n\n### Claude Code Setup\n\n```sh\n# Dry run first\napx setup claude-code --dry-run\n\n# Safe apply with explicit root\napx setup claude-code --agent-root .agent-powerups-demo\\claude --yes\n\n# Inspect after setup\napx commands print ship-check --target claude-code\napx info using-powerups\n```\n\n**Instruction File Behavior:**\n- If `\\CLAUDE.md` exists, setup appends a marked `agent-powerups` block after creating a backup\n- If it does not exist, setup writes `agent-powerups\\instructions\\agent-powerups.md` and reports manual steps\n\n资料来源：[examples/claude-code/README.md]()\n\n### Gemini Setup\n\n```sh\napx setup gemini --dry-run\napx setup gemini --mode recommended --yes\n```\n\nGemini plugin bundles include `gemini-extension.json` and `GEMINI.md`.\n\n## Agent-Managed Setup\n\nFor agent-curated installation, provide the agent access to this repository and ask it to run:\n\n```sh\napx list\napx profiles list\napx setup --mode recommended --yes\n```\n\nThe agent will:\n1. Inspect available skills and plugins\n2. Propose a configuration plan\n3. Apply the setup based on the selected mode\n\n## Plugin Bundle Installation\n\n### Discovering Plugins\n\n```sh\napx plugins list\napx plugins info dev-vitals\n```\n\n### Validating Plugin Bundles\n\nBefore installation, validate bundle structure:\n\n```sh\napx plugins validate --all\n```\n\n### Installing Plugin Bundles\n\n```sh\napx plugins install dev-vitals --target codex --dry-run\napx plugins install dev-vitals --target codex\n```\n\n### Plugin Bundle Structure\n\nEach plugin follows the standard agent plugin layout:\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code Manifest\n├── .codex-plugin/\n│ └── plugin.json # Codex Manifest\n├── skills/\n│ └── /\n│ └── SKILL.md\n├── agents/\n│ └── .md\n└── commands/\n └── .md\n```\n\n资料来源：[plugins/README.md]()\n\n## MCP Configuration Installation\n\n### Available MCP Commands\n\n| Command | Purpose |\n|---------|---------|\n| `apx mcp list` | List available MCP configurations |\n| `apx mcp print ` | Display MCP configuration |\n| `apx mcp check ` | Validate MCP configuration |\n| `apx mcp smoke ` | Run smoke tests |\n| `apx mcp install ` | Install MCP configuration |\n\n### Installing GitHub MCP\n\n```sh\napx mcp check github-local --target generic\napx mcp smoke github-local --json\napx mcp install github-local --target codex --dry-run\napx mcp install github-local --target codex\n```\n\n## Post-Installation Validation\n\n### Run Validation Scripts\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\npython scripts/check-requirements.py\n```\n\n### Verify Setup\n\n```sh\napx doctor\napx check using-powerups\napx hooks run no-secrets-preflight --all\n```\n\n## Minimal Demo Walkthrough\n\nFor inspecting Agent Powerups without mutating an agent's global config:\n\n```sh\n# 1. Install and link the CLI\nnpm install\nnpm run build\nnpm link\n\n# 2. Verify installation\napx doctor\napx list\n\n# 3. Dry run setup to disposable directory\napx setup codex --agent-root .agent-powerups-demo\\codex --dry-run\n\n# 4. Apply to disposable local root\napx setup codex --agent-root .agent-powerups-demo\\codex --yes\n\n# 5. Review created structure\n.agent-powerups-demo/codex/agent-powerups/skills/\n.agent-powerups-demo/codex/agent-powerups/commands/\n.agent-powerups-demo/codex/agent-powerups/instructions/agent-powerups.md\n\n# 6. Rollback when done\nRemove-Item .agent-powerups-demo -Recurse -Force\n```\n\n资料来源：[examples/minimal/README.md]()\n\n## Safety Considerations\n\nThe installation system implements safety boundaries around:\n\n| Area | Safety Measure |\n|------|----------------|\n| External Tools | Require user approval before install |\n| Secrets | Never paste into agent context unless strictly necessary |\n| Shell Profiles | No automatic shell profile modifications |\n| MCP Servers | Require explicit user approval via `apx mcp check` and `apx mcp smoke` |\n| Hooks | Execute only when supported by host agent |\n\n**Before loading any asset**, review it:\n\n- Skills can instruct an agent to read local files or run commands\n- Hooks can execute code when supported by the host agent\n- MCP configs can expand tool access\n- Install commands can modify the local environment\n\nSee [SECURITY.md](./SECURITY.md) and [docs/security-model.md](./docs/security-model.md) for full security details.\n\n## Command Reference\n\n### Install Command Options\n\n| Option | Description |\n|--------|-------------|\n| `--dry-run` | Preview changes without applying |\n| `--full` | Stage support assets and update global instructions |\n| `--verbose` | Show per-file paths during installation |\n| `--agent-root ` | Specify custom agent root directory |\n| `--instructions-file ` | Specify custom instructions file path |\n| `--force` | Overwrite existing files |\n| `--json` | Output results in JSON format |\n\n### Setup Command Options\n\n| Option | Description |\n|--------|-------------|\n| `--mode minimal\\|recommended\\|full` | Select setup configuration mode |\n| `--dry-run` | Preview changes without applying (default) |\n| `--yes` | Auto-approve and apply changes |\n| `--agent-root ` | Specify custom agent root directory |\n| `--instructions-file ` | Specify custom instructions file path |\n| `--json` | Output results in JSON format |\n\n## Troubleshooting\n\n### CLI Not Found\n\n```sh\nnpm link\n# Or reinstall globally\nnpm install -g agent-powerups\n```\n\n### Dry Run vs Apply\n\nAlways prefer dry-run first:\n\n```sh\napx install codex --dry-run\napx setup codex --dry-run\napx plugins install dev-vitals --target codex --dry-run\n```\n\n### Rollback\n\nIf using explicit `--agent-root` with a disposable directory, simply delete the directory:\n\n```sh\nRemove-Item .agent-powerups-demo -Recurse -Force\n```\n\n### Agent Instructions Not Updated\n\nCheck if the agent's instruction file exists:\n\n- Codex: `\\AGENTS.md`\n- Claude Code: `\\CLAUDE.md`\n\nIf the file doesn't exist, setup writes to `agent-powerups\\instructions\\agent-powerups.md` and reports manual integration steps.\n\n---\n\n\n\n## apx CLI Reference\n\n### 相关页面\n\n相关主题：[Project Overview](#overview), [Installation Guide](#installation), [Plugin Bundles](#plugin-bundles)\n\n\nRelevant Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [src/cli/commands/list.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/list.ts)\n- [src/cli/commands/plugins.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/plugins.ts)\n- [src/cli/commands/profiles.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/profiles.ts)\n- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)\n- [src/cli/commands/validate.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/validate.ts)\n \n\n# apx CLI Reference\n\nThe `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.\n\n## Overview\n\nThe `apx` CLI serves as a safe local CLI with runnable local checks, enabling users to:\n\n- Discover and install reusable skills and plugin bundles\n- Configure agent-specific instruction files\n- Validate tool requirements and dependencies\n- Manage MCP (Model Context Protocol) server configurations\n- Execute security audits and preflight checks\n- Handle persistent relay sessions for multi-agent workflows\n\n资料来源：[src/cli/apx.ts:1-50]()\n\n## Command Hierarchy\n\nThe `apx` CLI organizes commands into a hierarchical structure with multiple subcommand categories.\n\n```mermaid\ngraph TD\n A[apx] --> B[Install Commands]\n A --> C[Setup Commands]\n A --> D[Information Commands]\n A --> E[MCP Commands]\n A --> F[Plugin Commands]\n A --> G[Profile Commands]\n A --> H[Validation Commands]\n A --> I[Security Commands]\n A --> J[Relay Commands]\n A --> K[Phase Commands]\n \n B --> B1[install]\n B --> B2[setup]\n \n C --> C1[setup codex]\n C --> C2[setup claude-code]\n C --> C3[setup gemini]\n \n D --> D1[list]\n D --> D2[info]\n D --> D3[doctor]\n D --> D4[check]\n \n E --> E1[mcp list]\n E --> E2[mcp print]\n E --> E3[mcp check]\n E --> E4[mcp smoke]\n E --> E5[mcp install]\n E --> E6[mcp write]\n \n F --> F1[plugins list]\n F --> F2[plugins info]\n F --> F3[plugins validate]\n F --> F4[plugins install]\n \n G --> G1[profiles list]\n G --> G2[profiles info]\n G --> G3[profiles plan]\n G --> G4[profiles install]\n```\n\n## Installation Commands\n\n### `apx install`\n\nInstalls assets, skills, or plugins to specified agent targets.\n\n```sh\napx install [--full] [--dry-run] [--agent-root ] [--instructions-file