skillpack-one 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 WnagoiYy
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,176 @@
+# SkillPack One
+
+[简体中文](README.zh-CN.md) · **Research-grade alpha**
+
+> **The SkillPack is all you need.**
+>
+> Install one pack. Let it find, combine, and improve the skills you need.
+
+SkillPack One packages the **Self-Organizing Skill System**: a Codex-compatible architecture for atomic, composable, evaluated, and safely self-improving Agent Skills.
+
+"One pack" means one installation and governance entry point—not one giant prompt and not a claim that every possible capability is already bundled. Progressive disclosure keeps the catalog broad while loading only the Category and Atomic Skills required for the current task.
+
+It turns a growing Skill/MCP ecosystem into four deliberately separate layers:
+
+```mermaid
+flowchart LR
+    R[User request] --> C[Category Skill]
+    C --> A[Smallest atomic Skills]
+    A --> P[Capability pack / task]
+    U[658-entry upstream catalog] -. evidence only .-> C
+    M[Meta Skill governor] --> C
+    M --> A
+    M --> P
+    E[Held-out evaluation] --> M
+```
+
+The project does **not** install every discovered capability. The upstream catalog is evidence for classification and decomposition; only reviewed local contracts become executable Skills.
+
+## What is included
+
+| Layer | Current snapshot | Purpose |
+| --- | ---: | --- |
+| Category Skills | 10 | First-stage, needs-driven routing and boundary decisions |
+| Atomic Skills | 11 | Small, independently testable capability contracts |
+| Meta Skills | 1 | Proposal, evaluation, promotion, deprecation, and rollback governance |
+| Capability packs | 4 | Validated compositions without merging atomic contracts |
+| Upstream records | 658 | 388 Agent Skills + 270 official MCP Registry servers |
+| Candidate duplicate clusters | 8 | Human-review queue; originals remain intact |
+
+Every category projection carries an English fallback `index.md` plus `index.en.md`, `index.zh-CN.md`, and generic `index.zh.md` variants. English `SKILL.md` remains the portable discovery contract, while localized indexes preserve language-specific terminology and routing habits.
+
+## Core ideas
+
+- **Needs before tools.** Classify the requested outcome, artifact, operation, and constraints before selecting a product or protocol.
+- **One primary capability per atom.** Stable capability IDs and explicit inputs, outputs, side effects, permissions, non-goals, and tests make overlap measurable.
+- **Compose explicitly.** Multi-step requests select reviewed Capability Packs whose stable Skill subset, count, dependency order, and acceptance tests compile into an explainable DAG.
+- **Bound current state where safe.** Long-running packs may opt into a schema-validated current-state profile while keeping immutable audit history outside the active prompt. Transcript mode remains valid when history cannot be safely summarized as state.
+- **Progressive disclosure.** Codex sees compact Skill metadata first, then a category index, then only the necessary atomic instructions.
+- **Typed relations, not an ungoverned graph.** Reviewed contracts and packs materialize `confusable-with`, `compose-with`, `depends-on`, and `packaged-in` edges. Similarity may suggest review, but cannot authorize installation, merging, execution, or deletion.
+- **Plugin architecture.** The repository is a plugin bundle with a manifest, generated `skills/` projection, project-native `.agents/skills/` projection, schemas, packs, and evaluation assets.
+- **Evidence-gated evolution.** A meta Skill may propose its own changes, but cannot weaken its gate in the same proposal. Held-out datasets, permission review, immutable decisions, and rollback pointers remain outside the optimization target.
+- **Lifecycle security.** Authoring, storage, retrieval, selection, execution, and evolution are separate trust boundaries. Passing one stage never substitutes for evidence at another.
+- **Persistent evolution knowledge.** Raw runs, consolidated patterns, and active Skills remain separate. Meta governance may reuse indexed evidence across iterations, while normal task execution sees only promoted Skills.
+- **Catalog is not trust.** Collection never executes upstream code. Unknown-license entries are metadata only; installation requires a separate security review.
+- **Skill lift, not Skill presence.** A Skill is useful only when a matched with-Skill run improves over the no-Skill baseline without protected regressions; synthetic protocol tests cannot certify that claim.
+
+The design follows the current [OpenAI Agent Skills guidance](https://learn.chatgpt.com/docs/build-skills), [Codex plugin model](https://learn.chatgpt.com/docs/build-plugins), and the [official MCP Registry API](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/official-registry-api.md).
+
+## The philosophy: one pack, many valid implementations
+
+SkillPack One is a reference implementation of a general design philosophy. An individual, community, or organization may choose a different taxonomy, directory layout, evaluation harness, or Meta Skill topology while remaining compatible with the same foundation:
+
+1. **One shared description standard.** Every Skill is a directory with a portable `SKILL.md` containing a discriminating `name` and `description`. This repository additionally requires every first-party Category, Atomic, and Meta Skill to carry the same machine-readable `skill.contract.yaml`: inputs, outputs, outcome, artifacts, boundaries, permissions, side effects, provenance, routing signals, and evaluations.
+2. **Categories index Skills progressively.** A request first selects a Category Skill, then reads that category's `index.md` or locale-specific index, and only then loads the selected Atom. Category trees should stay shallow: no more than three Category levels is recommended—broad domain → subdomain → specific category → Atomic Skill. The Atom is the leaf and is not counted as a Category level. This implementation keeps executable Skill directories flat for Codex discovery while representing hierarchy through taxonomy parents and generated indexes; another host may use physical nested directories.
+3. **Every Skill may be generated, trained, and evolved.** A Skill may be authored by a person, recorded from a workflow, or drafted with `@skill-creator` in ChatGPT and `$skill-creator` in Codex. Here, "training" means improving descriptions, contracts, instructions, and compositions against versioned routing and task suites—not silently changing model weights. Meta Skills govern proposals, evaluation, promotion, deprecation, and rollback. They may govern the whole pack, one Category subtree, or one specific Skill, including themselves under the same gate.
+4. **Atoms have explicit responsibility boundaries.** An Atomic Skill owns one primary outcome, one dominant artifact or state transition, one permission envelope, one focused rubric, and an independently useful failure boundary. Broad end-to-end workflows belong in capability packs that compose atoms without merging them.
+5. **The foundation is shared; the taxonomy is not universal.** Different maintainers may split industries, functions, modalities, and risk domains differently. Conformance comes from portable descriptions, explicit boundaries, progressive indexes, evidence, and governed evolution—not from copying this repository's ten top-level categories.
+
+See the [classification standard](taxonomy/classification-standard.md), [evaluation policy](docs/evaluation.md), and [evolution policy](docs/evolution-policy.md) for this implementation's concrete profile.
+
+## Community and model contributions
+
+Communities and models may propose new Skills or improvements, but generation is not approval. Each contribution follows the same admission path:
+
+1. Submit provenance, license state, the shared contract, localized routing examples, permissions, and evaluation cases.
+2. Use model-assisted classification and similarity analysis to choose the narrowest category, extract the atomic responsibility, and identify overlap with existing Skills.
+3. Review security, authority, provenance, and duplicate candidates. A generating model must not be the sole approver of its own change; use an independent reviewer, a maintainer, or both according to risk.
+4. Regenerate parent/child indexes and run development, held-out, multilingual, adversarial, and task-completion suites as applicable.
+5. Promote only through an append-only decision with a rollback pointer. Merge with an existing Atom, reject, or deprecate when a proposal adds wording but no distinct reusable capability.
+
+This keeps community growth additive in useful capability rather than additive in duplicated context. See [CONTRIBUTING.md](CONTRIBUTING.md) for the review checklist.
+
+## Quick start
+
+Requirements: Node.js 24 or newer and Git.
+
+```sh
+git clone https://github.com/WnagoiYy/skillpack-one.git
+cd skillpack-one
+npm ci
+npm run ci
+```
+
+Try the explainable router:
+
+```sh
+npm run skillpack -- route "请调研三家竞争对手并输出带引用的中文报告"
+npm run skillpack -- compose "Plan, implement, and security-review a bounded code change"
+npm run skillpack -- catalog stats
+npm run skillpack -- packs
+npm run skillpack -- relations
+npm run skillpack -- state init safe-skill-evolution
+npm run skillpack -- security check path/to/lifecycle-review.yaml
+npm run skillpack -- train attempt path/to/evolution-attempt.yaml
+npm run skillpack -- harness status
+npm run skillpack -- harness discover --adapter pi
+```
+
+For a Codex project-native installation, copy the reviewed directories under `.agents/skills/` into the target repository's `.agents/skills/`. The same generated Skills are available under `skills/` for the plugin bundle and compatible harnesses. Canonical sources live in `skill-src/`; do not edit either projection directly.
+
+## npm releases
+
+Permanent releases use GitHub Actions and npm Trusted Publishing (OIDC), without a long-lived repository write token. Exact tag/version matching, `main` ancestry, the complete CI gate, an `npm` deployment Environment, package inspection, and `next`/`latest` separation are enforced before publication. Because npm requires a package to exist before OIDC trust can be configured, maintainers must perform one 2FA-authenticated bootstrap publish first. Follow the complete [npm release and rollback guide](docs/npm-release.md).
+
+## Repository map
+
+```text
+.codex-plugin/        Codex plugin manifest
+.agents/skills/       generated project-native projection
+skills/               generated plugin/harness projection
+skill-src/            canonical category, atomic, and meta Skills
+taxonomy/             classification standard and boundaries
+catalog/              attributed, non-executed upstream metadata
+packs/                composable capability packages
+runtime/              optional pack-specific state schemas and initial states
+schemas/              machine-readable contracts
+evals/                split datasets, gates, and baselines
+paper/                English paper draft, Chinese extended abstract, bibliography
+.skill-system/        evolution proposals and immutable decisions
+  knowledge/          non-executable, indexed evolution patterns
+src/                  router, validator, catalog, evaluator, trainer, harnesses
+```
+
+## Evaluation and real evolution evidence
+
+`npm run skillpack -- gate` evaluates routing without collapsing metrics: category hit@1/@3, atom hit@1/@3, atom MRR, equivalence-aware atom Recall@3 and Full Coverage@3, non-invocation accuracy, and safety pass rate. Multi-Atom requests pass Full Coverage only when every required capability group appears. English, Chinese, adversarial, and same-domain hard-distractor suites are separate. The current 35 authored examples all pass; this verifies repository conformance, not general model utility. Task completion uses a different rubric and cannot be inferred from routing accuracy. `skillpack harness effect <without.json> <with.json>` then measures paired completion/rubric lift under the same dataset and harness identity.
+
+The repository includes one real governed evolution record: `proposal-generic-zh-fallback`. The candidate added `index.zh.md`, passed isolated development plus untouched English, Chinese, and adversarial suites, and produced an append-only promotion decision with a rollback revision.
+
+New candidates can be bound to their exact canonical Git diff with `npm run skillpack -- train propose --id <id> --target <skill-id> --observation <evidence> --author <identity> --authorship <human|model-assisted|model-generated> [--generator <model>]`, then evaluated and independently promoted through the immutable decision log. Individual optimizer steps can be recorded with bounded `add`, `delete`, or `replace` edits; ties, protected regressions, over-budget attempts, and declared decisions inconsistent with measurements fail closed. Protected datasets, baselines, and the release gate cannot certify a candidate that changes them.
+
+Pi 0.84.4 is pinned and its real `loadSkillsFromDir` implementation discovers all 22 Skills. Model-backed task completion remains explicitly **uncertified** until Pi provider credentials are configured. The deterministic Mock adapter tests protocol plumbing only and is always marked `synthetic: true`; the optional DeepSeek Harness adapter stays disabled until a compatible CLI release is pinned.
+
+See [evaluation](docs/evaluation.md), [harnesses](docs/harnesses.md), and the [evolution policy](docs/evolution-policy.md).
+
+The [Evolution Knowledge policy](docs/evolution-knowledge.md) explains how recurring successes, failures, rejected proposals, and research evidence become scoped, traceable patterns without becoming hidden task instructions.
+
+## Refreshing the research catalog
+
+```sh
+npm run skillpack -- catalog collect
+npm run skillpack -- catalog deduplicate
+npm run skillpack -- catalog stats
+```
+
+Collection uses fixed Git revisions and the read-only official MCP Registry endpoint, records attribution and fingerprints, and does not execute packages, hooks, endpoints, or Skill instructions. Review [catalog methodology](docs/catalog-methodology.md) and [third-party notices](THIRD_PARTY.md) before changing sources.
+
+The machine-readable [`catalog/decomposition-map.yaml`](catalog/decomposition-map.yaml) shows how representative upstream patterns informed each local Atom, the Meta Skill, and all four packs without copying or activating upstream implementations.
+
+## Research basis and boundaries
+
+The [Agent Skill literature review](docs/research/2026-09-02-agent-skill-literature.md) maps evidence from SkillsBench, Skill-Inject, compositional routing, structured composition, retrieval, and self-evolving Skill work to adopted, deferred, and rejected changes. The focused [WikiSkill and SKILL.state analysis](docs/research/2026-09-02-wikiskill-skill-state.md) explains why persistent cross-iteration knowledge belongs under Meta governance while bounded within-run state belongs to Capability Pack execution. The subsequent [retrieval, security, and optimization synthesis](docs/research/2026-09-02-retrieval-security-optimization.md) maps SkillRet, SkillRouter, realistic Skill-use evaluation, Agent Skill Security, SkillNet, and SkillOpt into implemented controls and deferred experiments. Research may improve retrieval, composition, verification, execution, and learning loops, but it does not replace the Category → Atom → Capability Pack → Meta architecture.
+
+The resulting system argument is available as the conference-style paper draft [SkillPack One: A Portable Control Plane for Self-Organizing, Composable, and Governed Agent Skills](paper/skillpack-one.md), with a [Chinese extended abstract](paper/skillpack-one.zh-CN.md) and [BibTeX bibliography](paper/references.bib). Numerical results in the draft are deliberately limited to reproducible repository conformance; the model-backed experiments are presented as future protocol, not completed evidence.
+
+## Roadmap
+
+- Grow held-out multilingual routing and executable task suites from real failures.
+- Compare deterministic, sparse/dense hybrid, distilled-metadata, and body-aware retrieval without changing the portable control-plane contract.
+- Build protected compositional datasets and certify paired live Skill lift across pinned harness/model pairs.
+- Add semantic duplicate review without turning similarity into automatic deletion.
+- Certify live Pi task-completion baselines across pinned model/provider pairs.
+- Pin and implement a compatible DeepSeek Harness adapter.
+- Add signed snapshots, trust promotions, canary releases, and richer rollback telemetry.
+
+Contributions are welcome through [CONTRIBUTING.md](CONTRIBUTING.md). Security issues follow [SECURITY.md](SECURITY.md). Licensed under Apache-2.0.

package/README.zh-CN.md

@@ -0,0 +1,176 @@
+# SkillPack One
+
+[English](README.md) · **研究型 Alpha 版本**
+
+> **The SkillPack is all you need.**
+>
+> 只装一个包，让它自动寻找、组合和进化你需要的技能。
+
+SkillPack One 对外提供一个安装包，内部技术架构称为 **Self-Organizing Skill System**：一个兼容 Codex 的原子化、可组合、可评估、可安全自进化的 Agent Skill 系统。
+
+“一个包”指一个统一的安装与治理入口，不是把所有指令塞进一个巨大 Prompt，也不宣称当前已经包含世上所有能力。系统通过渐进式读取保留广阔目录，但每次任务只加载命中的分类 Skill 和原子 Skill。
+
+它没有把网上所有 Skill 一股脑安装进上下文，而是把生态分成四层：
+
+```mermaid
+flowchart LR
+    R[用户需求] --> C[分类 Skill]
+    C --> A[最小原子 Skills]
+    A --> P[能力包 / 完整任务]
+    U[658 条上游目录] -. 只作证据 .-> C
+    M[元 Skill 治理器] --> C
+    M --> A
+    M --> P
+    E[保留集评估] --> M
+```
+
+上游目录只为分类、拆分和组合提供证据；只有经过本仓库审查并声明能力契约的内容，才进入可执行 Skill 层。
+
+## 首版包含什么
+
+| 层级 | 当前数量 | 作用 |
+| --- | ---: | --- |
+| 分类 Skills | 10 | 第一阶段按真实需求分类，并处理领域边界 |
+| 原子 Skills | 11 | 小而独立、可测试、可替换的能力契约 |
+| 元 Skills | 1 | 管理提案、评估、晋级、弃用与回滚，也约束自身 |
+| 能力包 | 4 | 不合并原子的前提下，组成端到端任务 |
+| 上游记录 | 658 | 388 个 Agent Skills + 270 个官方 MCP Registry 服务 |
+| 疑似重复簇 | 8 | 进入人工审查队列，不自动删除来源 |
+
+每个分类投影同时提供英文回退 `index.md`、`index.en.md`、`index.zh-CN.md` 和通用中文回退 `index.zh.md`。英文 `SKILL.md` 保持跨工具发现兼容性，本地化索引则保留不同语言的表达和路由习惯。
+
+## 我采纳并固化的设计原则
+
+- **先需求、后工具。** 先判断目标结果、产物、操作和约束，再选择具体产品或协议。
+- **一个原子一个主要能力。** 稳定能力 ID，加上输入、输出、副作用、权限、非目标和测试，使重叠可计算、可审查。
+- **显式组合。** 多步骤请求只选择经过审查的能力包，把稳定 Skill 子集、数量、依赖顺序和验收测试编译成可解释 DAG。
+- **在安全范围内约束当前状态。** 长任务能力包可以按需声明经 Schema 验证的当前状态，同时把不可变审计历史留在活动提示之外；当历史无法安全投影为状态时，仍使用对话历史模式。
+- **渐进式读取。** Codex 先看到精简元数据，再命中分类索引，最后只加载完成任务所需的原子 Skill。
+- **使用有类型的关系，而不是无治理知识图。** 已审查契约与能力包只生成 `confusable-with`、`compose-with`、`depends-on` 和 `packaged-in` 关系；相似度可以触发审查，但不能自动授权安装、合并、执行或删除。
+- **插件式架构。** 仓库本身是一个插件包，包含清单、两种 Skill 投影、Schema、能力包和评估资产。
+- **证据门禁下的进化。** 元 Skill 可以修改自己，但不能在同一个提案中削弱自己的门禁；保留测试集、权限审批、追加式决策记录和回滚指针不受优化目标控制。
+- **生命周期分阶段安全。** 创作、存储、检索、选择、执行和进化是六个不同的信任边界；任何一阶段通过都不能替代其他阶段的证据。
+- **持久化进化知识。** 原始运行、已沉淀模式和活动 Skill 相互分离；元治理可以跨迭代复用索引证据，普通任务只看到已晋级 Skill。
+- **被收录不等于可信。** 采集过程不执行上游代码；许可未知的条目只保存元数据，安装前必须另行安全审查。
+- **看 Skill Lift，不看“有没有 Skill”。** 只有在相同任务上优于无 Skill 基线且受保护指标不退化，才能证明 Skill 有用；Synthetic 协议测试不能认证该结论。
+
+架构参考当前的 [OpenAI Agent Skills 文档](https://learn.chatgpt.com/docs/build-skills)、[Codex 插件文档](https://learn.chatgpt.com/docs/build-plugins)和[官方 MCP Registry API](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/official-registry-api.md)。
+
+## 设计哲学：只装一个包，但允许多种实现
+
+SkillPack One 是一套通用设计哲学的参考实现。个人、社区和组织可以采用不同的分类体系、目录结构、评测 Harness 或元 Skill 拓扑，只要遵循共同基础：
+
+1. **所有 Skill 使用同一套描述规范。** 每个 Skill 都是一个目录，并包含可移植的 `SKILL.md`，其中 `name` 与 `description` 必须能准确区分触发范围。本仓库进一步要求每个第一方分类、原子和元 Skill 使用同一份机器可读 `skill.contract.yaml`，声明输入、输出、结果、产物、边界、权限、副作用、来源、路由信号和评测。
+2. **分类 Skill 负责渐进式索引。** 请求先命中分类 Skill，再读取该层级的 `index.md` 或对应语言索引，最后才加载选中的原子 Skill。分类树建议最多三层：行业或领域大类 → 细分领域 → 具体分类 → 原子 Skill；原子 Skill 是叶节点，不计入分类层数。本实现为了兼容 Codex 发现机制，保持可执行 Skill 目录扁平，通过 taxonomy 的父子关系和生成索引表达逻辑层级；其他宿主也可以采用物理嵌套目录。
+3. **所有 Skill 都可以生成、训练和进化。** Skill 可以由人编写、从工作流录制，或在 ChatGPT 中通过 `@skill-creator`、在 Codex 中通过 `$skill-creator` 生成草案。这里的“训练”是依据版本化路由题集和任务题集，持续优化描述、契约、指令与组合，不是静默修改模型权重。元 Skill 负责提案、评测、晋级、弃用和回滚；它既可以管理整个包，也可以只管理某个分类子树或单个 Skill，并以同一门禁约束自身。
+4. **原子 Skill 的职责边界必须明确。** 一个原子 Skill 只拥有一个主要结果、一个主导产物或状态变化、一个权限包络、一个聚焦评分标准和一个可独立复用的失败边界。端到端流程应通过能力包组合原子能力，而不是重新把多个原子揉成巨型 Skill。
+5. **基础规范通用，具体分类并不唯一。** 不同维护者可以按行业、职能、模态或风险采用不同划分。是否符合这套哲学，取决于描述可移植、边界明确、索引渐进、证据可查和进化受治理，而不是照搬本仓库现有的十个一级分类。
+
+本实现的具体规则见[分类标准](taxonomy/classification-standard.zh-CN.md)、[评估流程](docs/zh-CN/evaluation.md)和[进化策略](docs/zh-CN/evolution-policy.md)。
+
+## 社区与大模型贡献
+
+社区和大模型都可以提出新 Skill 或改进方案，但“生成”不等于“审核通过”。每项贡献采用同一准入流程：
+
+1. 提交来源、许可证状态、统一能力契约、多语言路由样例、权限声明和评测案例。
+2. 使用大模型辅助分类与相似度分析，选择最窄的分类、提取原子职责，并找出与现有 Skill 的重叠。
+3. 审核安全、权限、来源和重复候选。生成变更的模型不能成为唯一审核者；应根据风险使用独立模型、维护者或两者共同审核。
+4. 重新生成父子分类索引，并按需要运行开发集、留出集、多语言集、对抗集和任务完成集。
+5. 只有生成不可覆盖的晋级决策和回滚指针后才能合入；若提案只增加表述、没有新的可复用能力，则应与现有 Atom 合并、拒绝或弃用。
+
+这样，社区增长增加的是有效能力，而不是重复上下文。详细清单见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 快速开始
+
+需要 Node.js 24 或更新版本，以及 Git。
+
+```sh
+git clone https://github.com/WnagoiYy/skillpack-one.git
+cd skillpack-one
+npm ci
+npm run ci
+```
+
+体验可解释路由和状态检查：
+
+```sh
+npm run skillpack -- route "请调研三家竞争对手并输出带引用的中文报告"
+npm run skillpack -- compose "规划、实现并安全审查一个边界明确的代码修改"
+npm run skillpack -- catalog stats
+npm run skillpack -- packs
+npm run skillpack -- relations
+npm run skillpack -- state init safe-skill-evolution
+npm run skillpack -- security check path/to/lifecycle-review.yaml
+npm run skillpack -- train attempt path/to/evolution-attempt.yaml
+npm run skillpack -- harness status
+npm run skillpack -- harness discover --adapter pi
+```
+
+若要以 Codex 项目级 Skill 使用，请把本仓库 `.agents/skills/` 下经过审查的目录复制到目标仓库的 `.agents/skills/`。插件包和兼容 Harness 使用 `skills/`。二者都由 `skill-src/` 生成，请勿直接编辑投影目录。
+
+## npm 发布
+
+长期发布流程使用 GitHub Actions 与 npm Trusted Publishing（OIDC），仓库中不保存长期写入 Token。流程会强制校验标签与版本严格一致、发布提交属于 `main`、完整 CI、`npm` Environment 审批、包内容，以及 `next`/`latest` 隔离。由于 npm 只允许已经存在的包绑定 OIDC，维护者需要先进行一次带 2FA 的首次发布。完整步骤与回滚方式见 [npm 发布指南](docs/zh-CN/npm-release.md)。
+
+## 目录结构
+
+```text
+.codex-plugin/        Codex 插件清单
+.agents/skills/       生成的 Codex 项目级投影
+skills/               生成的插件/Harness 投影
+skill-src/            分类、原子与元 Skill 的唯一源文件
+taxonomy/             分类标准与边界
+catalog/              有来源、未执行的上游元数据
+packs/                可组合能力包
+runtime/              能力包可选的专属状态 Schema 与初始状态
+schemas/              机器可读能力契约
+evals/                分集问题集、门槛与基线
+paper/                英文论文草稿、中文扩展摘要与参考文献
+.skill-system/        进化提案与追加式决策记录
+  knowledge/          不可执行、可索引的进化模式
+src/                  路由、校验、采集、评估、训练和 Harness
+```
+
+## 测试与真实进化证据
+
+`npm run skillpack -- gate` 分别评估分类 Hit@1/@3、原子 Hit@1/@3、MRR、等价能力感知的原子 Recall@3 与 Full Coverage@3、不调用准确率和安全通过率，不用一个总分掩盖短板。多原子请求只有在每个必需能力组都出现时才通过 Full Coverage。英文、中文、对抗和同领域硬干扰问题集彼此独立；当前 35 条人工编写样例全部通过，这只验证仓库工程一致性，不代表真实模型通用能力。任务完成率另行评估，不能用路由正确率代替。`skillpack harness effect <without.json> <with.json>` 会在相同数据集与 Harness 下计算成对完成率和 Rubric 增益。
+
+仓库已经保存一次真实的受治理进化：`proposal-generic-zh-fallback`。该候选增加了 `index.zh.md`，依次通过开发集、未参与生成的英文/中文测试集和对抗集，并写入带回滚版本的不可覆盖晋级记录。
+
+新候选可以通过 `npm run skillpack -- train propose --id <id> --target <skill-id> --observation <evidence> --author <identity> --authorship <human|model-assisted|model-generated> [--generator <model>]` 与规范 Git 差异精确绑定，再进入评估和独立晋级决策记录。单个优化步骤可以记录有预算的 `add`、`delete`、`replace` 编辑；分数持平、受保护指标回退、超预算或声明决策与测量不一致都会失败关闭。受保护数据集、基线和发布门槛不能为同时修改它们的候选背书。
+
+Pi 0.84.4 已固定版本，并通过其真实 `loadSkillsFromDir` 发现全部 22 个 Skill。由于本机尚未配置 Pi 模型提供商凭证，模型驱动的任务完成率仍明确标记为**未认证**。Mock 只验证协议管线，结果始终带 `synthetic: true`；DeepSeek Harness 需等兼容 CLI 版本固定后才启用。
+
+详细说明见[评估流程](docs/zh-CN/evaluation.md)、[Harness 适配](docs/zh-CN/harnesses.md)和[进化策略](docs/zh-CN/evolution-policy.md)。
+
+[进化知识策略](docs/zh-CN/evolution-knowledge.md)说明如何把重复成功、失败、被拒绝提案和研究证据沉淀为有范围、可追溯的模式，同时避免它们成为隐藏任务指令。
+
+## 刷新 300+ 来源目录
+
+```sh
+npm run skillpack -- catalog collect
+npm run skillpack -- catalog deduplicate
+npm run skillpack -- catalog stats
+```
+
+采集固定 Git 版本并读取官方 MCP Registry 的只读接口，保存来源、归属和指纹；不会运行包、Hook、端点或 Skill 指令。修改来源前请阅读[目录方法](docs/zh-CN/catalog-methodology.md)和[第三方说明](THIRD_PARTY.md)。
+
+机器可读的 [`catalog/decomposition-map.yaml`](catalog/decomposition-map.yaml) 说明代表性上游模式如何影响每个本地原子 Skill、元 Skill 和四个能力包，同时不复制或激活上游实现。
+
+## 论文依据与边界
+
+[Agent Skill 论文综述](docs/zh-CN/research/2026-09-02-agent-skill-literature.md)把 SkillsBench、Skill-Inject、组合路由、结构化组合、检索和自进化研究分别映射为“立即采纳、暂缓、明确不采纳”。专项的 [WikiSkill 与 SKILL.state 分析](docs/zh-CN/research/2026-09-02-wikiskill-skill-state.md)解释了为什么跨迭代持久知识属于元治理，而单次任务的有界当前状态属于能力包执行。后续的[检索、安全与优化综合分析](docs/zh-CN/research/2026-09-02-retrieval-security-optimization.md)把 SkillRet、SkillRouter、真实场景 Skill 使用评测、Agent Skill Security、SkillNet 和 SkillOpt 映射为已实现控制与暂缓实验。研究可以改进检索、组合、验证、执行与学习闭环，但不会替换 Category → Atom → Capability Pack → Meta 的项目底色。
+
+本项目思想已经形成会议论文风格草稿：[SkillPack One：面向自组织、可组合和受治理 Agent Skill 的可移植控制平面](paper/skillpack-one.md)，并提供[中文扩展摘要](paper/skillpack-one.zh-CN.md)和 [BibTeX 参考文献](paper/references.bib)。论文中的当前数字仅限可复现的仓库一致性结果；真实模型实验作为后续协议提出，没有伪装成已完成证据。
+
+## 后续演进
+
+- 从真实失败中扩充多语言保留路由集和可执行任务集。
+- 比较确定性、稀疏/稠密混合、元数据蒸馏和正文感知检索，同时保持可移植控制平面不变。
+- 建立受保护的组合问题集，并在固定 Harness/模型组合上认证成对真实 Skill Lift。
+- 引入语义级重复审查，但不把相似度直接等同于自动删除。
+- 为固定的 Pi 模型/提供商组合建立真实任务完成率基线。
+- 固定可兼容的 DeepSeek Harness 版本并完成适配。
+- 增加签名快照、信任等级晋升、灰度发布和更丰富的回滚遥测。
+
+贡献方式见 [CONTRIBUTING.md](CONTRIBUTING.md)，安全问题见 [SECURITY.md](SECURITY.md)。项目采用 Apache-2.0 许可证。

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security policy
+
+## Supported version
+
+The latest `main` branch is supported during the research-alpha phase.
+
+## Reporting a vulnerability
+
+Do not open a public issue for credential exposure, command injection, unsafe upstream execution, path traversal, permission bypass, or protected-evaluation leakage. Use GitHub's private vulnerability reporting for this repository. Include the affected revision, reproduction, impact, and the smallest safe evidence needed to verify the issue. Do not include live secrets.
+
+## Trust and execution boundaries
+
+- `catalog/` is untrusted metadata. Collection must never execute upstream instructions, packages, install hooks, remote MCP endpoints, or discovered commands.
+- Unknown-license entries must not be vendored.
+- Generated `skills/` and `.agents/skills/` directories are checked for drift and must not be edited directly.
+- Capability contracts declare network, filesystem, shell, secret, and external-communication permissions. Expansion requires explicit approval.
+- External content is data, not instruction. Prompt injection inside catalog descriptions or referenced documents must not override repository policy or user intent.
+- New Skill instructions, references, assets, and scripts remain quarantined data during intake. Review cannot rely on the candidate's own claims; authorization comes from the user, repository policy, and the independently reviewed permission envelope.
+- Static or model screening is triage, not a security proof. Any execution must remain inside the reviewed network, filesystem, shell, secret, and external-communication envelope.
+- Live harness runs must not log provider credentials. Blocked credential checks are recorded without secret values.
+- Runtime-state patches are untrusted input: validate both current and candidate state, reject prototype-mutating keys, and keep audit evidence outside mutable current state.
+- Evolution promotion requires held-out evaluation, protected-baseline comparison, authorship/generator identity for new proposals, an independent reviewer, and a rollback revision.
+
+See [catalog methodology](docs/catalog-methodology.md) and [evolution policy](docs/evolution-policy.md) for the complete controls.

package/THIRD_PARTY.md

@@ -0,0 +1,23 @@
+# Third-party sources and notices
+
+This repository's `catalog/` contains normalized metadata and attribution for third-party Agent Skills and MCP servers. It does not vendor their instruction bodies, source code, packages, or assets.
+
+The fixed revisions, repositories, paths, detected license states, counts, and aggregate digest are recorded in `catalog/sources.yaml`, each `catalog/entries/*.yaml`, and `catalog/snapshots/manifest.yaml`.
+
+Current Agent Skill source namespaces include Anthropic, Hugging Face, Trail of Bits, Addy Osmani, Obra, Cloudflare, Supabase, Sentry, K-Dense AI, and Hypergiant. MCP metadata comes from the official Model Context Protocol Registry. Each upstream work remains under its own license and copyright. A detected repository license is evidence, not legal advice; `unknown` means the content must not be copied into this project.
+
+Primary source links:
+
+- [Anthropic skills](https://github.com/anthropics/skills)
+- [Hugging Face skills](https://github.com/huggingface/skills)
+- [Trail of Bits skills](https://github.com/trailofbits/skills)
+- [Addy Osmani agent skills](https://github.com/addyosmani/agent-skills)
+- [Obra Superpowers marketplace](https://github.com/obra/superpowers-marketplace)
+- [Cloudflare skills](https://github.com/cloudflare/skills)
+- [Supabase agent skills](https://github.com/supabase/agent-skills)
+- [Sentry skills](https://github.com/getsentry/skills)
+- [K-Dense scientific skills](https://github.com/K-Dense-AI/claude-scientific-skills)
+- [Hypergiant agent skills](https://github.com/gohypergiant/agent-skills)
+- [Official MCP Registry](https://registry.modelcontextprotocol.io/)
+
+The Pi adapter depends on `@earendil-works/pi-coding-agent` under its published package license. Dependency notices are available from the installed packages and lockfile.