skillpack-one 0.1.0-alpha.10

package/paper/skillpack-one.md

@@ -0,0 +1,272 @@
+# SkillPack One: A Portable Control Plane for Self-Organizing, Composable, and Governed Agent Skills
+
+**Anonymous system paper draft — 2026-09-02**
+
+## Abstract
+
+Reusable Agent Skills package procedural knowledge as discoverable files, but a growing ecosystem creates four systems problems: large catalogs become difficult to route, overlapping capabilities become difficult to compose, community artifacts cross several trust boundaries, and self-modification can silently optimize against its own evidence. This paper presents **SkillPack One**, a portable control plane for self-organizing Agent Skills. The design separates Category Skills for progressive routing, Atomic Skills with explicit responsibility and permission boundaries, Capability Packs that compile reviewed partial orders into executable plans, and Meta Skills that govern proposal, evaluation, promotion, rollback, and learning. All first-party capabilities share a machine-readable contract; locale-specific indexes preserve language-specific routing while stable identifiers remain portable. The system keeps immutable traces, persistent evolution knowledge, active Skills, and bounded within-run state as distinct artifacts. Recent retrieval, realistic-use, security, relation-graph, and text-optimization research is incorporated through equivalence-aware multi-Skill metrics, same-domain hard distractors, six-stage lifecycle security reviews, reviewed typed relations, and strictly improving bounded evolution attempts. The reference implementation contains 22 Skill contracts, four Capability Packs, and a non-executed catalog of 658 upstream Skill and Model Context Protocol records. Thirty-five deterministic conformance examples pass the current routing gate, including multilingual, adversarial, and hard-distractor suites. These results validate implementation invariants, not general model utility; the paper therefore specifies a separate model-backed experimental protocol based on paired no-Skill/with-Skill task effect. SkillPack One's central contribution is an interchangeable governance contract: learned routers and optimizers may evolve, while authorization, evidence separation, and rollback remain stable.
+
+**Keywords:** Agent Skills, capability routing, skill composition, self-improving agents, lifecycle security, progressive disclosure, agent governance
+
+## 1. Introduction
+
+Agent Skills have emerged as a lightweight adaptation layer between general-purpose language models and task-specific execution. A Skill can bundle instructions, scripts, references, and resources in a discoverable directory without changing model weights [1]. This mechanism is attractive because the artifact is portable, inspectable, and cheap to deploy. It also moves complexity out of the model and into a fast-growing capability ecosystem.
+
+Scale changes the problem. A system with ten Skills can expose their names directly; a system with tens of thousands must retrieve a small relevant subset. Public repositories contain functional overlap, inconsistent metadata, different permission needs, and untrusted instructions. Complex tasks require more than one Skill, so the system must predict a subset, count, order, and dependency structure. Finally, a self-improving Skill library risks training on its own test evidence, preserving accidental rules, expanding authority, and losing a known-good rollback state.
+
+Existing research has developed strong methods for individual parts of this problem. SkillsBench evaluates whether curated Skills improve downstream tasks [2]. SkillRet and SkillRouter study retrieval at realistic catalog scale [3, 4]. Realistic-use experiments separate Skill availability, selection, retrieval, loading, adaptation, and task completion [5]. SkillWeaver and SkillComposer address decomposition and structured composition [6, 7]. SkillNet organizes Skills with taxonomy, relations, and packages [8]. SkillOpt, WikiSkill, and related evolution systems turn trajectories into persistent or optimized procedural artifacts [9, 10]. SKILL.state separates current execution state from long interaction history [11]. Skill security research exposes supply-chain and lifecycle threats [12, 13].
+
+These advances leave an integration question: **what portable control plane allows different retrieval, composition, execution, and evolution implementations to interoperate without making any one learned backend the source of authorization?**
+
+SkillPack One addresses this question with four contributions:
+
+1. a shared Atomic Skill contract that makes outcome, boundary, permission, provenance, routing, and evaluation fields machine-readable;
+2. a progressive Category -> Atom -> Capability Pack architecture that keeps routing and composition explicit while supporting locale-specific indexes;
+3. an evidence-gated Meta Skill protocol that separates optimizer state, persistent knowledge, active capabilities, held-out evidence, and rollback;
+4. a reference implementation and evaluation protocol that reports routing, complete multi-Skill recovery, downstream Skill effect, and lifecycle security as separate measurements.
+
+The contribution is a systems architecture and reference implementation, not a claim that one taxonomy, lexical router, or optimizer is universally optimal.
+
+## 2. Design Requirements
+
+SkillPack One begins from six requirements derived from the intended deployment model and the literature.
+
+**R1 — One installation, progressive context.** “One pack” means one installation and governance entry point, not one giant prompt. A broad catalog must remain available without loading every Skill body into the active context.
+
+**R2 — Atomic responsibility.** An Atomic Skill owns one primary outcome, dominant artifact or state transition, permission envelope, focused rubric, and useful failure boundary. Workflows compose Atoms rather than widening them.
+
+**R3 — Taxonomy is replaceable, contracts are portable.** Organizations may classify industries or functions differently. Interoperability depends on shared descriptions, stable identifiers, explicit boundaries, and evidence rather than a universal directory tree.
+
+**R4 — Generation is not admission.** Human authors and models may generate Skills, but a proposal does not become active until provenance, security, held-out evaluation, and independent review pass.
+
+**R5 — Skill presence is not Skill utility.** Routing accuracy, load rate, and a syntactically valid Skill do not establish downstream benefit [2, 5]. Task claims require paired runs under a pinned model and harness.
+
+**R6 — Self-improvement is reversible.** Every accepted modification must preserve the evidence that motivated it, the candidate diff, protected metrics, approval identity, canary scope, and tested rollback pointer.
+
+## 3. Related Work
+
+### 3.1 Skill effectiveness and realistic use
+
+SkillsBench compares no-Skill, curated-Skill, and self-generated-Skill conditions across diverse tasks [2]. It motivates paired Skill-effect measurement and warns that fluent self-generation is not equivalent to improvement. Liu et al. move from idealized conditions toward large-pool retrieval and general-purpose Skills [5]. Their progressive settings reveal distinct failures in selection, retrieval, loading, adaptation, and use. SkillPack One therefore keeps task completion, routing, and Skill usage as different result families.
+
+### 3.2 Retrieval and composition
+
+SkillRet frames retrieval as long-document matching and reports Recall and strict completeness for multi-Skill requests; it also audits functionally equivalent Skills to reduce false negatives [3]. SkillRouter finds that Skill bodies contain routing information absent from raw names and descriptions and shows the value of hard negatives, false-negative filtering, and listwise reranking [4]. SkillWeaver decomposes complex requests, retrieves Skills per subtask, and constructs a dependency-aware plan [6]. SkillComposer treats subset, number, and order as one constrained sequence problem [7]. SkillPack One does not reproduce these learned models. Instead, it defines a common output contract and deterministic baseline against which a learned backend must be evaluated.
+
+### 3.3 Skill organization and evolution
+
+SkillNet separates taxonomy, typed relations, and packaged collections, with multi-dimensional quality assessment [8]. Trace2Skill consolidates lessons from multiple trajectories [15], while AutoSkill and SkillX study ongoing experience-driven construction and knowledge bases [16, 17]. Voyager provides an earlier example of an accumulating executable skill library in an open-ended environment [18]. WikiSkill separates traces, persistent consolidated knowledge, and active Skills [10]. SkillOpt adds bounded text edits, strict validation selection, rejected-edit feedback, and optimizer-only meta state [9]. SkillPack One adopts these as control-plane invariants while leaving the proposal generator interchangeable.
+
+### 3.4 State and security
+
+SKILL.state executes long procedures using an immutable specification, bounded current state, and the latest observation [11]. SkillPack One uses this as an opt-in Capability Pack profile, not a universal transcript replacement. Skill-Inject shows that Skill files form a supply-chain attack surface [13]. Agent Skill Security extends the threat model across authoring, storage, retrieval, selection, execution, and evolution [12]. The reference implementation represents all six stages explicitly and treats updates as new admissions.
+
+## 4. System Architecture
+
+```mermaid
+flowchart LR
+    U[User request] --> C[Category Skills]
+    C --> A[Atomic Skills]
+    A --> P[Capability Pack DAG]
+    P --> H[Agent harness]
+
+    K[Non-executed upstream catalog] -. classification evidence .-> C
+    R[Typed relation graph] -. confusable / compose / depend .-> A
+
+    T[Immutable traces] --> M[Meta Skill governor]
+    W[Persistent evolution knowledge] --> M
+    M --> Q[Bounded candidate proposal]
+    Q --> E[Dev / selection evaluation]
+    E --> X[Untouched held-out and adversarial evaluation]
+    X --> D[Independent promotion / rollback]
+    D --> C
+    D --> A
+    D --> P
+```
+
+### 4.1 Shared capability contract
+
+Every first-party Category, Atomic, and Meta Skill has a portable `SKILL.md` and a machine-readable `skill.contract.yaml`. The contract records:
+
+- stable identity, version, kind, localized name, and summary;
+- outcomes, artifacts, typed inputs and outputs;
+- preconditions, failures, side effects, and permission envelope;
+- primary and secondary taxonomy locations, lifecycle phases, modalities, dependencies, and risk;
+- localized positive and negative routing triggers plus explicitly confusable capabilities;
+- provenance, license, derivation, and evaluation identifiers.
+
+The contract does not attempt to encode the entire Skill body. It exposes the fields needed for routing, composition, governance, and review while retaining `SKILL.md` as the human- and agent-readable procedural artifact.
+
+### 4.2 Category routing and localization
+
+A request first selects a Category Skill, reads the locale-appropriate category index, and then loads only the selected Atom. The reference taxonomy recommends no more than three Category levels; the Atom is the leaf. Executable Skill directories remain flat for host discovery, while hierarchy is represented by taxonomy parents and generated indexes.
+
+The portable discovery file remains English. Category indexes provide `index.md`, `index.en.md`, `index.zh-CN.md`, and generic `index.zh.md` variants. Stable capability identifiers remain language-independent. This design lets a locale refine vocabulary and negative boundaries without forking the underlying capability.
+
+The baseline router is deterministic and explanation-producing. It reports matched positive signals, applied penalties, ranked Categories, ranked Atoms, Meta Skills, and ambiguity. An optional learned router may use body-aware offline features, but it must emit the same trace shape and may not silently expand permissions or activate an unreviewed capability.
+
+### 4.3 Atomic Skills, Capability Packs, and typed relations
+
+A Capability Pack names a reviewed set of stable Atom and Meta Skill identifiers, optional MCP dependencies, partial-order constraints, and acceptance tests. The compiler turns the partial order into deterministic stages. This avoids creating a new monolithic Skill for every workflow.
+
+The typed relation graph supplements the taxonomy with four evidence-bearing relations:
+
+- `confusable-with`, declared by a Skill contract;
+- `packaged-in`, declared by a reviewed Capability Pack;
+- `compose-with`, derived from reviewed co-membership;
+- `depends-on`, derived from a pack's directed ordering.
+
+Relations cannot authorize execution or deletion. Unknown endpoints, invalid self-relations, missing evidence, duplicate edges, and dependency cycles fail validation.
+
+### 4.4 Lifecycle security
+
+Each reusable capability has a lifecycle review with six independent stages. Authoring checks consistency among advertised behavior, instructions, and authority. Storage checks origin, integrity, version lineage, and dependencies. Retrieval checks manipulation and duplicate flooding. Selection checks planner-visible metadata and permission consistency. Execution checks actual operations and information flow. Evolution checks whether an update changes behavior, dependencies, provenance, or permission.
+
+Each stage records reviewed threats, evidence, status, and residual risk. An applicable stage cannot pass without evidence. `not-applicable` requires a rationale. A semantic review never substitutes for runtime enforcement.
+
+### 4.5 Governed evolution
+
+Evolution has four distinct stores:
+
+1. immutable task traces and run artifacts;
+2. persistent Evolution Knowledge containing recurring, scoped, evidence-linked patterns;
+3. append-only bounded evolution attempts;
+4. active, promoted Skills and Capability Packs.
+
+An optimizer attempt may apply only explicit `add`, `delete`, or `replace` edits within a proposal and an edit budget. Training evidence proposes changes; a separate selection split accepts only strict improvement. Ties are rejected. Any protected regression rejects the attempt. Rejected edits and score changes remain evidence so later optimization does not repeat them. Optimizer-only summaries may guide later proposals but are not shipped inside an Atomic Skill.
+
+Promotion requires an independent reviewer, an append-only decision, a canary scope, and a rollback revision. A Meta Skill proposal cannot weaken its own gate, replace its held-out set, erase its audit history, or remove its rollback path.
+
+### 4.6 Long-horizon state
+
+Capability Packs may opt into a JSON-Schema-validated current-state profile with JSON Merge Patch semantics and an external audit log. This profile is appropriate only when the current state is a sufficient statistic for future action. Transcript mode remains valid when history itself is the task, when a summary would erase authority-relevant evidence, or when concurrent actors make state reconciliation unsafe.
+
+## 5. Reference Implementation
+
+SkillPack One is implemented in TypeScript and distributed as a Codex-compatible plugin and npm package. Canonical Skills live in `skill-src/`; generated projections are emitted under `skills/` and `.agents/skills/`. The package includes JSON Schemas, a deterministic router, Capability Pack compiler, harness adapters, catalog collection, evaluation and effect measurement, governed proposal tooling, Evolution Knowledge, runtime-state validation, lifecycle security review, and typed relation construction.
+
+The current snapshot contains:
+
+| Artifact | Count | Role |
+| --- | ---: | --- |
+| Category Skills | 10 | first-stage needs and boundary routing |
+| Atomic Skills | 11 | independently testable capability contracts |
+| Meta Skills | 1 | governed lifecycle change |
+| Capability Packs | 4 | reviewed composition and ordering |
+| Upstream catalog records | 658 | attributed, non-executed classification evidence |
+| Typed relation nodes / edges | 26 / 49 | reviewed confusion, composition, dependency, packaging |
+
+Of the 658 upstream records, 388 are Agent Skills and 270 are official MCP Registry server records. Unknown or detected license status remains metadata; collection does not authorize execution.
+
+## 6. Evaluation
+
+### 6.1 Questions and metrics
+
+The current engineering evaluation asks:
+
+- **Q1:** Do public artifacts satisfy schemas and repository invariants?
+- **Q2:** Does the deterministic baseline preserve Category and Atom boundaries across English, Chinese, adversarial, and hard-distractor requests?
+- **Q3:** Do the new control-plane gates reject incomplete multi-Atom recovery, malformed lifecycle reviews, dependency cycles, and unsafe evolution attempts?
+
+Routing metrics are reported separately: Category Hit@1/3, Atom Hit@1/3, Atom MRR, Atom Recall@3, Atom Full Coverage@3, non-invocation accuracy, and safety pass rate. For a multi-Atom query, Recall@3 measures the fraction of required capability groups represented in the top three; Full Coverage@3 is one only when every group is represented. Reviewed functional alternatives may inhabit the same group.
+
+Task utility is a different experiment. Matched no-Skill and with-Skill runs compare completion, rubric pass, blocking, latency, and cost under the same dataset, harness, and model. Synthetic Mock runs test protocol plumbing and are non-certifying.
+
+### 6.2 Deterministic conformance result
+
+The candidate was evaluated on 35 authored examples:
+
+| Suite | Split | Locale | Examples | Category H@1 | Atom H@1 | Recall@3 | Full Coverage@3 | Safety |
+| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| routing-adversarial | adversarial, protected | en | 8 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
+| routing-bootstrap | development | en | 3 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
+| routing-en-test | test | en | 10 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
+| routing-hard-distractors | development | en | 4 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
+| routing-zh-cn-test | test | zh-CN | 10 | 1.00 | 1.00 | 1.00 | 1.00 | 1.00 |
+
+The hard-distractor development suite initially exposed a practical failure: negated phrases such as “do not edit the source” could still score as positive edit signals, while generic words such as “evidence” could dominate a security request. Before correction, the four-example suite produced 0.50 Category Hit@1, 0.50 Atom Hit@1, and 0.50 safety pass rate. Adding negation-aware positive matching and narrower outcome boundaries raised all three to 1.00 on that development suite. This is a test-driven debugging observation, not held-out evidence of generalization.
+
+Focused tests also verify that functional alternatives receive credit, partial multi-Atom recovery does not pass Full Coverage, lifecycle stages fail closed, declared evolution decisions must agree with measured evidence, and dependency cycles are rejected. The complete repository test suite is the reproducibility boundary for these engineering claims.
+
+### 6.3 What the result does not show
+
+The examples are small, authored for this repository, and partly used during development. A score of 1.00 therefore does not establish large-scale retrieval performance, cross-model Skill use, or downstream task lift. The deterministic router has not been compared with SkillRet- or SkillRouter-style learned retrieval over the complete upstream corpus. Live Pi task-effect certification also requires provider credentials and a pinned model. No claim in this paper transfers the numerical gains of cited systems to SkillPack One.
+
+## 7. Model-Backed Experimental Protocol
+
+A publication-ready empirical study should add four experiments without changing the control-plane contract.
+
+**E1 — Retrieval scale and overlap.** Compare deterministic lexical routing, hybrid sparse/dense retrieval, body-distilled metadata, and body-aware retrieve-rerank over increasing catalog sizes. Report Hit, MRR, Recall, Full Coverage, latency, and cost. Audit functional equivalents before treating close candidates as negatives.
+
+**E2 — Progressive realism.** Evaluate forced curated Skills, autonomous curated Skills, curated Skills with distractors, retrieval with curated Skills present, retrieval without curated Skills, query-specific refinement, and no Skills. Record availability, retrieval, loading, use, and task completion separately.
+
+**E3 — Bounded optimizer ablation.** Compare unrestricted rewrite, bounded edits, bounded edits plus strict selection, rejected-attempt memory, and optimizer-only slow/meta state. Hold the target model and harness fixed. Use train data for proposal, a selection split for acceptance, and untouched test data for reporting.
+
+**E4 — Lifecycle security.** Measure malicious admission, retrieval attack success, malicious planner selection, execution policy violations, and malicious update detection at their corresponding boundaries. Include developer-friction measures such as false positive rate. No aggregate security score should hide a failed stage.
+
+All model-backed experiments should publish dataset and registry digests, Skill revision, harness and model versions, prompt/load policy, random seeds or repeated trials, cost, latency, and rejected results.
+
+## 8. Discussion
+
+### 8.1 Why the control plane stays deterministic
+
+The portable baseline is intentionally simpler than the best learned retrieval systems. Determinism supports debugging, offline installation, small private repositories, and a stable reference for regression. It also prevents a model score from becoming an authorization decision. A learned router is still desirable at large scale, especially when body-resident signals matter [3, 4]. SkillPack One treats it as a replaceable data-plane backend governed by common evidence and safety gates.
+
+### 8.2 Why a Category Skill is not merely a folder
+
+A Category Skill contains inclusion, exclusion, language-specific terminology, and an index of certified Atoms. It is a decision boundary: broad enough to reduce search space, but not an executable catch-all. This makes category errors observable and lets organizations replace the taxonomy without rewriting every Atom contract.
+
+### 8.3 Why self-evolution remains externally governed
+
+Self-evolution systems can accumulate useful procedures [9, 10, 14–17], but the ability to propose an edit does not confer authority to approve it. Separating proposer, evaluator, protected data, reviewer, and deployed artifact reduces self-confirmation. Preserving rejected attempts is equally important: negative evidence prevents repeated exploration without contaminating ordinary task context.
+
+## 9. Limitations and Threats to Validity
+
+The implementation is an early research-grade alpha. Its first-party Skill set is deliberately small, and the upstream catalog is metadata rather than executable coverage. The authored routing suites are insufficient to estimate real-user distributions. The Chinese suite tests one locale and does not establish general multilingual performance. The relation graph materializes declared evidence but does not discover missing relations. Lifecycle review validates record completeness and deterministic gates; it cannot prove that an LLM-based semantic reviewer or runtime taint tracker is sound. Capability Packs encode reviewed plans but do not yet learn new compositions from protected data. Current model-backed Harness results are not certified, and no statistical significance claim is made.
+
+The literature base is unusually recent and contains many preprints. Findings may change under peer review, broader replications, different model generations, or different agent harnesses. For this reason, the architecture adopts narrow invariants—separation, evidence, strict improvement, least authority, and rollback—rather than paper-specific implementations.
+
+## 10. Conclusion
+
+Skill ecosystems need more than package discovery. They need a portable contract for deciding what a Skill is responsible for, how it composes, which evidence supports it, what authority it needs, and how it can change without certifying itself. SkillPack One provides that contract through Category Skills, Atomic Skills, Capability Packs, and Meta governance. The reference implementation integrates equivalence-aware retrieval evaluation, lifecycle security, typed relations, persistent evolution knowledge, bounded long-horizon state, and strictly improving evolution attempts while remaining compatible with a single-installation Skill package.
+
+The intended future is not one universal taxonomy or one permanent router. It is a stable, auditable control plane under which different communities and models can discover, combine, test, and improve Skills without losing provenance, safety boundaries, or rollback.
+
+## References
+
+[1] OpenAI, “Agent Skills,” 2026. https://learn.chatgpt.com/docs/build-skills
+
+[2] X. Li et al., “SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks,” arXiv:2602.12670, 2026.
+
+[3] R. Kang, H. Cho, and Y. Kim, “SkillRet: A Large-Scale Benchmark for Skill Retrieval in LLM Agents,” arXiv:2605.05726, 2026.
+
+[4] Y. Zheng et al., “SkillRouter: Skill Routing for LLM Agents at Scale,” arXiv:2603.22455, 2026.
+
+[5] Y. Liu et al., “How Well Do Agentic Skills Work in the Wild: Benchmarking LLM Skill Usage in Realistic Settings,” arXiv:2604.04323, 2026.
+
+[6] X. Gao, “Compositional Skill Routing for LLM Agents: Decompose, Retrieve, and Compose,” arXiv:2606.18051, 2026.
+
+[7] X. Zhao et al., “Generative Skill Composition for LLM Agents,” arXiv:2606.32025, 2026.
+
+[8] Y. Liang et al., “SkillNet: Create, Evaluate, and Connect AI Skills,” arXiv:2603.04448, 2026.
+
+[9] Y. Yang et al., “SkillOpt: Executive Strategy for Self-Evolving Agent Skills,” arXiv:2605.23904, 2026.
+
+[10] L. Tang et al., “WikiSkill: Compiling Agent Experience into Persistent Knowledge for Skill Evolution,” arXiv:2608.27454, 2026.
+
+[11] S. Badhe, P. Tiwari, and J. Chung, “SKILL.state: Scalable Long-Horizon Agent Skills,” arXiv:2608.26263, 2026.
+
+[12] S. Badhe and P. Tiwari, “Agent Skill Security: Threat Models, Attacks, Defenses, and Evaluation,” arXiv:2607.13987, 2026.
+
+[13] D. Schmotz, L. Beurer-Kellner, S. Abdelnabi, and M. Andriushchenko, “Skill-Inject: Measuring Agent Vulnerability to Skill File Attacks,” arXiv:2602.20156, 2026.
+
+[14] H. Zhang et al., “CoEvoSkills: Self-Evolving Agent Skills via Co-Evolutionary Verification,” arXiv:2604.01687, 2026.
+
+[15] J. Ni et al., “Trace2Skill: Distill Trajectory-Local Lessons into Transferable Agent Skills,” arXiv:2603.25158, 2026.
+
+[16] Y. Yang et al., “AutoSkill: Experience-Driven Lifelong Learning via Skill Self-Evolution,” arXiv:2603.01145, 2026.
+
+[17] C. Wang et al., “SkillX: Automatically Constructing Skill Knowledge Bases for Agents,” arXiv:2604.04804, 2026.
+
+[18] G. Wang et al., “Voyager: An Open-Ended Embodied Agent with Large Language Models,” arXiv:2305.16291, 2023.
+

