@netpilot/skills 0.3.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "netpilot",
+  "owner": {
+    "name": "NetPilot"
+  },
+  "description": "NetPilot 个人 AI 工程协作插件目录",
+  "plugins": [
+    {
+      "name": "netpilot-skills",
+      "source": "./",
+      "description": "中文工程协作 skills 与可组合工作流",
+      "version": "0.3.2",
+      "author": {
+        "name": "NetPilot"
+      },
+      "category": "development",
+      "tags": [
+        "skills",
+        "engineering",
+        "productivity",
+        "chinese"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "netpilot-skills",
+  "displayName": "NetPilot Skills",
+  "version": "0.3.2",
+  "description": "面向 Claude Code 的中文工程协作 skills 与可组合工作流",
+  "author": {
+    "name": "NetPilot"
+  },
+  "license": "MIT",
+  "keywords": [
+    "skills",
+    "claude-code",
+    "engineering",
+    "productivity",
+    "chinese"
+  ]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "netpilot-skills",
+  "version": "0.3.2",
+  "description": "面向 Codex 的中文工程协作 skills 与可组合工作流",
+  "author": {
+    "name": "NetPilot"
+  },
+  "license": "MIT",
+  "keywords": [
+    "skills",
+    "codex",
+    "engineering",
+    "productivity",
+    "chinese"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "NetPilot Skills",
+    "shortDescription": "中文工程协作 skills 与可组合工作流",
+    "longDescription": "为需求澄清、研究、设计、实现、测试、审查和交接提供中文、可组合、带安全门禁的工作流。",
+    "developerName": "NetPilot",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "使用 $ask 为当前任务选择最短且合适的工作流。",
+      "使用 $grill-with-docs 深入确认方案，并同步维护已确认的领域术语和重要决策。",
+      "使用 $teach 在专用目录中建立可信资料驱动的跨会话学习工作区。"
+    ],
+    "brandColor": "#2563EB"
+  }
+}

package/AGENTS.md

@@ -0,0 +1,55 @@
+# NetPilot Skills 项目规则
+
+本仓库只维护可复用 skills、双宿主 metadata、少量用户级 Codex custom agents、插件打包信息和安全同步脚本。项目初始化模板与 harness engineering 必须在独立仓库中维护，不得把具体业务项目脚手架反向塞入本仓库。
+
+## 语言与命名
+
+- 默认使用中文沟通、中文正文和中文 description；`display_name` 使用由 canonical skill name 派生的英文标题，`short_description` 与 `default_prompt` 使用中文。
+- skill 目录、frontmatter `name`、代码标识符、命令与技术字段使用英文。
+- 同一职责只保留一个主名称；触发与产物重叠时优先合并。
+- `ask` 是唯一工作流路由入口；不得新增 `clarify`、`ask-*` 等同义入口。
+- `grill` 是可由用户或路由器启动的访谈入口，`grilling` 是可复用访谈引擎，两者不得复制同一套流程。
+
+## Skill 编写
+
+- 修改 skill 前读取 `skills/writing-great-skills/SKILL.md`。
+- 每个 `SKILL.md` 必须包含清楚的触发条件、不适用边界、完成标准和反模式。
+- 新 skill 使用 kebab-case，并通过官方 skill 脚手架创建。
+- 每个 skill 必须提供 `agents/openai.yaml`；`default_prompt` 显式提到 `$skill-name`。
+- `display_name` 必须与目录名和 frontmatter `name` 一一对应，例如 `code-review` 显示为 `Code Review`、`tdd` 显示为 `TDD`；不得另造中文别名。
+- 当前采用跨宿主单源策略，所有 skill 的 `policy.allow_implicit_invocation` 保持 `true`，通过正文中的权限门禁限制动作。若未来确实需要宿主级禁用隐式调用，必须先建立可验证的宿主专用生成层，不能只修改 Codex metadata。
+- skill 调用另一 skill 时，说明触发条件、宿主调用形式和返回关系，禁止循环依赖。
+- 只加入实际需要的 `scripts/`、`references/` 或 `assets/`，不要建立空目录。
+
+## 上游吸收
+
+- 可以吸收优秀方法，但必须重新表达并适配本项目的语言、权限和工具边界。
+- 不建立 upstream registry、adoption map 或逐 skill 吸收台账。
+- 复制或实质改编受许可证约束的内容时，只在 `THIRD_PARTY_NOTICES.md` 保留必要声明。
+- 不引入个人化角色、作者口吻、默认 commit/push、未经授权的远程 issue 写入或其他扩大权限的行为。
+
+## Codex Agent 编写
+
+- custom agent 放在 `agents/codex/*.toml`，文件名与 `name` 保持一致；不得覆盖内置 `default`、`worker` 或 `explorer`。
+- 分发 TOML 采用可由 Node.js 确定性校验的严格子集：只允许 `name`、`description`、`developer_instructions`、`model`、`model_reasoning_effort`、`sandbox_mode`，字符串不使用反斜杠转义；需要其他 Codex 配置时由用户或项目层覆盖。
+- agent 保持窄职责和固定返回契约，只保存角色、推理强度与 sandbox；完整前后端规范继续由项目 `AGENTS.md` 和 standards 提供。
+- 分发 agent 默认不固定 `model`，继承当前会话实际可用模型；用户或项目层可以在确认账号能力后覆盖。代码探索使用低推理只读配置；复杂审查和架构判断根据风险提高推理强度，不能只按“读/写”机械分档。
+- reviewer 默认 `read-only`。需要运行测试而写缓存的 verifier 可以使用 `workspace-write`，但正文必须禁止修改受版本控制文件、安装依赖和更新快照。
+- 用户级 agent 只由 CLI 显式组件安装；项目级 `.codex/agents/` 仍由独立 harness 或项目初始化工具负责。
+- skill 引用 custom agent 时使用 `` `agent:<name>` ``，仓库校验必须阻止不存在的 agent 引用。
+
+## 同步与安全
+
+- `npm run sync` 默认必须是 dry-run；只有显式 `--apply` 才能写入用户目录。
+- 默认组件只有 skills；只有显式 `--component agents` 或 `--component all` 才能写入 `~/.codex/agents`。
+- 同步只覆盖 manifest 记录且自上次同步后未被用户修改的文件。
+- 未受管理的同名文件必须报冲突并整批停止，不得提供隐式强制覆盖。
+- 测试必须使用临时 home，禁止触碰真实 `~/.agents`、`~/.claude` 或宿主配置。
+- 本仓库不默认安装插件、不修改宿主 settings，也不执行 commit、push、发布或远程写入。
+
+## 交付门禁
+
+- 同步或校验行为变更必须先写失败测试，再实现。
+- 修改任何 skill、metadata、manifest 或脚本后运行 `npm run verify`。
+- 发布前额外运行 `npm run doctor`、官方 skill validator、Codex plugin validator，并分别严格校验 Claude plugin manifest 与 marketplace manifest。
+- 如实记录未能执行的宿主验证，不得把结构检查等同于真实加载成功。

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+本文件记录用户可观察的版本变化。版本遵循 SemVer；`0.x` 阶段仍可能包含明确说明的兼容性调整。
+
+## 0.3.2
+
+- 首次发布公开 npm 包 `@netpilot/skills`，README 默认使用 npm `latest`，团队和 CI 可固定完整版本。
+- Release 工作流支持 npm Trusted Publishing；首次发布可由 GitHub Secret 注入 token 引导，并由公开 CI 显式生成 provenance，token 不写入仓库。
+
+## 0.3.1
+
+- 公网卫生测试统一使用明确的合成路径，不再保留个人目录语义；发布内容与运行行为不变。
+
+## 0.3.0
+
+- README 将快速安装前置，并改用可移植的学习目录描述和默认分支 GitHub 安装源。
+- 新增公网卫生校验，阻止发布内容重新引入本机绝对路径、旧项目标识或默认分支硬编码。
+- `doctor` 的 Node.js 门槛与包声明统一为 22 或更高版本。
+- Codex Agents 改为继承当前会话模型，避免固定模型在不同账号中安装成功但调用失败。
+- 新增 Agent 编写规范，并由仓库校验阻止分发配置重新固定模型。
+- 支持 Node.js 22/24，CI 使用固定 SHA 的 Actions。
+- 增加人工触发、验证优先的 GitHub Release 工作流；继续禁止意外发布到 npm registry。
+
+## 0.2.0
+
+- 提供 18 个中文工程 Skills 和 5 个可选 Codex Agents。
+- 增加 Codex/Claude Code metadata、CLI 安全同步、冲突保护和打包验证。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetPilot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# NetPilot Skills
+
+一套以中文为主、面向 Codex 并兼容 Claude Code 的工程协作 skills，以及少量可选的 Codex custom agents。本仓库只管理跨项目工作流和用户级角色；项目规则、文档骨架与技术栈组合由 [NetPilot Harness](https://github.com/netpilot-z/harness) 管理。
+
+## 安装
+
+前提：Node.js 版本满足 [`package.json`](package.json) 中的 `engines`。CLI 默认 dry-run，未加 `--apply` 时不会写入用户目录。
+
+预览安装计划：
+
+```shell
+npx --yes @netpilot/skills install
+```
+
+安装 Codex Skills，或同时安装可选 Agents：
+
+```shell
+npx --yes @netpilot/skills install --host codex --apply
+npx --yes @netpilot/skills install --host codex --component all --apply
+```
+
+Claude Code 使用 `--host claude`。默认只安装 Skills；Codex Agents 不会进入 Claude Code。
+
+```shell
+npx --yes @netpilot/skills doctor
+npx --yes @netpilot/skills validate
+```
+
+省略版本时使用 npm 的 `latest`。团队或 CI 需要可复现安装时，可在包名后追加经过验证的完整 SemVer。
+
+频繁使用时可以全局安装：
+
+```shell
+npm install --global @netpilot/skills
+netpilot-skills doctor
+netpilot-skills install --host codex --component all --apply
+```
+
+## 推荐的初始工作流
+
+Skills 是可组合工具，不是固定瀑布流程。入口不确定时使用 `ask`；主 skill 已经明确时直接调用它。
+
+首次进入陌生项目，可先让 agent 只读建立最小上下文：
+
+```text
+请使用 $ask，只读检查项目规则、README、与当前任务相关的入口、测试和工作树状态，
+不要修改文件；然后为当前任务选择最短且合适的 workflow。
+```
+
+| 场景 | 推荐链路 |
+| --- | --- |
+| 跨会话学习 | `teach → 按需 research / grilling → 下一节课` |
+| 模糊方向 | `ask → wayfinder → research / prototype → grill → to-spec` |
+| 重要新功能 | `grill-with-docs → to-spec → to-tickets → tdd / implement → code-review` |
+| 明确的小改动 | `implement → 定向验证` |
+| Bug 根因未知 | `diagnosing-bugs → tdd → code-review` |
+| 跨会话交付 | `to-spec → to-tickets → 分切片实现与审查 → handoff` |
+
+`grill-with-docs` 仅在需要边访谈边维护 `CONTEXT.md`、领域术语或 ADR 时使用；不写项目文档时改用 `grill`。
+
+## Skill 体系
+
+Codex 使用 `$skill-name`；Claude Code 用户级同步使用 `/skill-name`；Claude Code 插件模式使用 `/netpilot-skills:skill-name`。canonical name 和 UI 标题保持英文，说明与默认提示使用中文。
+
+| 阶段 | Skill | 作用与适用时机 | 主要产物 |
+| --- | --- | --- | --- |
+| 路由 | `ask` | 入口不确定或关键边界缺失时选择主 skill | 主 skill、已确认边界与下一步 |
+| 学习 | `teach` | 在专用目录中跨会话学习一个主题 | Mission、资料、课程、术语与学习记录 |
+| 深入确认 | `grill` | 对计划或关键决策进行只读逐题深访 | 事实、决策、假设与未决问题 |
+| 深入确认 | `grill-with-docs` | 访谈时同步维护领域文档和 ADR | 更新后的领域文档与决策记录 |
+| 深入确认 | `grilling` | 供其他 skill 复用的一次一题访谈引擎 | 可继续执行的共识 |
+| 探索 | `wayfinder` | 把巨大或模糊想法收敛成可验证路线 | 候选路径、实验与路线图 |
+| 探索 | `research` | 用一手资料核验陌生或快速变化的事实 | 来源、事实、比较与建议 |
+| 探索 | `prototype` | 用最小可运行实验验证关键假设 | 实验、证据与继续/停止结论 |
+| 设计 | `domain-modeling` | 统一术语、状态、关系和业务不变量 | 术语表、模型与必要 ADR |
+| 设计 | `codebase-design` | 设计模块职责、接口、依赖和测试接缝 | 模块边界与测试策略 |
+| 交付 | `to-spec` | 将已明确结论整理成可实现规格 | 范围、规则与验收标准 |
+| 交付 | `to-tickets` | 将规格拆成可独立验证的垂直任务 | 任务、依赖与验证要求 |
+| 交付 | `implement` | 在已批准边界内实施明确任务 | 范围内改动与验证证据 |
+| 质量 | `tdd` | 用 RED/GREEN/REFACTOR 保护行为变更 | 测试证据与实现 |
+| 质量 | `diagnosing-bugs` | 系统定位尚未证实的根因 | 最小复现、根因与回归建议 |
+| 质量 | `code-review` | 审查正确性、风险、测试和架构边界 | 按严重度排列的 findings |
+| 连续性 | `handoff` | 为跨会话、agent 或人员交接建立恢复点 | 状态、证据、决策与下一步 |
+| 维护 | `writing-great-skills` | 创建、改写、本地化或测试 skill | 可验证的 skill |
+
+`ask` 始终只有一个。`grill` 是默认访谈入口，`grill-with-docs` 负责同步项目文档，`grilling` 是内部访谈引擎。
+
+## Teach：跨会话学习工作区
+
+`teach` 用于围绕明确目标持续学习，并通过短课程、主动练习、反馈和复习保存可靠进度。它不是 `research` 或工程实施的别名：一次性事实问题使用 `research`，需要修改项目则进入工程工作流。
+
+| 教学资产 | 作用 |
+| --- | --- |
+| `MISSION.md` | 学习目标、成功标准、约束和非目标 |
+| `RESOURCES.md` | 经筛选并带用途说明的可信资料 |
+| `GLOSSARY.md` | 已经理解并能正确使用的术语 |
+| `lessons/` | 每次一个目标的短课程与练习 |
+| `learning-records/` | 有练习证据支持的掌握记录 |
+| `NOTES.md` | 稳定教学偏好和必要工作笔记 |
+
+开始时可直接说：
+
+```text
+请使用 $teach，在我指定的独立学习目录中建立学习项目。
+先确认可观察的成功标准并做简短基础诊断，再安排第一节最小课程。
+```
+
+`teach` 只维护用户确认的教学目录，不修改业务代码、项目配置、Git 状态或远程资源。
+
+## Codex Subagents（可选）
+
+完整规则保存在项目 `AGENTS.md` 和 standards 中；skill 保存跨宿主工作流；custom agent 只定义窄职责、推理强度、sandbox 和返回格式。模型默认继承当前 Codex 会话，避免绑定特定账号能力。
+
+| Agent type | 作用 | Model | Reasoning | Sandbox |
+| --- | --- | --- | --- | --- |
+| `code-reader` | 快速只读定位职责、调用链、配置和测试 | 继承会话 | `low` | `read-only` |
+| `frontend-reviewer` | 审查前端状态、交互、可访问性和测试风险 | 继承会话 | `high` | `read-only` |
+| `backend-reviewer` | 审查接口、权限、事务、幂等和数据一致性 | 继承会话 | `high` | `read-only` |
+| `architecture-designer` | 比较模块边界、依赖、数据流和迁移路径 | 继承会话 | `high` | `read-only` |
+| `test-verifier` | 执行测试、类型检查、lint 和构建并压缩证据 | 继承会话 | `medium` | `workspace-write` |
+
+配置位于 `agents/codex/*.toml`。完整边界见 [`docs/agent-authoring.md`](docs/agent-authoring.md)。
+
+## 从源码或插件使用
+
+从源码同步默认只展示计划：
+
+```shell
+npm run sync
+npm run sync -- --apply
+npm run sync -- --host codex --component all --apply
+```
+
+同步器只更新由本项目管理且用户未修改的文件；冲突会在写入前整批停止，不提供 `--force`。写入前会拒绝 symlink/junction 目标；异常中断时保留 staging 证据，不承诺断电级事务。状态保存在 `~/.netpilot-skills/manifest.json`。
+
+仓库也包含 Codex 与 Claude Code plugin manifest。不要同时安装插件副本和普通用户级 Skills，以免出现重复名称。Claude Code 本地验证：
+
+```shell
+claude plugin validate ./.claude-plugin/plugin.json --strict
+claude plugin validate ./.claude-plugin/marketplace.json --strict
+claude --plugin-dir .
+```
+
+## 开发与验证
+
+```shell
+npm run verify
+npm run doctor
+```
+
+项目规范见 [AGENTS.md](./AGENTS.md)，版本变化见 [CHANGELOG.md](./CHANGELOG.md)，第三方声明见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。本项目使用 MIT License；上游内容经过中文化、去个人化和权限收敛，不全量复制上游仓库。

package/SECURITY.md

@@ -0,0 +1,7 @@
+# 安全政策
+
+请不要在公开 Issue 中提交密钥、个人数据、未修复漏洞细节或可直接复现的攻击载荷。
+
+优先使用 GitHub 仓库 `Security` 页面中的私密漏洞报告功能。若该入口不可用，请先通过仓库所有者的 GitHub 联系方式发送不含敏感细节的通知，再协商私密传递方式。
+
+报告应包含受影响版本、前置条件、最小复现、实际影响和已知缓解措施。本项目当前不承诺固定响应 SLA；确认问题后会在 Release 和 Changelog 中说明受影响范围与升级方式。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# 第三方声明
+
+本仓库的部分工作流结构与方法由 [mattpocock/skills](https://github.com/mattpocock/skills) 翻译、蒸馏并重新适配。本地版本去除了个人化角色，改写为中文，并增加了权限、安全、验证与双宿主约束。
+
+无需维护逐 skill 的来源表或吸收记录；本文件仅保留许可证要求所需的最小声明。
+
+## mattpocock/skills
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agents/codex/architecture-designer.toml

@@ -0,0 +1,11 @@
+name = "architecture-designer"
+description = "只读分析模块所有权、接口、依赖方向、数据流与失败边界，比较方案并给出可迁移的架构建议。"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+先读取适用的 AGENTS.md、CONTEXT、ADR、架构标准和与问题直接相关的实现，尊重现有约束与术语。
+明确目标、质量属性和不可改变的边界，再画出现状模块、依赖、数据流、失败面和测试接缝。
+提出最少数量的可行方案，用一致维度比较复杂度、耦合、演进性、迁移成本、可逆性和风险，并给出推荐及反对理由。
+不要修改代码或文档，不要创建 ADR，不要为了未来可能性提前抽象，也不要脱离仓库证据设计理想化系统。
+向主 agent 返回现状证据、候选方案、推荐边界、迁移切片、需要用户决定的取舍和验证方式。
+"""

package/agents/codex/backend-reviewer.toml

@@ -0,0 +1,11 @@
+name = "backend-reviewer"
+description = "只读审查后端与接口变更的契约、权限、数据一致性、事务并发、幂等性、可观测性和测试风险。"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+像后端代码所有者一样审查，优先正确性、安全边界和数据完整性。
+先读取适用的 AGENTS.md、规格、后端标准、接口契约、数据模型和完整 diff，再追踪必要的调用方、迁移与测试。
+重点检查输入验证、认证授权、租户隔离、事务边界、并发与竞态、幂等、错误语义、重试、资源释放、日志与指标以及回归测试。
+不要修改文件，不要执行生产或数据写入，不要把缺少个人偏好的抽象当成问题。
+每个 finding 返回严重度、文件与行、可复现路径、影响和最小修复方向；明确区分已证实问题、未知项和建议验证。
+"""

package/agents/codex/code-reader.toml

@@ -0,0 +1,11 @@
+name = "code-reader"
+description = "快速只读阅读代码库，定位职责、调用链、数据流、配置和相关测试，不承担实现或最终设计决策。"
+model_reasoning_effort = "low"
+sandbox_mode = "read-only"
+developer_instructions = """
+先读取适用的 AGENTS.md 和与任务直接相关的说明，只探索用户指定的问题。
+优先使用快速文本搜索定位入口、符号、调用方、配置和测试，再阅读最小必要上下文。
+区分代码事实、合理推断和仍未知内容；所有关键结论给出可定位的文件或符号证据。
+不要修改文件，不要安装依赖，不要运行会改变项目状态的命令，也不要把探索扩大成全面审查。
+向主 agent 返回简洁的调用链、相关文件、关键事实、未知项和建议下一步。
+"""

package/agents/codex/frontend-reviewer.toml

@@ -0,0 +1,11 @@
+name = "frontend-reviewer"
+description = "只读审查前端变更的正确性、状态与异步交互、可访问性、组件边界、性能和测试风险。"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+像前端代码所有者一样审查，但只报告有证据、可触发且值得修复的问题。
+先读取适用的 AGENTS.md、规格、前端标准、设计系统约束和完整 diff，再检查必要的调用方与测试。
+重点检查行为正确性、状态同步、竞态与取消、错误和加载状态、键盘与屏幕阅读器可用性、组件职责、渲染成本以及测试缺口。
+不要修改文件，不要安装依赖，不要把纯风格偏好或无法证明影响的猜测列为 finding。
+每个 finding 返回严重度、文件与行、触发条件、实际影响和最小修复方向；最后列出未决问题与未执行验证。
+"""

package/agents/codex/test-verifier.toml

@@ -0,0 +1,11 @@
+name = "test-verifier"
+description = "执行已有测试、类型检查、lint 和构建，压缩日志并报告真实验证证据，不负责修改实现。"
+model_reasoning_effort = "medium"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+先读取适用的 AGENTS.md、package scripts、测试说明和主 agent 给出的变更范围，选择最小充分的现有验证命令。
+可以运行会产生正常缓存、coverage 或临时构建产物的测试工具，但不得修改受版本控制的源码、测试、配置或快照。
+不要安装或升级依赖，不要删除文件，不要弱化断言，不要用跳过检查换取绿色结果。
+记录实际命令、退出码和关键输出；失败时定位到最可能的阶段并保留原始错误含义，不擅自修复。
+向主 agent 返回已通过、失败、未执行及其原因，并区分由当前变更引起的失败和环境限制。
+"""

package/bin/netpilot-skills.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const commands = Object.freeze({
+  install: "scripts/sync.mjs",
+  sync: "scripts/sync.mjs",
+  doctor: "scripts/doctor.mjs",
+  validate: "scripts/validate.mjs",
+});
+
+function printHelp() {
+  console.log(`NetPilot Skills CLI
+
+用法：
+  netpilot-skills [install] [--host codex|claude|all] [--component skills|agents|all] [--home PATH] [--apply]
+  netpilot-skills doctor
+  netpilot-skills validate
+  netpilot-skills --version
+
+install 默认只执行 dry-run。确认计划无冲突后，再追加 --apply。
+默认只安装 skills；Codex agents 必须显式选择 --component agents 或 all。
+省略命令或直接传入安装参数时，等同于 install。`);
+}
+
+function packageVersion() {
+  const manifest = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  return manifest.version;
+}
+
+function run() {
+  const rawArguments = process.argv.slice(2);
+  const firstArgument = rawArguments[0];
+
+  if (firstArgument === "--help" || firstArgument === "-h" || firstArgument === "help") {
+    printHelp();
+    return;
+  }
+  if (firstArgument === "--version" || firstArgument === "-v" || firstArgument === "version") {
+    console.log(packageVersion());
+    return;
+  }
+
+  const implicitInstall = firstArgument === undefined || firstArgument.startsWith("-");
+  const command = implicitInstall ? "install" : firstArgument;
+  const commandArguments = implicitInstall ? rawArguments : rawArguments.slice(1);
+  const script = commands[command];
+
+  if (!script) {
+    console.error(`未知命令：${command}`);
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = spawnSync(process.execPath, [path.join(packageRoot, script), ...commandArguments], {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}
+
+run();

package/docs/agent-authoring.md

@@ -0,0 +1,64 @@
+# Codex Agent 编写规范
+
+本文定义 NetPilot 分发 Agent 的最小公共契约。Agent、Skill 与项目规则分别承担专业执行、跨宿主工作流和项目事实，不能互相复制。
+
+## 职责边界
+
+- Agent：保存一个窄角色的关注点、权限边界、证据要求和固定返回格式。
+- Skill：保存触发条件、完整工作流、降级路径、验证与完成标准。
+- 项目 `AGENTS.md` 与 standards：保存业务事实、架构约束、安全红线和项目命令。
+- 主 agent：拆解任务、选择子代理、限制写入范围、整合结论并承担最终判断。
+
+Agent 不应成为完整工作流、项目规范副本或长期人格。实现工作优先使用 Codex 内置 `worker`，代码定位优先使用内置 `explorer` 或本项目的窄职责 `code-reader`。
+
+## 配置约定
+
+文件位于 `agents/codex/<name>.toml`，文件名、`name` 和调用时的 agent type 必须一致。不得覆盖 `default`、`worker` 或 `explorer`。
+
+分发配置使用以下字段：
+
+- `name`、`description`、`developer_instructions`：必填；
+- `model_reasoning_effort`、`sandbox_mode`：按职责显式声明；
+- `model`：可选，默认不固定 `model`，继承当前 Codex 会话实际可用的模型。
+
+固定模型只能作为用户或项目层的本地覆盖。模型名称和账号可用性会变化，仓库不能把结构校验冒充真实账号兼容性，也不能伪造不存在的候选模型自动回退。
+
+## 权限与模型强度
+
+- reviewer、reader、designer 默认 `read-only`，指令正文同时明确禁止写入。
+- verifier 只有在测试工具会产生缓存或构建产物时才使用 `workspace-write`；必须禁止修改受版本控制文件、安装依赖和更新快照。
+- 分发 Agent 禁止 `danger-full-access`。
+- 直接代码定位使用 `low`；测试执行通常使用 `medium`；架构、安全、并发和数据一致性审查使用 `high`。
+- sandbox 是默认值，父任务的实时权限可能覆盖它，因此行为限制不能只依赖 TOML。
+
+## 新增门禁
+
+新增 Agent 前必须同时具备：
+
+1. 至少一个反复出现的真实触发场景；
+2. 与现有 Agent 不重叠的单一职责；
+3. 一个明确调用它的 Skill 或主任务类型；
+4. 固定、可合并的返回契约；
+5. 权限和失败边界；
+6. 结构测试、调用方引用测试和至少一次宿主真实加载记录。
+
+没有真实触发场景时，不提前增加通用 implementer、项目经理或文档角色。宿主不可用时，调用 Skill 必须能够回退到主 agent 的串行流程。
+
+## 返回契约
+
+只读 Agent 返回事实、可定位证据、推断、未知项和建议下一步；Reviewer 按严重度返回可触发 finding；Verifier 返回实际命令、退出码、关键输出、未执行项和环境限制。不得把建议写成已经验证的结论。
+
+## 双宿主策略
+
+Skills 保持 Codex 与 Claude Code 共用单源。Agent 配置是宿主专用适配，不强求两种宿主使用相同格式、模型名或权限语义。真正支持 Claude Code Agent 时，在独立宿主目录中实现并建立能力映射，不复制 Skill 工作流。
+
+## 验证
+
+提交前运行：
+
+```powershell
+npm run verify
+npm run doctor
+```
+
+CI 只执行稳定的离线结构验证。账号登录、模型可用性和实际委派属于可选宿主验证，必须如实记录，不能成为无凭据 CI 的强制门禁。

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@netpilot/skills",
+  "version": "0.3.2",
+  "description": "面向 Codex 与 Claude Code 的中文工程协作 skills 与可选 Codex agents",
+  "keywords": [
+    "codex",
+    "claude-code",
+    "agent-skills",
+    "subagents",
+    "ai-engineering"
+  ],
+  "type": "module",
+  "bin": {
+    "netpilot-skills": "bin/netpilot-skills.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    "agents/",
+    "docs/",
+    ".codex-plugin/",
+    ".claude-plugin/",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netpilot-z/skills.git"
+  },
+  "homepage": "https://github.com/netpilot-z/skills#readme",
+  "bugs": {
+    "url": "https://github.com/netpilot-z/skills/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test",
+    "validate": "node scripts/validate.mjs",
+    "lint:public": "node scripts/public-hygiene.mjs",
+    "doctor": "node scripts/doctor.mjs",
+    "sync": "node scripts/sync.mjs",
+    "verify": "npm run test && npm run validate && npm run lint:public"
+  },
+  "license": "MIT"
+}