skillpack-one 0.1.0-alpha.10

package/docs/plans/2026-09-02-self-organizing-skills-design.zh-CN.md

@@ -0,0 +1,194 @@
+# 可自组织 Skills：架构设计
+
+**状态：** 已接受的设计基线  
+**日期：** 2026-09-02  
+**主语言：** 英文；同时维护中文伴随文档
+
+## 1. 愿景
+
+构建一个开放、兼容 Codex 的系统，把大量互相重叠的 Agent Skill 与 MCP Server，整理成少量可组合、可测试的原子能力。这个集合需要能够解释自己的分类，分别评估“是否命中”与“是否完成”，依据证据进化，并在失败时安全回滚。
+
+它不是把热门 Skill 全部装进来的大礼包，而是一套 Skill 操作系统：
+
+1. **分类 Skill**：先把请求缩小到能力领域。
+2. **原子 Skill**：在明确契约内完成一种边界清晰的能力。
+3. **配方/能力包**：像插件一样组合原子 Skill 与 MCP 依赖，完成真实任务。
+4. **元 Skill**：治理发现、分类、变更、评估、上线、弃用与回滚，包括治理自己。
+5. **训练与评测器**：上线前分别测量路由、流程遵循、任务完成、回归、安全、成本和延迟。
+
+## 2. 核心约束
+
+- 通过 `.agents/skills/<skill-name>/SKILL.md` 保持 Codex 原生发现能力。
+- 通过 `.codex-plugin/plugin.json` 将同一份源码打包为 Codex 插件。
+- 逻辑上采用“先分类、再原子”的两阶段路由。
+- 分类边界来自用户真正想得到的结果，而不是作者、仓库或工具品牌。
+- 建立不少于 300 项的前沿 Skill/MCP 可追溯目录，但不盲目安装和执行第三方代码。
+- 根据能力契约识别重复，并从现有项目中提炼原子能力候选。
+- 英文作为生态兼容的主入口，中文采用 `index.zh-CN.md`；兼容 `*.zh.md` 回退。
+- 首个真实测试底座采用 Pi；DSH 与 Codex 通过统一适配层接入。
+- 自优化只能产生有边界、可审查的补丁，必须通过留出集和安全门禁。
+
+## 3. 方案选择
+
+### 方案 A：物理嵌套目录
+
+把原子 Skill 放进分类目录。结构直观，但不同 Agent 对嵌套发现的支持不稳定，而且重新分类会改变 Skill 路径和身份，因此不采用。
+
+### 方案 B：原生 Skill 平铺 + 分类索引 + 机器注册表（采用）
+
+所有可调用 Skill 都是 `.agents/skills` 的直接子目录。分类 Skill 也是标准 Skill，通过中英文索引逐步披露原子能力；机器可读契约和注册表负责两阶段路由、去重、评测和组合。
+
+这个方案同时满足 Codex 原生兼容、稳定身份、插件分发和确定性测试。
+
+### 方案 C：数据库里的万能路由器
+
+动态性很强，但会形成单点瓶颈，弱化 Codex 的原生 Skill 可见性与渐进披露，因此不作为主架构。
+
+## 4. 核心结构
+
+```text
+.codex-plugin/plugin.json       Codex 插件清单
+skill-src/                      唯一权威模板与能力契约
+skills/                         自动生成的插件 Skill 投影
+.agents/skills/                 自动生成的 Codex 项目 Skill 投影
+catalog/                        300+ 上游能力目录与快照
+taxonomy/                       分类树和边界标准
+packs/                          插件式能力包/配方
+evals/                          训练、开发、留出、对抗与任务集
+src/                            注册表、路由、训练器、适配器和 CLI
+schemas/                        能力契约与目录 Schema
+tests/                          单元、集成和黄金测试
+docs/                           英文文档
+docs/zh-CN/                     中文文档
+```
+
+仓库根目录本身就是插件。当前插件规范要求 Skill 投影位于 `skills/`，Codex 项目原生发现则使用 `.agents/skills/`。生成器从 `skill-src/` 确定性地产生两份投影，CI 拒绝任何漂移。契约与模板仍是唯一事实来源，两个生成目录只是兼容产物；这也避免了 Windows 上不可靠的符号链接。
+
+## 5. 什么叫“原子 Skill”
+
+需要同时满足五个单一性：
+
+- **结果单一：** 只有一个主要的用户可见结果。
+- **产物单一：** 只有一个主导产物或状态变化。
+- **权限单一：** 副作用和授权边界可以独立声明。
+- **评测单一：** 能用一个聚焦的完成标准判断好坏。
+- **失败单一：** 失败后不必重跑无关工作。
+
+若包含多个可以独立复用的结果，就拆成原子 Skill 或改成配方；若拆开后总是一起变化且没有独立意义，则保留为一个原子 Skill。
+
+每个原子 Skill 都有 `skill.contract.yaml`，描述输入、输出、前置条件、失败模式、工具与 MCP 依赖、权限、风险、正向触发词、负向边界、易混淆能力、来源、许可证和评测集。
+
+去重优先比较“结果 + 产物 + 权限 + 评测边界”的契约指纹，而不是只看名称和关键词。
+
+## 6. 分类标准
+
+分类采用多维描述，但路由按以下顺序决策：
+
+1. **用户结果和产物**：最终要得到什么？
+2. **领域**：软件、研究、知识、数据、媒体、商业、运营、个人效率或系统治理。
+3. **生命周期**：发现、规划、创建、转换、分析、验证、发布、运行或治理。
+4. **模态**：代码、文本、文档、表格、幻灯片、图像、音频、视频、浏览器状态或结构化数据。
+5. **依赖**：工具无关、产品专用、MCP、CLI 或 API。
+6. **风险**：只读、可逆写入、对外沟通、高风险专业领域、破坏性或特权操作。
+
+初始一级分类为：软件工程、研究与知识、数据与分析、文档与沟通、设计与媒体、商业与增长、自动化与运营、个人效率、安全与信任、Skill 与 Agent 治理。
+
+一个原子 Skill 可以出现在多个分类索引中，但只有一个稳定身份。只有评测持续显示混淆或过载时，才允许拆分或合并分类。
+
+## 7. 分类 Skill
+
+分类 Skill 不是文件夹标签，而是可被 Codex 命中的特殊 Skill，包含：
+
+- 有区分度的 `SKILL.md`；
+- `references/index.en.md` 与 `references/index.zh-CN.md`；
+- 纳入、排除和边界案例；
+- 自动生成的原子能力索引；
+- “只读取选中的原子 Skill 或配方”的渐进披露规则；
+- 分类版本和节点元数据。
+
+CI 会从契约重新生成/校验索引，防止分类说明与实际能力漂移。
+
+## 8. 元 Skill 与自进化
+
+`meta-skill-governor` 可以扫描、学习、提出修改、评测、上线、弃用、迁移和回滚其他 Skill，也包括自己；但不能静默改写生产 Skill。
+
+固定流程是：
+
+```text
+观察 -> 有边界的变更提案 -> 沙盒构建 -> 训练/开发集
+  -> 留出集和对抗集门禁 -> 人或策略批准 -> 灰度 -> 上线
+  -> 监控 -> 保留或回滚
+```
+
+关键规则：
+
+- 所有修改都是带理由、影响范围和契约差异的补丁。
+- 用来优化的题目不能再作为上线证明。
+- 受保护指标不能回退，安全用例必须全部通过。
+- 元 Skill 修改自己时，也必须走同一流程；同一次提案不能顺便削弱门禁。
+- 默认先弃用并保留历史，物理删除是另一项显式维护动作。
+- 所有决策进入只追加的审计记录。
+
+## 9. 插件思维
+
+项目吸收四个插件原则：
+
+- **Manifest：** 身份、版本、入口、依赖、兼容性显式化。
+- **隔离：** 每个原子 Skill 声明工具、权限和副作用。
+- **组合：** 能力包引用稳定 ID，不复制大段提示词。
+- **生命周期：** 安装、校验、启用、更新、弃用和回滚。
+
+能力包是一份声明式配方，包含原子 Skill、可选 MCP、先后关系、交接产物、语言和验收测试。高频能力包可以暴露一个很薄的编排 Skill，但原子契约仍是事实来源。
+
+## 10. 300+ 上游能力目录
+
+默认只收集元数据和来源，不执行第三方代码。每条记录至少包括仓库与固定 revision、类型、路径、作者、摘要、触发条件、工具、权限、产物、许可证、安全审查、最后验证时间、契约指纹与重复簇。
+
+第一里程碑要求不少于 300 条去重后的前沿记录。无来源、只指向可变分支、ID 重复或许可证缺失的记录不能通过 CI。未知许可证只允许保留在目录中，不允许复制进本仓库。
+
+## 11. 评测与训练软件
+
+题集分为：
+
+- `train`：用于改进描述和规则；
+- `dev`：频繁回归；
+- `test`：发布前不可参与优化的留出集；
+- `adversarial`：歧义、多语言、恶意和负向边界；
+- `tasks`：实际执行并检查产物的任务集。
+
+分别测量分类 hit@1/hit@3、原子 hit@1/hit@3/MRR、正确不调用、流程遵循、任务完成、产物质量、安全、回归、成本和延迟。初始门槛建议为：分类 hit@1 ≥ 0.90，原子 hit@1 ≥ 0.80，完成率 ≥ 0.80，受保护安全集 = 1.00，并且多个独立数据集无受保护回归。
+
+训练器只生成小范围候选补丁，不能只凭一个总分宣称改进，每次运行都必须可复现。
+
+## 12. Pi、DSH 与 Codex
+
+统一适配器提供 `discover`、`route`、`execute` 和 `healthcheck`。首个真实集成选择 Pi，因为当前 Node 环境可直接使用其维护中的包和结构化模式；DSH 采用可选适配器，在选定固定 RC 或稳定版本后接入；Codex 适配器用于原生发现校验和轨迹回放；CI 默认使用不需要 API Key 的确定性 Mock 适配器。
+
+评测记录必须包含 Harness 名称与版本，因为同一 Skill 在不同 Harness 中的命中和执行表现可能不同。
+
+## 13. 双语约定
+
+为了主流生态兼容，`SKILL.md` 使用英文作为规范路由面。详细说明通过相邻的 `*.en.md`、`*.zh-CN.md` 提供；`*.zh.md` 是可选的通用中文回退。解析顺序为精确地区、基础语言、英文、默认版本。
+
+翻译可以调整表达和文化习惯，但不得改变能力边界、安全规则或权限。CI 检查各语言所引用的契约版本和必要章节。
+
+## 14. 安全、失败与恢复
+
+- 收录不等于安装；上游指令在采集时一律视为不可信数据。
+- 采集器不执行仓库脚本。
+- 网络、文件、Shell、密钥、消息发送等权限全部显式声明。
+- 检查提示注入、隐藏下载、凭据访问、破坏性命令和越权。
+- 元 Skill 未经显式审查不得扩大权限。
+- 歧义请求返回候选与解释；依赖缺失返回结构化阻塞原因。
+- 上游拉取失败时保留最近一次已验证快照并标记过期。
+- 失败候选留在沙盒，不改变活动注册表；每个上线版本都有回滚指针。
+
+## 15. 交付阶段
+
+1. **基础层：** Schema、分类、注册表、CLI、插件清单和首批分类/元/原子 Skill。
+2. **证据层：** 300+ 可追溯目录、重复簇和自动生成索引。
+3. **评测层：** 双语路由集、可执行任务集、Mock 与 Pi 适配器。
+4. **进化层：** 有边界的训练循环、上线门禁、审计和回滚。
+5. **生态层：** 能力包、DSH 适配、贡献流程和公开 GitHub Release。
+
+宏大愿景被拆成连续可验证的版本；每个阶段都必须留下一个真正可运行、可测试的系统。