package/paper/skillpack-one.zh-CN.md

@@ -0,0 +1,79 @@
+# SkillPack One：面向自组织、可组合和受治理 Agent Skill 的可移植控制平面
+
+**中文扩展摘要 — 2026-09-02**
+
+## 摘要
+
+Agent Skill 通过可发现的目录封装过程知识，但 Skill 规模增长以后会产生四类系统问题：大目录难以准确检索，重叠能力难以组合，社区产物跨越多个安全信任边界，自修改则可能对自己的证据过拟合并失去回滚路径。本文提出 **SkillPack One**：一个面向自组织 Agent Skill 的可移植控制平面。系统将能力分为负责渐进路由的 Category Skill、职责与权限边界明确的 Atomic Skill、把已审查偏序编译成执行计划的 Capability Pack，以及治理提案、评测、晋级、回滚和学习的 Meta Skill。所有第一方能力遵循统一机器可读契约；不同语言可以拥有本地化索引，而稳定能力 ID 保持不变。系统进一步分离原始轨迹、持久进化知识、活动 Skill 和单次长任务状态。
+
+本轮吸收 SkillRet、SkillRouter、真实环境 Skill 评测、Agent Skill Security、SkillNet 与 SkillOpt 的关键机制，增加等价感知的多 Skill Recall/Full Coverage、同领域硬干扰、安全生命周期六阶段审查、类型化 Skill 关系，以及只接受严格提升的有界进化尝试。参考实现包含 22 个 Skill 契约、4 个能力包和 658 条不执行的上游 Skill/MCP 元数据。当前 35 条确定性合规样例全部通过，但这些结果只验证工程不变量，不证明真实模型任务增益。本文因此另外提出基于固定模型/Harness 的 no-Skill/with-Skill 成对实验协议。
+
+## 核心研究问题
+
+现有论文分别研究了检索、组合、进化、状态和安全，但工程系统仍需要回答：**能否建立一种稳定控制平面，让不同检索器、组合器、Harness 和优化器可以替换，同时不把任何学习模型的分数直接变成授权？**
+
+SkillPack One 的回答是四层架构：
+
+1. Category Skill 先判断用户真正需要的结果、产物和风险边界；
+2. Atomic Skill 只拥有一个主要结果和一个独立可测试的职责边界；
+3. Capability Pack 组合稳定 Atom ID、依赖顺序和验收测试；
+4. Meta Skill 只负责生命周期变化，不直接替代普通领域能力。
+
+## 系统设计
+
+```mermaid
+flowchart LR
+    U[用户请求] --> C[分类 Skill]
+    C --> A[原子 Skill]
+    A --> P[能力包 DAG]
+    P --> H[Agent Harness]
+
+    T[不可变轨迹] --> M[元 Skill 治理器]
+    W[持久进化知识] --> M
+    M --> Q[有界候选修改]
+    Q --> E[开发/选择集]
+    E --> X[未触碰留出集与对抗集]
+    X --> D[独立晋级或回滚]
+```
+
+统一契约包含稳定 ID、版本、类型、多语言名称、结果、产物、输入输出、前置条件、失败、权限、风险、正负触发、易混淆能力、来源与评测。`SKILL.md` 继续承载人和 Agent 可读的过程指令，契约只暴露检索、组合和治理所需的公共字段。
+
+分类目录建议不超过三层。英文 `SKILL.md` 作为可移植发现入口，分类索引可以提供 `index.md`、`index.en.md`、`index.zh-CN.md` 和通用 `index.zh.md`。语言版本可以调整表达习惯和负边界，但不改变 Atom ID。
+
+能力包不把多个 Atom 合成巨型 Skill，而是声明 Atom 集、可选 MCP、依赖偏序和验收测试。类型化关系图只物化已有证据：契约声明 `confusable-with`，能力包产生 `packaged-in`、`compose-with` 和 `depends-on`。关系相似不能授权安装、执行、合并或删除。
+
+## 受治理进化
+
+进化流程分为四类数据：不可变任务轨迹、跨迭代进化知识、有界 evolution attempt、已晋级活动 Skill。每个优化步骤只能在预算内执行显式 `add`、`delete` 或 `replace`；训练数据只能推动提案，选择集必须严格提升，平分也拒绝；任何受保护指标回退都拒绝。失败编辑与分数变化仍保留，以避免重复失败，但优化器专属记忆不能进入普通 Atom 上下文。
+
+晋级要求生成者之外的独立审核者、只追加决定、灰度范围和回滚 revision。Meta Skill 修改自己时也不能更换留出集、删除审计或弱化自身闸门。
+
+## 生命周期安全
+
+安全审查分为创作、存储、检索、选择、执行和进化六阶段。每个阶段记录信任假设、已检查威胁、证据、状态和残余风险。适用阶段没有证据就不能通过；`not-applicable` 必须解释。签名只能说明来源和完整性，语义审查只能说明一定程度的一致性，二者都不能替代运行时最小权限和信息流控制。任何更新都重新进入准入，而不是继承旧版本信任。
+
+## 当前工程结果
+
+候选实现包含 10 个 Category、11 个 Atom、1 个 Meta Skill、4 个能力包、26 个关系节点和 49 条有证据关系。非执行上游目录共有 658 条记录，其中 388 条 Agent Skill、270 条 MCP Server。
+
+确定性路由在 35 条仓库样例上通过当前闸门，样例包括英文、简体中文、对抗和同领域硬干扰。指标分别报告 Category Hit@1/3、Atom Hit@1/3、MRR、Recall@3、Full Coverage@3、非调用准确率与安全通过率，不汇总成一个总分。
+
+硬干扰开发集最初发现两个真实问题：否定语句“不要编辑源码”仍可能触发编辑 Atom，通用词 “evidence/source” 可能压过安全任务的真正结果边界。修复否定作用域与职责词以后，该四条开发集的 Category Hit@1、Atom Hit@1 和 Safety 从 0.50 提升到 1.00。该数字是测试驱动调试记录，不是留出集泛化结论。
+
+## 后续正式实验
+
+正式论文需要继续完成四组模型实验：
+
+1. 在不同目录规模下比较确定性、稀疏/稠密混合、正文摘要和正文感知重排；
+2. 分别测试强制精选 Skill、自主选择、干扰项、检索、无精选 Skill 的适配、任务特定改写和无 Skill；
+3. 对无约束重写、有界编辑、严格选择、失败缓存和慢速/元更新做消融；
+4. 分阶段测试恶意准入、检索操纵、Planner 欺骗、执行违规和恶意更新，并同时报告误报成本。
+
+所有实验都应记录数据集与目录摘要、Skill revision、模型、Harness、加载策略、重复试验、成本、延迟和失败结果。
+
+## 局限
+
+项目仍是研究级 alpha。第一方 Atom 数量很少，上游目录只是元数据而非已安装能力；35 条测试不足以估计真实用户分布；中文测试不能代表普遍多语言能力；关系图只能物化已声明关系；安全 Schema 只能验证记录和确定性门禁，不能证明模型 Judge 或运行时 Taint Tracking 正确；当前还没有可认证的真实 Harness Skill Lift。
+
+因此，本文的主要贡献不是“效果最好的路由器”，而是一种可替换实现、不可绕过证据与授权边界的控制平面。完整英文论文及参考文献见 [`skillpack-one.md`](skillpack-one.md)。
+

