NetPilot Skills

面向 Codex、兼容 Claude Code 的中文工程协作 Skills，并附带少量 Codex custom agents。内容覆盖需求澄清、研究、设计、实现、测试、审查、分诊和交接。

快速安装

要求 Node.js 满足 package.json 的 engines。推荐直接安装 npm 已发布的 latest：

npx @netpilot/skills@latest

也可以使用短命令：

npx @netpilot/skills

默认一次性安装当前用户的 Codex Skills（~/.agents/skills）和 Codex 用户 Agents（~/.codex/agents），不会安装 Claude Code Skills，也不需要额外传入 --host codex、--component all 或 --apply。

npx 可能优先匹配当前项目中的同名本地依赖；需要保证选择 npm latest 时使用带 @latest 的命令。团队或 CI 需要可复现安装时，应固定完整 SemVer。

常用高级选项：

npx @netpilot/skills preview                 # 只预览
npx @netpilot/skills --dry-run               # 只预览
npx @netpilot/skills --host claude           # 只安装 Claude Code Skills
npx @netpilot/skills --host all              # 同时安装 Claude Code Skills
npx @netpilot/skills --component skills      # 只安装 Skills
npx @netpilot/skills --component system-agents
npx @netpilot/skills --local                 # 安装到当前项目
npx @netpilot/skills --project PATH          # 安装到指定项目
npx @netpilot/skills doctor
npx @netpilot/skills validate

频繁使用时可以全局安装：

npm install --global @netpilot/skills
netpilot-skills

安装器不会覆盖未受管理或用户修改过的同名文件；发生冲突时整批停止。同步状态保存在 .agents/.state/skills-installer：用户安装位于 home，项目安装位于项目根；旧 .netpilot-skills 会在下一次实际安装时原子迁移，预览只展示计划。旧版安装器在新状态旁留下的空旧目录会安全自愈，含内容的双状态仍会阻断。项目范围只安装 Skills，项目级 Agents 仍由 NetPilot Harness 管理。

核心用法

Codex 使用 $skill-name；Claude Code 用户级安装使用 /skill-name。入口不确定时从 ask 开始，主 Skill 已明确时直接调用。

| 场景 | 推荐链路 | | --- | --- | | 模糊方向 | ask → wayfinder → research / prototype → grill-me → to-spec | | 重要新功能 | grill-with-docs → to-spec → to-tickets → implement → code-review | | 明确小改动 | implement → 定向验证 | | Bug 根因未知 | diagnosing-bugs → tdd → code-review | | 必须由人操作控制台 | wizard → 用户执行 → 原任务 | | 跨会话学习 | teach → 按需 research / grilling → 下一节课 | | 跨会话交付 | to-spec → to-tickets → implement → handoff |

grill-me 是 stateless、只读且不创建本地或远程 artifact 的访谈入口；需要同步维护领域文档或 ADR 时使用 grill-with-docs。

显式调用且目标唯一时，相关 Skills 可以按正文创建本地 branch/commit，或操作明确的 issue、label、assignment 和状态。push、PR、merge、deploy、npm publish 等动作始终需要单独授权。

Skill 体系

| 阶段 | Skill | 适用时机 | 主要产物 | | --- | --- | --- | --- | | 路由 | ask | 入口或关键边界不清楚 | 主 Skill 与已确认边界 | | 学习 | teach | 建立跨会话学习项目 | 课程、资料与学习记录 | | 访谈 | grill-me | 深入盘问但不写文档 | 当前对话中的共识 | | 访谈 | grill-with-docs | 访谈时同步沉淀文档 | 领域文档与 ADR | | 访谈 | grilling | 供其他 Skills 复用访谈 | 已确认决定与未决分支 | | 访谈 | to-questionnaire | 向掌握关键信息的人收集事实或决定 | 可异步填写的问卷 | | 探索 | wayfinder | 大型工作仍处于 fog of war | Decision map 与 frontier | | 探索 | research | 核验陌生或变化中的事实 | 带一手引用的研究文档 | | 探索 | prototype | 用低成本实验验证假设 | Throwaway artifact 与 verdict | | 协作 | wizard | 必须由人操作控制台、录入凭证或完成迁移步骤 | 供用户运行的交互式 Bash 向导 | | 设计 | domain-modeling | 统一术语、状态和不变量 | Glossary、模型与必要 ADR | | 设计 | codebase-design | 判断 Module、Interface 和 Seam | 设计词汇与接口比较 | | 设计 | improve-codebase-architecture | 扫描架构摩擦和 deepening 机会 | HTML 报告与候选项 | | 交付 | to-spec | 把已确认结论整理为规格 | Spec issue 与验收标准 | | 交付 | to-tickets | 把规格拆成垂直任务 | Tickets、blocking 与 frontier | | 交付 | implement | 按明确规格实际实施 | 代码、验证与受控 commit | | 质量 | tdd | 可观察行为需要 RED/GREEN | 测试与最小实现 | | 质量 | diagnosing-bugs | 真实根因尚不明确 | 最小复现、根因与证据 | | 质量 | code-review | 审查 diff、commit 或 PR | Standards + Spec findings | | 质量 | resolving-merge-conflicts | 解决 merge/rebase 冲突 | 已验证的冲突解决结果 | | 维护 | triage | 推进 issue 或外部 PR | 标签、brief、评论或关闭结果 | | 连续性 | handoff | 跨会话或人员交接 | 可恢复的状态与下一步 | | 连续性 | wait-what | 上一条消息缺少背景或过于复杂 | 更简明的重述 | | 维护 | writing-for-agents | 编写 Agent 使用的规则、Skill 或指针文档 | 可预测的 Agent 文档 |

Codex Agents

| Agent | 用途 | 默认配置 | | --- | --- | --- | | frontend-reviewer | 前端状态、交互、可访问性和测试审查 | high / read-only | | backend-reviewer | 接口、权限、事务和数据一致性审查 | high / read-only | | security-reviewer | 应用、Agent、Tool 与供应链安全审查 | high / read-only | | migration-reviewer | schema、回填、兼容切换与恢复审查 | high / read-only | | architecture-designer | 模块边界、依赖和迁移方案比较 | high / read-only | | test-verifier | 执行测试、类型检查、lint 和构建 | medium / workspace-write |

Agents 默认继承当前 Codex 会话模型。代码定位直接使用 Codex 内置 explorer；详细配置见 docs/agent-authoring.md。

项目配置与安全

• Tracker 默认从项目规则和唯一 Git remote 自动发现；自定义配置见 skills/triage/references/project-config.md。
• 双宿主调用 metadata 由仓库校验器保持一致；调用分类不等于写入权限。
• 同步器只更新本项目管理且用户未修改的文件，不提供隐式强制覆盖。
• 上游方法采用 conservation-first 本地化：保留限定词、步骤顺序、失败边界、诊断例子和有方法价值的附件，只移除个人化表达、不存在的命令，并适配真实宿主权限。
• wizard 需要可用 Bash（Windows 可用 Git Bash / WSL）；agent 生成并静态检查，用户执行。模板只支持单行 dotenv，GitHub 写入要求明确仓库和实际确认。

开发

npm run verify
npm run doctor
npm run sync                    # dry-run
npm run sync -- --apply         # 写入用户目录

项目规范见 AGENTS.md，版本变化见 CHANGELOG.md，安全政策见 SECURITY.md，第三方声明见 THIRD_PARTY_NOTICES.md。