package/docs/plans/2026-09-02-self-organizing-skills-implementation.md

@@ -0,0 +1,136 @@
+# Self-Organizing Skill System Implementation Plan
+
+> This plan turns the accepted architecture into small, test-first milestones. Each task ends in a runnable check and a focused commit.
+
+**Goal:** Publish an English-first, Chinese-localized, Codex-compatible repository that classifies, catalogs, composes, evaluates, and safely evolves atomic Agent Skills, with 300+ attributed Skill/MCP entries and a Pi-backed evaluation path.
+
+**Architecture:** The repository root is a Codex plugin. `skill-src` is the canonical template/contract source; deterministic projections target both the plugin-required `skills` directory and the Codex project-native `.agents/skills` directory. YAML contracts feed a generated registry and category indexes. A TypeScript CLI provides validation, routing, cataloging, evaluation, training proposals, and harness adapters.
+
+**Technology:** Node.js 24, TypeScript, npm, Vitest, YAML, JSON Schema/Ajv, Commander, Pi coding-agent package, GitHub Actions.
+
+---
+
+## Task 1: Bootstrap the repository and public contracts
+
+**Files:** `package.json`, `pnpm-lock.yaml`, `tsconfig.json`, `vitest.config.ts`, `.gitignore`, `.codex-plugin/plugin.json`, `schemas/*.schema.json`, `src/types.ts`, `tests/schemas.test.ts`
+
+1. Write failing schema tests for valid/invalid skill contracts, catalog records, taxonomy nodes, packs, datasets, and evaluation runs.
+2. Add pinned runtime and development dependencies.
+3. Implement schemas and shared TypeScript types.
+4. Add the plugin manifest pointing to `.agents/skills`.
+5. Run `pnpm test -- tests/schemas.test.ts` and plugin validation.
+6. Commit `feat: bootstrap contracts and plugin manifest`.
+
+## Task 2: Implement taxonomy and deterministic two-stage routing
+
+**Files:** `taxonomy/taxonomy.yaml`, `taxonomy/classification-standard.md`, `src/registry.ts`, `src/router.ts`, `src/cli.ts`, `tests/router.test.ts`, `evals/datasets/routing-bootstrap.yaml`
+
+1. Write failing tests for category boundaries, positive/negative triggers, multilingual prompts, ambiguity, and top-k traces.
+2. Implement taxonomy loading and validation.
+3. Implement weighted category and atom ranking with negative-boundary penalties.
+4. Return an explainable route trace including scores and matched contract fields.
+5. Add `skillpack route`, `skillpack validate`, and `skillpack taxonomy lint` commands.
+6. Run focused tests and typecheck.
+7. Commit `feat: add explainable two-stage router`.
+
+## Task 3: Create Category, Atomic, and Meta Skills
+
+**Files:** `skill-src/category-*`, `skill-src/atom-*`, `skill-src/meta-skill-governor`, `skills/*`, `.agents/skills/*`, `scripts/generate-skill-projections.ts`, `tests/skill-layout.test.ts`
+
+1. Write failing layout tests using Codex/Agent Skills naming and frontmatter rules.
+2. Create ten category Skills with localized indexes and boundary references.
+3. Create a small representative atom set spanning read-only, artifact creation, verification, and governed mutation.
+4. Create the meta Skill with proposal, evaluation, promotion, deprecation, and rollback procedures.
+5. Generate category indexes and both compatibility projections from `skill.contract.yaml`; fail on staleness or divergence.
+6. Validate every Skill with the Codex skill validator.
+7. Commit `feat: add category atom and meta skills`.
+
+## Task 4: Build the 300+ source catalog
+
+**Files:** `catalog/sources.yaml`, `catalog/entries/*.yaml`, `src/catalog/*`, `tests/catalog.test.ts`, `docs/catalog-methodology.md`, `docs/zh-CN/catalog-methodology.md`
+
+1. Write failing tests for provenance, immutable references, licenses, freshness, duplicate IDs, and minimum entry count.
+2. Implement GitHub repository metadata collection without executing upstream code.
+3. Implement importers for Agent Skills repositories, MCP registry/server lists, and plugin manifests.
+4. Curate official and leading community source definitions.
+5. Normalize at least 300 unique entries with source URLs, revisions, paths, types, summaries, licenses, and verification timestamps.
+6. Compute contract fingerprints and near-duplicate clusters.
+7. Run catalog validation and inspect a random sample.
+8. Commit `feat: add attributed 300 capability catalog`.
+
+## Task 5: Add capability packs and deduplication workflow
+
+**Files:** `packs/*.yaml`, `src/packs.ts`, `src/deduplicate.ts`, `tests/packs.test.ts`, `tests/deduplicate.test.ts`
+
+1. Write failing tests for dependency resolution, cycles, missing atoms/MCPs, permissions, and duplicate thresholds.
+2. Implement pack resolution over stable capability IDs.
+3. Implement contract-fingerprint clustering with explainable similarity components.
+4. Add starter packs for software delivery, deep research, document production, and skill governance.
+5. Commit `feat: compose capability packs and duplicate clusters`.
+
+## Task 6: Implement the evaluation engine
+
+**Files:** `src/eval/*`, `evals/datasets/*`, `evals/baselines/*`, `tests/eval.test.ts`
+
+1. Write failing metric tests for category hit@k, atom hit@k, MRR, non-invocation, completion, safety, cost, and latency.
+2. Implement deterministic dataset loading and split protection.
+3. Implement metric aggregation without collapsing protected metrics into one score.
+4. Implement configurable release gates and regression comparisons.
+5. Create independent English, Chinese, ambiguous, adversarial, and task-completion datasets.
+6. Add `skillpack eval` and `skillpack gate`.
+7. Commit `feat: add multi-suite evaluation gates`.
+
+## Task 7: Add harness adapters and Pi evaluation
+
+**Files:** `src/harness/types.ts`, `src/harness/mock.ts`, `src/harness/pi.ts`, `src/harness/dsh.ts`, `src/harness/codex.ts`, `tests/harness.test.ts`, `docs/harnesses.md`
+
+1. Write adapter contract tests using the mock harness.
+2. Implement capability discovery, health checks, route traces, and execution traces.
+3. Pin the maintained Pi package and implement structured execution behind an opt-in environment check.
+4. Implement a DSH adapter stub that reports precise installation/version requirements until its pinned CLI is present.
+5. Add Codex native-layout validation and trace import.
+6. Run offline tests, then a real Pi smoke evaluation if provider credentials/configuration are available.
+7. Commit `feat: evaluate skills through harness adapters`.
+
+## Task 8: Add governed self-optimization
+
+**Files:** `src/train/*`, `.skill-system/proposals/`, `.skill-system/decisions/`, `tests/trainer.test.ts`, `docs/evolution-policy.md`, `docs/zh-CN/evolution-policy.md`
+
+1. Write failing tests proving train/test isolation, bounded diffs, permission expansion rejection, self-gate protection, and rollback.
+2. Implement observation and failure clustering.
+3. Generate bounded candidate patches to descriptions, triggers, boundaries, or taxonomy mappings.
+4. Evaluate candidates in an isolated worktree/directory without modifying the active registry.
+5. Persist signed-off decision records and promotion/rollback pointers.
+6. Add `skillpack train propose`, `skillpack train evaluate`, `skillpack promote`, and `skillpack rollback`.
+7. Commit `feat: add evidence-gated skill evolution`.
+
+## Task 9: Documentation, security, and CI
+
+**Files:** `README.md`, `README.zh-CN.md`, `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE`, `.github/workflows/ci.yml`, `.github/ISSUE_TEMPLATE/*`, `docs/*`
+
+1. Document the mental model, quick start, architecture, classification rules, contribution path, catalog caveats, metrics, and roadmap in English and Chinese.
+2. Add threat model, upstream trust levels, reporting policy, and safe ingestion rules.
+3. Add CI for formatting, typecheck, unit/integration tests, Skill/plugin validation, generated-index drift, catalog provenance, and minimum 300 entries.
+4. Add release and changelog conventions.
+5. Run the complete local verification matrix.
+6. Commit `docs: prepare public bilingual release`.
+
+## Task 10: Publish the GitHub repository
+
+1. Verify the final diff, license attribution, secrets scan, and clean test run.
+2. Create the public GitHub repository `skillpack-one` under the authenticated user, with issues enabled.
+3. Push `main`, add repository topics, and verify rendered READMEs and CI.
+4. Create an initial prerelease only after CI passes.
+5. Record the published URL and exact verified revision.
+
+## Definition of done
+
+- Codex discovers the repository Skills natively and the plugin validates.
+- The deterministic router explains category and atom choices in English and Chinese tests.
+- The normalized, attributed catalog contains at least 300 unique Skill/MCP entries.
+- Category indexes are generated from contracts and current.
+- Multiple independent suites report routing and completion separately.
+- Pi-backed smoke evaluation runs when credentials are present; offline CI remains deterministic without them.
+- Self-optimization cannot bypass held-out, safety, permission, or rollback gates.
+- English and Chinese documentation are complete enough for independent adoption.
+- The public GitHub repository and CI are accessible.