package/runtime/initial/safe-skill-evolution.state.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "pack": "safe-skill-evolution",
+  "phase": "classify",
+  "status": "pending",
+  "evidenceRefs": [],
+  "checks": {
+    "provenance": "pending",
+    "permissions": "pending",
+    "protectedMetrics": "pending",
+    "independentReview": "pending"
+  },
+  "blockers": []
+}

package/runtime/schemas/safe-skill-evolution.state.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WnagoiYy/skillpack-one/runtime/schemas/safe-skill-evolution.state.schema.json",
+  "title": "Safe Skill evolution current execution state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "pack", "phase", "status", "evidenceRefs", "checks", "blockers"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "pack": { "const": "safe-skill-evolution" },
+    "phase": { "enum": ["classify", "propose", "evaluate", "review", "canary", "promote", "rollback", "complete"] },
+    "status": { "enum": ["pending", "running", "blocked", "passed", "failed", "rolled-back"] },
+    "targetSkill": { "$ref": "#/$defs/id" },
+    "currentProposal": { "$ref": "#/$defs/id" },
+    "revisions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "base": { "$ref": "#/$defs/revision" },
+        "candidate": { "$ref": "#/$defs/revision" },
+        "rollback": { "$ref": "#/$defs/revision" }
+      }
+    },
+    "evidenceRefs": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "checks": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provenance", "permissions", "protectedMetrics", "independentReview"],
+      "properties": {
+        "provenance": { "$ref": "#/$defs/check" },
+        "permissions": { "$ref": "#/$defs/check" },
+        "protectedMetrics": { "$ref": "#/$defs/check" },
+        "independentReview": { "$ref": "#/$defs/check" }
+      }
+    },
+    "blockers": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "revision": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+    "check": { "enum": ["pending", "passed", "failed", "not-applicable"] }
+  }
+}