package/docs/plans/2026-09-02-wikiskill-skill-state-integration.md

@@ -0,0 +1,28 @@
+# WikiSkill and SKILL.state integration design
+
+## Preserved architecture
+
+- Categories route needs.
+- Atomic Skills own one bounded outcome.
+- Capability Packs compose stable Skill IDs and may optionally declare execution mechanics.
+- Meta Skills govern evidence, proposals, promotion, deprecation, and rollback.
+
+## Change A: persistent Evolution Knowledge
+
+Create a non-executable pattern registry between immutable run evidence and active Skills. Patterns are scoped, evidence-backed, searchable, and supersedable. Proposals may cite pattern IDs. Ordinary inference cannot read this layer.
+
+## Change B: bounded current execution state
+
+Allow a Capability Pack to opt into a pack-specific JSON Schema, initial state, JSON Merge Patch, and external audit-log policy. Validate current and candidate state before returning a transition. Start with `safe-skill-evolution` rather than making an untested global runtime change.
+
+## Rejected shortcuts
+
+- No fifth Skill kind, universal state schema, global transcript deletion, automatic Skill activation, or model-authored self-approval.
+- No claim of live token savings until a pinned harness/model runs matched long-horizon tests.
+
+## Verification
+
+- Schema and graph tests for knowledge records and proposal references.
+- State initialization, merge preservation, invalid-patch rejection, and prototype-pollution tests.
+- Capability Pack compilation includes the optional state profile.
+- Full routing, projection, plugin, packaging, security, and governance gates remain green.