package/schemas/capability-pack.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WnagoiYy/skillpack-one/schemas/capability-pack.schema.json",
+  "title": "Composable capability pack",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "version", "name", "atoms", "optionalMcps", "acceptanceTests"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "$ref": "#/$defs/id" },
+    "version": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" },
+    "name": {
+      "type": "object",
+      "required": ["en"],
+      "minProperties": 1,
+      "properties": { "en": { "type": "string", "minLength": 1 } },
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "description": {
+      "type": "object",
+      "required": ["en"],
+      "minProperties": 1,
+      "properties": { "en": { "type": "string", "minLength": 1 } },
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "atoms": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/id" }
+    },
+    "optionalMcps": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/id" }
+    },
+    "specialSkills": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/id" }
+    },
+    "ordering": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["before", "after"],
+        "properties": {
+          "before": { "$ref": "#/$defs/id" },
+          "after": { "$ref": "#/$defs/id" }
+        }
+      }
+    },
+    "acceptanceTests": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/id" }
+    },
+    "runtimeState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stateSchema", "initialState", "patchSemantics", "historyPolicy"],
+      "properties": {
+        "stateSchema": { "$ref": "#/$defs/runtimePath" },
+        "initialState": { "$ref": "#/$defs/runtimePath" },
+        "patchSemantics": { "const": "json-merge-patch" },
+        "historyPolicy": { "const": "external-audit-log" }
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "runtimePath": { "type": "string", "pattern": "^runtime/[a-zA-Z0-9._/-]+$" }
+  }
+}