package/docs/plans/2026-09-03-npm-publishing-design.md

@@ -0,0 +1,34 @@
+# npm publishing design
+
+## Goal
+
+Publish `skillpack-one` from reviewed GitHub releases without storing a long-lived npm write token, while preserving the repository's existing CI and Meta Skill release gates.
+
+## Decision
+
+Use a dedicated `publish-npm.yml` GitHub Actions workflow triggered by a published GitHub Release. The job runs on a GitHub-hosted runner, checks that the release tag exactly equals `v<package.json version>`, checks that the tagged commit belongs to `main`, verifies GitHub's prerelease flag against SemVer, runs the complete repository CI, and publishes through npm Trusted Publishing (OIDC). A GitHub Environment named `npm` supplies the human deployment-approval boundary. Pre-release versions publish under the `next` dist-tag; stable versions publish under `latest`.
+
+The package is currently absent from npm. npm only permits Trusted Publisher configuration after the package exists, so the first pre-release is a one-time 2FA-authenticated bootstrap publish. After that publish, the maintainer binds `WnagoiYy/skillpack-one`, workflow `publish-npm.yml`, and environment `npm` as the package's trusted publisher, tests one automated release, then disables token-based publishing.
+
+## Alternatives considered
+
+1. **Recommended: GitHub Release plus OIDC direct publish.** It has no persistent npm secret, preserves provenance, and is understandable to contributors. GitHub Environment approval and protected release tags provide the human gate.
+2. **OIDC staged publishing.** This adds a second npm-side 2FA approval after CI. It is the strongest option and remains documented as a future hardening profile, but adds operational steps while the project is an alpha.
+3. **Repository `NPM_TOKEN`.** This bootstraps easily but creates a long-lived write credential and weaker supply-chain posture. It is not included in the permanent workflow.
+
+## Release invariants
+
+- `package.json` contains the exact public GitHub repository URL required for npm provenance.
+- A GitHub Release tag must exactly match `v<version>`.
+- SemVer pre-releases must be marked as GitHub pre-releases and use npm tag `next`.
+- Stable SemVer releases must not be marked pre-release and use npm tag `latest`.
+- The release commit must be reachable from `origin/main`.
+- `npm run ci` and a package dry run must pass before publishing.
+- The publish job has only `contents: read` and `id-token: write` permissions.
+- Release builds disable package-manager caching and install dependencies with lifecycle scripts disabled.
+- npm versions are immutable. Recovery uses deprecation, dist-tag rollback, and a corrective version rather than overwriting a release.
+
+## Trust boundaries
+
+The workflow establishes artifact origin, build revision, and publish identity; it does not prove semantic safety. Pull-request review, the project's evolution proposal, held-out evaluation, GitHub Environment approval, npm OIDC configuration, and runtime permissions remain separate controls. npm provenance links the package to this public repository and workflow, but is not a malware guarantee.
+

package/docs/plans/2026-09-03-npm-publishing.md

@@ -0,0 +1,69 @@
+# npm Publishing Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a tokenless, release-gated npm publishing workflow for `skillpack-one` and document the unavoidable first-publish bootstrap.
+
+**Architecture:** A small TypeScript release planner validates package metadata, release tag, prerelease state, repository identity, and npm dist-tag selection. A pinned GitHub Actions workflow consumes that planner, runs the existing CI, and publishes through npm OIDC only after the `npm` deployment environment approves the job.
+
+**Tech Stack:** TypeScript 7, Vitest, npm 11, GitHub Actions, npm Trusted Publishing/OIDC.
+
+---
+
+### Task 1: Specify release-plan invariants
+
+**Files:**
+- Create: `tests/release.test.ts`
+- Create: `src/release.ts`
+
+1. Write tests for an alpha release selecting `next`, a stable release selecting `latest`, tag mismatch, GitHub prerelease mismatch, invalid SemVer, and repository mismatch.
+2. Run `npm test -- tests/release.test.ts` and verify it fails because the module is absent.
+3. Implement a pure `planNpmRelease` function with explicit inputs and deterministic errors.
+4. Run the focused test and verify it passes.
+
+### Task 2: Add the workflow-facing release command
+
+**Files:**
+- Create: `scripts/prepare-npm-release.ts`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+
+1. Add a `release:plan` script that reads `package.json`, validates two command arguments and `GITHUB_REPOSITORY`, prints the plan, and writes safe values to `GITHUB_OUTPUT` when available.
+2. Add the exact repository, homepage, bugs, keywords, public registry, package manager, and `0.1.0-alpha.10` version metadata.
+3. Run the command with matching and mismatching inputs to verify success and fail-closed behavior.
+
+### Task 3: Add tokenless GitHub publishing
+
+**Files:**
+- Create: `.github/workflows/publish-npm.yml`
+
+1. Trigger only on a published GitHub Release.
+2. Pin checkout and setup-node actions, use Node 24 and npm 11.19.1, disable release-job caching, and grant only `contents: read` plus `id-token: write`.
+3. Check out the release tag with full history and reject commits not reachable from `origin/main`.
+4. Install with `npm ci --ignore-scripts`, execute `npm run ci`, validate release metadata, inspect `npm pack --dry-run`, and run `npm publish --access public --tag <next|latest>` without `NODE_AUTH_TOKEN`.
+5. Bind the job to the `npm` GitHub Environment and disable concurrent publication of the same release.
+
+### Task 4: Document setup, operation, and rollback
+
+**Files:**
+- Create: `docs/npm-release.md`
+- Create: `docs/zh-CN/npm-release.md`
+- Modify: `README.md`
+- Modify: `README.zh-CN.md`
+- Modify: `CHANGELOG.md`
+
+1. Document the one-time 2FA bootstrap because npm requires the package to exist before OIDC trust can be configured.
+2. Document the exact `npm trust github` command, GitHub Environment configuration, release checklist, `next`/`latest` behavior, verification, and recovery.
+3. Link the guide from both READMEs and record the change under `Unreleased`.
+
+### Task 5: Verify the release candidate
+
+**Files:**
+- Verify all files above.
+
+1. Run the focused release tests.
+2. Run `npm run ci`.
+3. Run `npm run release:plan -- v0.1.0-alpha.10 true` with `GITHUB_REPOSITORY=WnagoiYy/skillpack-one`.
+4. Run `npm pack --dry-run --json` and confirm the package name, version, CLI, documentation, and absence of temporary files.
+5. Run `git diff --check` and inspect the final diff without publishing, tagging, or changing npm account state.
+