package/schemas/catalog-entry.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WnagoiYy/skillpack-one/schemas/catalog-entry.schema.json",
+  "title": "Upstream capability catalog entry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "type", "name", "summary", "author", "source", "license", "verifiedAt", "capabilities", "security"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 160 },
+    "type": { "enum": ["skill", "mcp-server", "plugin", "harness"] },
+    "name": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1 },
+    "author": { "type": "string", "minLength": 1 },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repository", "revision", "path", "url"],
+      "properties": {
+        "repository": { "type": "string", "format": "uri", "pattern": "^https://" },
+        "revision": { "type": "string", "pattern": "^[0-9a-fA-F]{40,64}$" },
+        "path": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "format": "uri", "pattern": "^https://" }
+      }
+    },
+    "license": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["declared", "detected", "unknown", "conflicting"] },
+        "spdx": { "type": "string", "minLength": 1 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "status": { "enum": ["declared", "detected"] } }, "required": ["status"] },
+          "then": {
+            "properties": { "spdx": { "type": "string", "minLength": 1 } },
+            "required": ["spdx"]
+          }
+        }
+      ]
+    },
+    "verifiedAt": { "type": "string", "format": "date-time" },
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "security": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "executesUpstreamCode"],
+      "properties": {
+        "status": { "enum": ["unreviewed", "metadata-reviewed", "statically-reviewed", "sandbox-tested", "rejected"] },
+        "executesUpstreamCode": { "type": "boolean" },
+        "notes": { "type": "string" }
+      }
+    },
+    "fingerprint": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "duplicateCluster": { "type": "string", "minLength": 1 },
+    "freshness": { "enum": ["current", "stale", "archived", "unknown"] }
+  }
+}

package/schemas/decomposition-map.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/WnagoiYy/skillpack-one/schemas/decomposition-map.schema.json",
+  "title": "Upstream evidence to local capability decomposition map",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "snapshotDigest", "policy", "capabilityMappings", "packMappings"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "snapshotDigest": { "$ref": "#/$defs/digest" },
+    "policy": { "type": "string", "minLength": 1 },
+    "capabilityMappings": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["capability", "synthesis", "evidence"],
+        "properties": {
+          "capability": { "$ref": "#/$defs/id" },
+          "synthesis": { "type": "string", "minLength": 1 },
+          "evidence": {
+            "type": "array",
+            "minItems": 2,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["catalogEntry", "contribution", "usage"],
+              "properties": {
+                "catalogEntry": { "$ref": "#/$defs/id" },
+                "contribution": { "type": "string", "minLength": 1 },
+                "usage": { "const": "design-evidence-only" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "packMappings": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pack", "compositionRationale", "evidence"],
+        "properties": {
+          "pack": { "$ref": "#/$defs/id" },
+          "compositionRationale": { "type": "string", "minLength": 1 },
+          "evidence": {
+            "type": "array",
+            "minItems": 2,
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/id" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}