package/docs/release-policy.md

@@ -0,0 +1,5 @@
+# Release policy
+
+Releases use Semantic Versioning. Research-stage builds use `vMAJOR.MINOR.PATCH-alpha.N` and remain GitHub prereleases until live task-completion evidence is certified.
+
+A release requires a clean worktree, exact local/remote revision match, warning-free GitHub Actions on that revision, passing independent routing gates, current generated projections, official Skill/plugin validation, a dependency and secret scan, attribution checks, and an immutable annotated tag. Published tags are never moved; a correction receives a new prerelease number. The changelog records user-visible behavior and known evidence limits.

package/docs/research/2026-09-02-agent-skill-literature.md

@@ -0,0 +1,57 @@
+# Agent Skill literature: evidence and decisions
+
+Date: 2026-09-02  
+Scope: Agent Skill structure, retrieval, composition, evaluation, security, and governed evolution.
+
+This note records evidence used to evolve SkillPack One. It is not a claim that every cited method generalizes to every agent harness. Peer-reviewed work, accepted papers, preprints, and project results are identified by their source rather than blended into one confidence level.
+
+## Requested article sources
+
+The WeChat page itself was inaccessible, but the user clarified that it discusses [WikiSkill](https://arxiv.org/pdf/2608.27454) and [SKILL.state](https://arxiv.org/pdf/2608.26263). Both official arXiv PDFs were read in full and checked through their architecture figures, result tables, ablations, appendices, prompts, and limitations. Their detailed mapping is recorded in [WikiSkill and SKILL.state: implications for SkillPack One](2026-09-02-wikiskill-skill-state.md).
+
+## Evidence-to-decision matrix
+
+| Evidence | What it supports | SkillPack One decision |
+| --- | --- | --- |
+| [WikiSkill](https://arxiv.org/pdf/2608.27454) separates immutable traces, persistent consolidated patterns and impact logs, and reversible active Skills. Its ablation favors giving the proposer—but not ordinary inference—access to the wiki. | Experience should compound across iterations without becoming hidden task-solving context or directly activating generated Skills. | Add non-executable Evolution Knowledge with scoped evidence, search, supersession, and proposal references. Preserve rejected interventions as evidence and keep the layer out of ordinary task execution. |
+| [SKILL.state](https://arxiv.org/pdf/2608.26263) executes long procedures from an immutable specification, bounded current state, and latest observation, validating each state patch while keeping history out of the active prompt. | Long tasks need an explicit current-state contract; arbitrary transcript truncation is not a safe substitute. | Add optional pack-specific runtime-state profiles with JSON Schema, validated JSON Merge Patch, and a separate audit-log policy. Do not force state mode when history is itself the task or the sufficient-state assumption fails. |
+| [SkillsBench](https://arxiv.org/abs/2602.12670) evaluates tasks with no Skills, curated Skills, and self-generated Skills. Its first release reports strong average lift from curated Skills, negative deltas on some tasks, negligible average benefit from self-generated Skills, and better results from focused packages than comprehensive documentation. | Existence, routing accuracy, or fluent generation does not prove that a Skill helps. | Add paired without-Skill/with-Skill effect results. Synthetic runs may test the protocol but cannot certify lift. Preserve small Atomic Skills and require a positive completion or rubric lift for admission evidence. |
+| [Skill-Inject](https://arxiv.org/abs/2602.20156) treats Skill files as an agent supply-chain attack surface and reports high attack success in its benchmark. | Community text and scripts are untrusted even when a package appears useful. Simple filtering or stronger models are not an authorization boundary. | Keep catalog entries non-executable; review prompt injection, provenance, scripts, and permission envelopes before activation; separate the generating identity from the approver. |
+| [Compositional Skill Routing](https://arxiv.org/abs/2606.18051) frames complex requests as decompose → retrieve → compose and finds decomposition granularity to be a major bottleneck over a large MCP-derived library. | Top-1 Skill retrieval is insufficient for multi-step tasks. Decomposition must know the available atomic boundaries. | Compile existing Capability Packs into dependency-aware stages and recommend them from multiple routed Atom/Meta signals. Do not invent a new monolithic Skill or free-form execution graph. |
+| [Generative Skill Composition](https://arxiv.org/abs/2606.32025) treats subset, count, and execution order as one structured decision. | Composition is more than returning top-k independent Skills. | A pack plan explicitly records the selected stable IDs, count, partial order, stages, and acceptance tests. A future learned composer must emit the same constrained plan shape. |
+| [ToolScope](https://aclanthology.org/2026.acl-long.1573/) reports that overlapping tools hurt selection and that merging/filtering can improve tool selection. | Redundancy consumes context and creates ambiguity. | Keep duplicate clustering as a review queue; merge contracts only after outcome and failure-boundary review. Similarity never authorizes deletion. |
+| [PORTS](https://aclanthology.org/2025.emnlp-main.507/) aligns tool retrieval with downstream tool-use performance rather than documentation similarity alone. | A retriever should optimize usefulness, not lexical resemblance. | Retain explainable lexical routing as the portable baseline, but evaluate any future semantic retriever against downstream Skill effect and protected safety metrics. |
+| [CoEvoSkills](https://arxiv.org/abs/2604.01687) separates an iterative Skill generator from a verifier that does not see ground-truth test content. | A generator must not grade itself on the evidence it optimized against. | Record authorship/generator identity, require independent promotion review, and preserve held-out/adversarial data outside the candidate diff. |
+| [SkillX](https://arxiv.org/abs/2604.04804), [AutoSkill](https://arxiv.org/abs/2603.01145), and [Voyager](https://arxiv.org/abs/2305.16291) show different ways to distill trajectories, retain reusable experience, use curriculum, and refine skills from execution feedback. | Experience can seed reusable capabilities without changing model weights, but automatic accumulation can also preserve noise and duplicate behavior. | Treat traces as observations for bounded proposals. Map strategic plans to Capability Packs, functional groupings to Categories, and reusable execution units to Atoms. Never let a trace write directly into active projections. |
+| [SkillRet](https://arxiv.org/abs/2605.05726) evaluates long Skill documents at realistic catalog scale, removes functional-equivalence false negatives, and reports Recall and strict Completeness for multi-Skill queries. Its own end-to-end result also shows that better retrieval scores do not automatically produce higher task success. | Any-of Hit@K hides incomplete compositions and capability-equivalent alternatives can corrupt both evaluation and hard-negative training. | Add equivalence-aware Atom Recall and Full Coverage beside Hit@K/MRR. Keep downstream paired Skill effect as the promotion objective. |
+| [How Well Do Agentic Skills Work in the Wild](https://arxiv.org/abs/2604.04323) separates forced loading, autonomous selection, distractors, retrieval, adaptation, and no-Skill conditions. Utility degrades as conditions become realistic, and query-specific refinement helps mainly when initial Skill coverage is already adequate. | Availability, retrieval, loading, use, and task benefit are different events. Refinement multiplies useful evidence; it cannot manufacture absent capability reliably. | Define progressive realism profiles for future live evaluation and never promote refinement from retrieval metrics alone. Keep task-specific synthesis quarantined as an ephemeral candidate until task verification. |
+| [Agent Skill Security](https://arxiv.org/abs/2607.13987) models distinct trust boundaries at authoring, storage, retrieval, selection, execution, and evolution. Its controlled evaluation also leaves residual attacks and false positives after proposed defenses. | No single scanner or LLM judge secures the Skill lifecycle. An update must re-enter admission, while runtime authorization remains independent of metadata review. | Add a six-stage lifecycle security review artifact. Require stage-specific evidence and residual-risk reporting; do not equate a passing semantic review with safe execution. |
+| [SkillNet](https://arxiv.org/abs/2603.04448) separates taxonomy, typed Skill relations, and packaged collections, and evaluates safety, completeness, executability, maintainability, and cost awareness. Its limitations acknowledge incomplete coverage and unresolved poisoned contributions. | A directory tree alone cannot express substitutability, composition, packaging, and dependency, while a relation graph must not become unreviewed authority. | Materialize only relations supported by contracts and reviewed packs. Preserve the project taxonomy as the routing skeleton and keep inferred relations as candidates until reviewed. |
+| [SkillRouter](https://arxiv.org/abs/2603.22455) finds that full Skill bodies contain routing signal absent from raw names and descriptions, and that false-negative filtering plus listwise reranking matter in overlapping libraries. Its core benchmark is small and downstream gains are limited to the studied setting. | Progressive disclosure should not imply metadata-only offline retrieval. Functionally close distractors need explicit tests and body-derived features may be used without injecting every body into the live prompt. | Keep runtime disclosure narrow, but permit optional offline body-aware indexing and reranking behind the common RouteTrace contract. Add same-domain functional distractors to development evaluation. |
+| [SkillOpt](https://arxiv.org/abs/2605.23904) uses bounded add/delete/replace edits, strict selection-split improvement, rejected-edit feedback, and optimizer-only slow/meta state to train compact Skills. | Self-improvement should be a versioned propose-and-test loop; ties, plausible reflections, and full rewrites are not sufficient evidence. | Add bounded evolution-attempt records with strict improvement and protected-regression checks. Preserve rejected edits as evidence and keep optimizer memory out of deployed Atomic Skills. |
+
+## Adopt now
+
+1. `skillpack compose <request>` recommends only reviewed Capability Packs and compiles their declared ordering into deterministic stages.
+2. `skillpack harness effect <without.json> <with.json>` measures paired Skill lift under the same dataset and harness identity. Synthetic evidence is explicitly non-certifying.
+3. New evolution proposals record `human`, `model-assisted`, or `model-generated` authorship. Human-only proposals require a reviewer other than the author; model-assisted/generated proposals cannot be approved by the generating model.
+4. Community intake explicitly treats all upstream instructions, resources, and scripts as untrusted data until provenance, injection, permission, and execution review pass.
+5. Evolution Knowledge separates raw runs, consolidated cross-iteration patterns, and active Skills; proposals may cite pattern IDs, but normal inference cannot read the pattern layer.
+6. Capability Packs may opt into a validated current-state profile while retaining full audit history out of band.
+
+## Defer behind evidence
+
+- Semantic or learned retrieval: adopt only after it beats the deterministic baseline on held-out routing, paired task effect, cost, and latency without a safety regression.
+- Iterative skill-aware decomposition: add after a protected compositional dataset exists; do not optimize against its test split.
+- Automatic trace-to-Skill generation: keep proposals quarantined until an independent verifier and live task baselines exist.
+- Model-weight reinforcement learning: useful in research such as skill-augmented RL, but outside the portable package core.
+- Autonomous trace consolidation and proposal generation, live state-loop harness integration, multi-agent state merge, and constrained decoding: defer until protected long-horizon suites and live evidence exist.
+
+## Reject as a change of project identity
+
+- Replacing Category → Atom → Capability Pack → Meta governance with a paper-specific ontology.
+- Installing or executing the full upstream catalog.
+- Treating a high similarity score as proof of equivalence or authorization to delete.
+- Letting a generated Skill, its generator, or one aggregate score certify promotion.
+
+The stopping rule for this review was evidence convergence: additional papers repeated the same themes—focused procedural modules, constrained retrieval/composition, downstream evaluation, independent verification, and supply-chain authorization—without changing the selected incremental design.

package/docs/research/2026-09-02-retrieval-security-optimization.md

@@ -0,0 +1,41 @@
+# Retrieval, lifecycle security, and bounded optimization
+
+Date: 2026-09-02  
+Status: evidence review for a candidate implementation; most cited work is a 2026 preprint.
+
+## Research question
+
+Which mechanisms from recent Agent Skill research improve SkillPack One without replacing its portable Category -> Atom -> Capability Pack -> Meta architecture or making a learned model mandatory?
+
+## Sources inspected
+
+- [SkillRet](https://arxiv.org/pdf/2605.05726): benchmark construction, functional-equivalence audit, taxonomy, retrieval metrics, end-to-end study, appendices, and limitations.
+- [How Well Do Agentic Skills Work in the Wild](https://arxiv.org/pdf/2604.04323): collection/search design, progressive settings, refinement experiments, prompts, and conclusion.
+- [Agent Skill Security](https://arxiv.org/pdf/2607.13987): threat taxonomy, trust boundaries, experimental configurations, results, and limitations.
+- [SkillNet](https://arxiv.org/pdf/2603.04448): ontology, curation, five-dimensional evaluation, relation graph, composition study, failure analysis, and limitations.
+- [SkillRouter](https://arxiv.org/pdf/2603.22455): body-access controls, benchmark construction, hard negatives, false-negative filtering, listwise reranking, downstream results, and limitations.
+- [SkillOpt](https://arxiv.org/pdf/2605.23904): problem formulation, bounded optimizer, validation gate, rejected buffer, slow/meta update, transfer study, ablations, and conclusion.
+
+## Evidence-to-mechanism map
+
+| Observed gap | Evidence | Candidate mechanism | Non-claim |
+| --- | --- | --- | --- |
+| Multi-Atom evaluation rewards finding any one expected Atom. | SkillRet and SkillRouter distinguish Recall from strict full-set coverage and audit functional substitutes. | Equivalence-aware Atom Recall@3 and Full Coverage@3, plus same-domain hard distractors. | These deterministic metrics do not prove task success. |
+| Progressive disclosure can become metadata-only retrieval. | SkillRouter and the in-the-wild study report additional signal from full Skill content. | Optional offline body-aware index/reranker that emits the existing explainable trace format. | Do not inject the whole catalog into the live prompt or require a model backend. |
+| Security is described mainly at intake and execution. | Agent Skill Security identifies independent lifecycle trust boundaries and residual failures after every defense. | Six-stage review artifact with per-stage evidence and residual risk; every update re-enters admission. | A passed semantic review is not runtime authorization or information-flow proof. |
+| Skill relationships are implicit across contracts and packs. | SkillNet separates taxonomy, typed relations, and packages. | Deterministically materialize reviewed `confusable-with`, `compose-with`, `depends-on`, and `packaged-in` edges. | Inferred similarity never authorizes deletion, execution, or promotion. |
+| Proposal scope is bounded, but optimizer steps are not first-class evidence. | SkillOpt's strongest controls are strict validation, bounded edits, rejected feedback, and optimizer-only meta state. | Append-only evolution attempts with edit budget, strict improvement, protected regression checks, and rejected evidence. | This is a control protocol, not a reproduced SkillOpt model experiment. |
+| Idealized Skill tests hide selection and adaptation failures. | The in-the-wild study separates forced load, autonomous selection, distractors, retrieval, adaptation, and no-Skill. | Future live runs record a realism profile and stage-specific availability/selection/loading/use signals. | The current Mock Harness cannot certify these stages. |
+
+## Adoption boundary
+
+The candidate implements deterministic schemas, gates, metrics, and typed artifacts. It does not ship a learned retriever, execute downloaded Skills, create model-generated labels for protected tests, or report the cited papers' benchmark gains as SkillPack One results. Promotion still requires independent review and live paired Skill-effect evidence where a claim concerns task utility.
+
+## Evaluation requirements
+
+1. Existing protected multilingual and adversarial metrics cannot regress.
+2. New compositional metrics remain separate; no aggregate may hide partial coverage.
+3. Lifecycle security stages fail closed when applicable evidence is missing.
+4. Evolution ties are rejected and rejected attempts remain immutable evidence.
+5. A learned retrieval backend must later report catalog scale, Recall/Full Coverage, downstream paired effect, latency, cost, and attack robustness against the deterministic baseline.
+