Skill Optimizer

Evidence-driven creation, optimization, verification, release, and rollback for reusable LLM agent skills.

以证据驱动的方式创建、优化、验证、发布与回退可复用的 LLM Agent Skill。

English · 中文

---

English

Overview

Integrated strengths, not a stitched-together monolith. Skill Optimizer distills the strongest ideas from the work acknowledged below into one coherent, bounded control plane. Each adopted idea has a clear responsibility and is enabled only when its evidence, risk, and host support justify the cost; the project is not an omnibus wrapper that accumulates every feature. Special thanks and references →

Skill Optimizer treats Skill authoring as a controlled engineering process rather than a prompt-writing exercise. It can prove that a candidate should be promoted, that an existing Skill should be kept, or that no Skill should be created. Claims are limited to evidence that can be reconstructed from frozen inputs, receipts, and current artifact bytes.

The smaller, host-facing Skill Forge now lives in the standalone AlexBybye/skill-forge repository. This repository retains the broader Skill Optimizer control-plane history and runtime.

The current source version is 4.0.2. VERSION is the project-level version source; manifest and contract schema versions evolve independently. This working tree is not a published 4.0.2 release until the final regressions, explicit core refreeze, package receipts, clean commit, and matching v4.0.2 tag exist.

The runtime is a Python-standard-library control plane. Its workflow graph is fixed. A content-addressed ProcessPlan selects a bounded module DAG from closed templates; it is not an arbitrary profile interpreter. Additive ProcessPlan 2.0 separates authoring cost (M), quality evidence (Q), behavior-derived risk (R), and delivery depth (P); legacy ProcessPlan 1.0 remains accepted for compatibility and the formal no_skill path.

Implemented Boundary

The deterministic control plane implements four formal task modes, capability-bound ProcessPlan 1.0/2.0 compilation, bounded M authoring records, an authorized Q0/P0 draft lane, current-byte behavior-risk reports, Q1/Q2 QualityPlan and evidence reconstruction, narrow P1 personal install, isolated P2 team packaging, chain-bound workflow pauses, authorized deterministic validators, explicit read-only Codex and Claude execution, and the existing P3 formal release/install path. Both host executors are authorization-bound, capture a receipt, and reject workspace drift; neither claims OS-level isolation, automatic routing, or model conformance.

Q0, P1, and P2 are deliberately claim-limited. Q0 produces a structure-checked AuthoringHandoff, not formal quality evidence. P1 and P2 require an explicit user decision that accepts quality_unverified; P1 does not prove host activation or crash recovery, and P2 does not install, activate, or prove host compatibility or automatic routing.

Automatic Skill routing, hermetic or causal isolation, environment reset, sealed-holdout access enforcement, general artifact collection, stable token metrics, network control, paid live-model conformance, and host activation after installation remain unverified. Unknown mandatory capabilities fail closed; only predeclared degradations may remove dependent claims.

Local workflow and transaction journals are tamper-evident records, not digital signatures. A principal with equivalent filesystem write permission can replace an entire chain.

Transactional install synchronizes regular payload files, payload directories, and affected rename parents before recording committed. This is POSIX fsync-bounded durability; it is not a guarantee about device write caches, sudden power loss, network filesystems, or external storage barriers.

Core Invariants

• Evidence before promotion: decisions are rebuilt from the complete evidence graph and current package bytes.
• M, Q, R, and P are independent: M bounds authoring work, Q selects evidence depth, current candidate bytes derive R and its mandatory controls, and the user selects delivery depth P. A low Q or shallow P never erases safety requirements.
• Deterministic gates stay deterministic: gate criteria require an exact frozen script-validator identity and a core-recomputed typed threshold result.
• Cases are the statistical unit: repetitions and assessment rows cannot manufacture extra weight.
• Stopping is a first-class result: no_skill_confirmed and keep_baseline require evidence; they are not caller-supplied booleans.
• Actions are exact: public workflow grants exist only for analysis_execution, candidate_generation, and install. Budget/design/delivery choices and release acceptance are typed user decisions, not generic grants.
• Installation is a separate action: release acceptance does not imply install permission, and install permission binds one exact target and pre-state.

Formal Task Modes

Mode	Exact behavior
create	Builds and evaluates a candidate. Proven baseline sufficiency, or exhausted candidate non-gain, may end asno_skill_confirmed.
optimize	Requires an immutable baseline snapshot plus reproduction and diagnosis before candidate construction. Proven non-gain ends askeep_baseline.
description_only	Uses the optimization baseline path and additionally enforces the byte-level description-only gate.
no_skill	Builds, renders, packages, and installs no candidate. A frozen baseline-only probe must prove sufficiency beforeno_skill_confirmed.

reuse_candidate is a limited handoff suggestion, not a formal ProcessPlan mode. Verification is a workflow stage, not a fifth mode.

Workflow and ProcessPlan

adapter probe → capability requirements → capability resolution
              → bounded ProcessPlan 1.0 or 2.0

M authoring ceiling ─┐
Q evidence target  ──┼→ candidate bytes → behavior audit → R controls
P delivery choice  ──┘                         │
                                               ▼
                        bounded modules → exact user action → receipt/handoff

Axis	Meaning	Current executable boundary
M	Authoring cost ceiling	Counts clarification, research, source checks, independent calls, candidates, revisions, and evidence-triggered optional modules; it cannot claim quality or promotion.
Q	Evidence depth	Q0 is structure-only and quality-unverified; Q1/Q2 require a frozen QualityPlan; Q3 remains on the deep-evidence adapter.
R	Behavior risk	Rebuilt from current candidate bytes as a BehaviorRiskReport; its findings independently derive mandatory controls and capabilities.
P	Delivery depth	P0 handoff, P1 personal install, P2 isolated team package, or P3 formal transactional install.

ProcessPlan 2.0 accepts only create, optimize, and description_only; its authoring_budget, quality_level, current-byte behavior digest, and explicit delivery_target are separate fields. Q0 can compile only with P0_handoff and cannot contain formal campaigns, decisions, packages, or install modules. The formal candidate-free no_skill mode remains on ProcessPlan 1.0 until it has a versioned no-candidate behavior contract.

Every formal candidate path retains scope lock, execution authorization, current-byte risk binding, and the modules required by its selected Q and P. Optimize and description-only paths additionally require baseline snapshot and reproduction evidence. The no-skill path contains no candidate lifecycle.

The compiler's Q1 fast-lane predicate is deliberately narrow: create + Q1 + R0/R1 + no install + a recorded material_design_delta=false attestation + fully deterministic criteria. It never removes approval or safety gates. Formal graph validation reaches the fast lane by re-deriving the deterministic-suite predicate objectively and consuming the plan's tamper-evident design-delta attestation; a fast-lane promotion is tagged fast_lane_self_attested, so the release states that design sufficiency was declared by the caller rather than independently derived. Objective gate pass/fail and candidate gain are never self-reported.

WAIT_USER is a pause overlay, not a routing hub. workflow-pause issues an expiring, chain-head-bound, one-use continuation containing the exact origin gate, frozen-input digest, scope digest, risk digest, and nonce. workflow-resume can return only to that gate. Stale, replayed, cross-gate, expired, or input-drifted continuations fail closed. A continuation is neither user authentication nor a signature.

The public workflow-authorize and workflow-authorize-fixed commands accept only analysis_execution, candidate_generation, or install grants. Design approval, M/Q/P selection, the explicit P1/P2 claim-limit decision, and release acceptance are separate decision events or dedicated commands; they cannot be encoded as a broader grant.

Gate 1 records the shared M/Q/R/P edges in this order after SPEC_LOCKED and the current CANDIDATE_BUILT event:

workflow-behavior-reconcile
→ Q1/Q2 only: workflow-quality-lock
→ explicit user workflow-delivery-select
→ execute the selected P0/P1/P2/P3 sink
→ workflow-delivery-bind

These commands derive candidate, scope, risk, target, plan, and predecessor bindings from the recovered workflow and current objects; they do not accept caller-written digests as authority. workflow-delivery-bind reloads and target-specifically verifies the P0 handoff, P1 receipt, P2 manifest/current package, or committed P3 receipt. It records the verified edge only and never performs delivery itself.

Contracts and Evaluation

The runtime bundles 19 JSON Schema files:

• 18 contract schemas registered and auto-detected by the general validate command;
• one fixed model-judge-output schema consumed by the model-judge primitives.

The general validate command checks one document's structure, kind-specific self-digest, and contract-specific semantics. validate-graph additionally performs event-chain recovery, current-object resolution, and cross-object digest closure. A valid standalone quality-result remains a local consistency result, not formal authority; formal quality claims still require its exact QualityPlan and a rebuild from the raw evidence graph. The model-judge output is parsed from current response bytes against its frozen schema rather than accepted as a caller summary.

behavior-audit reads and hashes the current candidate bytes and derives R/C/K facts. Python is inspected with ast; Markdown intent and non-Python shell/script constructs are matched with regular-expression rules. Those matches are inferred heuristics, not a behavioral contract or runtime-safety certificate. Unknown, dynamic, or runtime-enforced behavior remains explicit and can block P1/P2.

For Q1/Q2, quality-plan derives targets from frozen pre-execution spec, suite, campaigns, handoff, and capability requirements. quality-evidence then rebuilds target-scoped results from the raw graph and current candidate bytes. A caller-provided summary is at most an equality assertion; release decisions rebuild the same authority themselves.

Production graph validation closes every applicable case × configuration × repetition × criterion cell. Deterministic gates require:

• evaluator role validator and kind script;
• exact manifest, implementation, and output-schema digests;
• an authorization- and journal-bound validator receipt;
• typed raw observations and a threshold result recomputed by the core.

Open model judgment is limited to frozen blind plans. When enabled, the contract requires at least two frozen judge slots, distinct implementation manifests, a frozen confidence threshold, the complete judge set for every case/repetition, and conflict_policy=human_review. In the current runtime that token means fail-closed handling only: a low-confidence or conflicting panel produces a completed inconclusive handoff; the engine does not create a review request, pause event, or human A/B resolution. There is currently no top-level model-judge-exec command and no claim of independent live dual-model conformance.

The script-validator executor runs only through a probed Darwin sandbox-exec backend. Its frozen default-deny profile grants reads to the sealed dependency tree, closed runtime roots, run-bound artifacts, and the system services/read paths inherited from Apple's private system.sb; it denies host writes, network access, and child-process creation. The backend, imported profile bytes, OS build, base policy, and effective artifact allowlist are digest-bound. Linux and other platforms fail closed for validator execution. CI therefore runs ordinary regressions on Ubuntu and a positive validator-execution lane on macOS before distribution builds may run. This narrow validator boundary is not separate-UID, memory, hermetic-host, or environment-reset isolation.

Host Support

Surface	Codex	Claude
Read-only probe	--version, --help, exec --help	--version, --help
Conservatively observed interfaces	noninteractive execution, JSONL, output schema, last-message output, ephemeral and read-only flags	print/noninteractive mode, stream JSON, no-session-persistence and bare flags
Explicit host executor	Implemented as authorization-boundcodex-exec with receipt capture and workspace-drift rejection	Implemented as authorization-bound claude-exec (--print, plan mode, no tools) with the same receipt and workspace-drift rejection
Automatic routing	Unverified	Unverified
Hermetic isolation, reset, sealed access	Unverified	Unverified
Stable token metrics, general artifacts	Unverified	Unverified
Installation activation semantics	Unverified	Unverified

Help output proves that an interface is exposed; it does not prove isolation semantics or model behavior. No host version is hard-coded as project truth. Use doctor for inspection and capability-probe for the journal-backed formal capability chain. Caller-supplied capability-seal records have imported_claims provenance and cannot establish positive execution capabilities.

Quick Start

Install a release package

Download the release archive and choose the package for your host: codex/ for Codex or claude/ for Claude. Install the contained skill-optimizer/ directory as a Skill in that host's configured Skill root, then invoke it with the host's explicit syntax below. The release package already contains the host-specific files; do not mix the Codex and Claude packages.

Invoke the Skill only through the host's explicit syntax. Ordinary conversation and similar intent must not auto-route to Skill Optimizer:

Codex:      $skill-optimizer <task>
Claude Code: /skill-optimizer <task>

For example:

$skill-optimizer Create a Codex Skill for X.
$skill-optimizer Optimize /path/to/skill.
/skill-optimizer Decide whether X should be a Skill.

The text after the explicit invocation remains natural language, but it can route only to the closed create, optimize, description_only, or no_skill task modes. This explicit-entry policy governs Skill Optimizer itself; it does not remove automatic-routing evaluation for candidate Skills.

Advanced CLI and automation

Inspect the composition root and local host interfaces:

python3 runtime/skill-optimizer/scripts/optimizer.py --help
python3 runtime/skill-optimizer/scripts/optimizer.py doctor \
  --host codex \
  --workspace "$PWD"

Build the trusted capability and process-plan chain:

python3 runtime/skill-optimizer/scripts/optimizer.py capability-probe \
  --host codex \
  --workspace "$PWD" \
  --record-id <report-id> \
  --journal <probe-journal.jsonl> \
  --output <capability-report.json>

python3 runtime/skill-optimizer/scripts/optimizer.py capability-resolve \
  --report <capability-report.json> \
  --requirements <capability-requirements.json> \
  --probe-journal <probe-journal.jsonl> \
  --output <capability-resolution.json>

python3 runtime/skill-optimizer/scripts/optimizer.py process-plan \
  --input <process-input.json> \
  --report <capability-report.json> \
  --requirements <capability-requirements.json> \
  --resolution <capability-resolution.json> \
  --probe-journal <probe-journal.jsonl> \
  --workspace "$PWD" \
  --output <process-plan.json>

For non-R0 plans, <process-input.json> must include the frozen risk_findings array. The compiler derives the mandatory capability floor from those findings, binds risk_findings_digest into the plan, and re-resolves the capability chain from the supplied report, requirements contract, and probe journal.

For an existing candidate, audit its current bytes and compile the explicit M/Q/R/P projection:

python3 runtime/skill-optimizer/scripts/optimizer.py behavior-audit \
  --candidate <candidate-skill> \
  --output <behavior-risk-report.json>

python3 runtime/skill-optimizer/scripts/optimizer.py process-plan-v2 \
  --input <m-q-p-input.json> \
  --candidate <candidate-skill> \
  --report <capability-report.json> \
  --requirements <capability-requirements.json> \
  --resolution <capability-resolution.json> \
  --probe-journal <probe-journal.jsonl> \
  --workspace "$PWD" \
  --output <process-plan-v2.json>

Q1/Q2 also pass --quality-plan <quality-plan.json>, derived by quality-plan from frozen pre-execution inputs. Use quality-evidence to rebuild the corresponding current-byte result. Q0 must omit the QualityPlan and select only P0_handoff.

The lightweight delivery lanes have closed command chains:

Q0/P0: draft-target → draft-authorize → draft-create
P1:    personal-install-decision → personal-install-authorize
       → personal-install → optional personal-install-rollback
P2:    team-delivery-target → team-delivery-decision
       → team-delivery-authorize → team-delivery-build
       → team-delivery-verify

draft-create and the P1/P2 sinks read library-derived fixed workflow logs; they do not accept caller-selected log paths. Grants are consumed once before the first durable/mutating transaction step or before a successful P2 build returns. P1 and P2 decision commands require --accept-quality-unverified. Inspect each subcommand's --help for its closed inputs.

Validate a complete evidence graph:

python3 runtime/skill-optimizer/scripts/optimizer.py validate-graph \
  --spec <skill-spec.json> \
  --suite <eval-suite.json> \
  --campaigns <campaigns.json> \
  --runs <runs.jsonl> \
  --assessments <assessments.jsonl> \
  --events <workflow-events.jsonl> \
  --capability-report <capability-report.json> \
  --capability-requirements <capability-requirements.json> \
  --capability-resolution <capability-resolution.json> \
  --process-plan <process-plan.json> \
  --capability-probe-journal <probe-journal.jsonl>

Build and reverify a distribution:

python3 runtime/skill-optimizer/scripts/optimizer.py package \
  --host codex \
  --source <candidate-skill> \
  --output <dist-dir> \
  --manifest <manifest.json>

python3 runtime/skill-optimizer/scripts/optimizer.py package-verify \
  --candidate <dist-dir> \
  --manifest <manifest.json> \
  --output <package-receipt.json>

Repository distributions are generated artifacts, not source files: dist/ is ignored and must not be committed. CI first runs both unittest suites on Ubuntu and the positive Darwin validator-execution suite on macOS. The distribution job depends on both lanes, builds both host profiles directly from runtime/skill-optimizer/, reverifies them with package-verify, and uploads a permission-preserving archive containing both trees, manifests, and receipts. Use a fresh output root to reproduce the same build locally because the packager intentionally refuses to overwrite an existing distribution:

DIST_ROOT="$(mktemp -d)"
mkdir -p "$DIST_ROOT/codex" "$DIST_ROOT/claude"

for host in codex claude; do
  python3 runtime/skill-optimizer/scripts/optimizer.py package \
    --host "$host" \
    --source runtime/skill-optimizer \
    --output "$DIST_ROOT/$host/skill-optimizer" \
    --manifest "$DIST_ROOT/$host/skill-optimizer.manifest.json"
  python3 runtime/skill-optimizer/scripts/optimizer.py package-verify \
    --candidate "$DIST_ROOT/$host/skill-optimizer" \
    --manifest "$DIST_ROOT/$host/skill-optimizer.manifest.json" \
    --output "$DIST_ROOT/$host/package-receipt.json"
done

Release and installation follow this trust chain:

formal decision
→ fresh package verification receipt
→ formal release snapshot
→ explicit user acceptance
→ exact InstallActionTarget
→ separate user install grant
→ transactional install
→ smoke/digest outcome or rollback/recovery

Use each command's --help for its closed input contract. The CLI derives the exact install authorization target but does not fabricate a user grant. Git commit is also a separately authorized action and has no execution command in the current control plane.

Verification

Run both regression suites without writing Python cache files:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s dev/optimizer-evals \
  -p 'test_*.py' \
  -v

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s dev/schema-tests \
  -p 'test_*.py' \
  -v

No test count, package file count, or digest is hard-coded here. Distribution facts are receipt-based: build from the current runtime source and use package-verify; its manifest version, source-projection digest, tree digest, byte/file counts, read-only flags, and receipt digest apply only to those exact bytes. A CI artifact is build evidence for its source revision, not a substitute for a tagged release.

The root VERSION file is the sole file source for the repository release version. Skill frontmatter carries no project version; schema, object, adapter, and manifest versions evolve independently. A release tag must equal v + VERSION and point to the verified clean commit.

Repository Layout

.
├── SKILL.md                 # Lightweight repository entry point
├── VERSION                  # Authoritative repository release version
├── LICENSE                  # Project license included in runtime distributions
├── runtime/skill-optimizer/ # Canonical Skill and deterministic control plane
├── dev/                     # Contract, integration, packaging, and recovery tests
├── .github/workflows/ci.yml # Builds and verifies untracked host distributions
└── WORKFLOW_SPEC.md         # Authoritative executable-contract specification

License

This project is distributed under the MIT-NonCommercial License. Commercial use, in whole or in part, requires prior written permission from the copyright holder.

References

Core academic papers

1. SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks

   Xiangyi Li et al., arXiv:2602.12670 (2026).

   Its central empirical result—that carefully authored skills materially outperform unconstrained automatic skill generation—supports this project's risk-adjusted degrees of freedom, deterministic scripting, isolated validation, duplicate discovery, and explicit/implicit requirement analysis.

2. SkillGenBench: Benchmarking Skill Generation Pipelines for LLM Agents

   Yifan Zhou et al., arXiv:2605.18693 (2026).

   Its pipeline-evaluation framing informs Skill Optimizer's TRIAGE and DEFINE stages, resource planning, and measurable create/optimize iteration loop.

Official specifications and documentation

• Anthropic Skill Creator — source for real-task evaluation, baseline comparison, artifact-first review, execution traces, human feedback, holdouts, and the principle that the best version is not necessarily the latest version.
• OpenAI Codex Skills documentation — source for context discipline, progressive disclosure, calibrated degrees of freedom, deterministic scripts, resource layering, and validation guidance.
• Zhipu GLM Open Platform LLM Skill API documentation — reference for cross-host adaptation boundaries.
• Agent Skills Open Standard — reference for portable skill structure and host-neutral authoring conventions.

Community reference projects

Skill Optimizer also learns from the strengths and limitations of adjacent community tools:

• FrancyJGLisboa/agent-skill-creator — motivated the separation of routing and execution, two-plane verification, and same-batch counterfactual comparison.
• sandiiarov/skill-creator — informed deterministic checks first and focused must-pass gates.
• AGI-comming/functional-skill-creator — informed the additional execution-trace, human-feedback, failure-attribution, and bounded-iteration safeguards.
• okjpg/skill-creator — informed maintenance rules for volatile dependencies, degradation paths, and avoiding meaningless version pinning.
• bilibili/skill-eval & skill-benchmark (closed source) — informed concrete authoring rules, iteration flow, regression questions, specification contracts, review protocols, maintenance checks, and global decision principles.

---

中文

项目简介

融合亮点，而不是缝合成庞大笨重的工具。 Skill Optimizer 将下列工作中最有价值的思想收敛为一个职责清晰、边界受控的控制面；每项机制只有在证据、风险与宿主能力足以支撑其成本时才启用，不以堆叠功能为目标。特别鸣谢与参考文献 →

Skill Optimizer 将 Skill 创建视为受控工程流程，而不是一次 Prompt 润色。它既可以证明候选应当发布，也可以证明应保留旧 Skill，或根本不应创建 Skill。所有声明都被限制在可由冻结输入、receipt 与当前产物字节重建的证据边界内。

更轻量、面向宿主使用的 Skill Forge 已迁移到独立仓库 AlexBybye/skill-forge。本仓库保留更完整的 Skill Optimizer 控制面历史与 runtime。

当前源码版本为 4.0.2。项目级版本以 VERSION 为准；manifest 与各契约的 schema version 独立演进。在最终回归、显式 core refreeze、包 receipt、clean commit 与匹配的 v4.0.2 tag 全部完成前，当前工作树不是已发布的 4.0.2 release。

runtime 是仅依赖 Python 标准库的确定性控制面。工作流状态图固定；内容寻址的 ProcessPlan 只能从闭合模板中选择有界模块 DAG，并不是任意可配置的 Profile 解释器。新增的 ProcessPlan 2.0 显式拆开编写成本 M、质量证据 Q、行为派生风险 R 与交付深度 P；旧 ProcessPlan 1.0 继续兼容，并承载正式 no_skill 路径。

已实现边界

确定性控制面已经实现四种正式任务模式、受能力事实约束的 ProcessPlan 1.0/2.0 编译、有界 M 编写记录、经授权的 Q0/P0 草稿、当前字节行为风险报告、Q1/Q2 QualityPlan 与证据重建、受限 P1 个人安装、隔离 P2 团队包、链绑定暂停恢复、经授权的确定性 validator、显式只读 Codex 与 Claude 执行，以及既有 P3 正式发布/安装路径。两个宿主执行器都是授权绑定、捕获 receipt、拒绝 workspace 漂移；均不声称 OS 级隔离、自动路由或模型 conformance。

Q0、P1 与 P2 的声明上限是设计边界。Q0 只产生通过结构检查的 AuthoringHandoff，不产生正式质量证据。P1/P2 都要求用户显式接受 quality_unverified；P1 不证明宿主激活或崩溃恢复，P2 不安装、不激活，也不证明宿主兼容性或自动路由。

自动 Skill 路由、密封或因果隔离、环境复位、sealed holdout 访问控制、通用产物收集、稳定 token 指标、网络控制、付费真实模型 conformance，以及安装后的宿主激活仍未验证。未知的强制能力会 fail closed；只有预先声明的降级路径可以移除其依赖声明。

本地工作流与事务 journal 只能提供篡改可见性，不是数字签名；拥有同等文件写权限的主体可以整体替换一条链。

事务安装会在记录 committed 前同步 regular payload 文件、目录及受影响的 rename 父目录。该 durability 只由 POSIX fsync 成功界定，不保证设备写缓存、突然断电、网络文件系统或外部存储屏障。

核心不变量

• 先有证据再发布：裁决必须从完整 evidence graph 与当前包字节重建。
• M、Q、R、P 相互独立：M 限制编写工作，Q 选择证据深度，当前候选字节派生 R 及其必选控制，用户选择 P 交付深度。低 Q 或浅 P 都不能删除安全要求。
• 确定性门只能由确定性证据通过：gate criterion 必须精确绑定冻结的 script validator，并由核心重算有类型阈值。
• 统计单位是 case：repetition 数或 assessment 行数不能制造额外权重。
• 停止是一等结果：no_skill_confirmed 与 keep_baseline 必须有证据，不能由调用方自报布尔值。
• 动作授权必须精确：公共 workflow grant 只存在 analysis_execution、candidate_generation 与 install 三类。额度/设计/交付选择和 release acceptance 是有类型的用户裁决，不是通用 grant。
• 安装是另一项动作：接受发布不等于允许安装，安装授权只绑定一个精确 target 与前态。

四种正式任务模式

模式	精确行为
create	构建并评测候选；已证明的基线充分性，或迭代结束后的候选无收益，可得到no_skill_confirmed。
optimize	候选构建前必须完成不可变基线快照、复现与诊断；已证明无收益时得到keep_baseline。
description_only	沿用优化基线路径，并额外通过字节级 description-only 门。
no_skill	不构建、渲染、打包或安装候选；冻结的 baseline-only probe 必须证明充分性，才能得到no_skill_confirmed。

reuse_candidate 只是 limited handoff 建议，不是正式 ProcessPlan 模式；验证是工作流阶段，也不是第五种模式。

工作流与 ProcessPlan

adapter probe → capability requirements → capability resolution
              → bounded ProcessPlan 1.0 或 2.0

M 编写上限 ─┐
Q 证据目标 ──┼→ candidate bytes → behavior audit → R controls
P 交付选择 ──┘                         │
                                      ▼
                   bounded modules → 精确用户动作 → receipt/handoff

轴	含义	当前可执行边界
M	编写成本上限	记录澄清、研究、来源核验、独立调用、候选、修订及有证据触发的可选模块；不得声明质量或 promotion。
Q	证据深度	Q0 只有结构检查且质量未验证；Q1/Q2 必须绑定冻结 QualityPlan；Q3 保留既有 deep-evidence adapter。
R	行为风险	从当前候选字节重建 BehaviorRiskReport；findings 独立派生必选控制与能力。
P	交付深度	P0 handoff、P1 个人安装、P2 隔离团队包或 P3 正式事务安装。

ProcessPlan 2.0 只接受 create、optimize 与 description_only；authoring_budget、quality_level、当前字节行为摘要和显式 delivery_target 是互相分离的字段。Q0 只能编译为 P0_handoff，并禁止 formal campaign、decision、package 与 install 模块。正式无候选 no_skill 在具有版本化 no-candidate behavior contract 前继续走 ProcessPlan 1.0。

每条正式候选路径都保留 scope lock、execution authorization、当前字节风险绑定及所选 Q/P 要求的模块。optimize 和 description-only 路径还必须具有基线快照及复现证据；no-skill 路径完全不包含候选生命周期。

编译器的 Q1 fast-lane 谓词非常严格：create + Q1 + R0/R1 + 未请求安装 + 记录的 material_design_delta=false 声明 + 全部判据可确定性，并且不会删除审批或安全门。正式 graph validator 通过独立重算“判据是否全为确定性”这一客观事实、并消费 plan 中防篡改记录的设计差异声明来到达快车道；fast-lane 发布会带上 fast_lane_self_attested 标记，如实说明设计充分性是调用方声明、而非独立推导。客观 gate 的 pass/fail 与候选增益从不自报。

WAIT_USER 是暂停 overlay，不是任意路由中心。workflow-pause 生成绑定当前链头、单次使用且会过期的 continuation，其中包含精确 origin gate、冻结输入摘要、scope digest、risk digest 与 nonce。workflow-resume 只能回到该 gate；旧链头、重放、跨 gate、过期或输入漂移都会 fail closed。continuation 既不是用户身份认证，也不是签名。

公共 workflow-authorize 与 workflow-authorize-fixed 只接受 analysis_execution、candidate_generation 或 install grant。design approval、M/Q/P 选择、P1/P2 声明上限接受和 release acceptance 必须使用各自的 decision event 或专用命令，不能编码成更宽的 grant。

Gate 1 在 SPEC_LOCKED 与当前 CANDIDATE_BUILT event 之后按以下顺序记录共享 M/Q/R/P 边：

workflow-behavior-reconcile
→ 仅 Q1/Q2：workflow-quality-lock
→ 显式用户 workflow-delivery-select
→ 执行所选 P0/P1/P2/P3 sink
→ workflow-delivery-bind

这些命令从已恢复 workflow 与当前对象派生 candidate、scope、risk、target、plan 及前序绑定，不接受调用方 digest 作为权威。workflow-delivery-bind 会按目标重新读取并验证 P0 handoff、P1 receipt、P2 manifest/当前 package 或已提交 P3 receipt；它只记录已验证边，本身不执行 delivery。

契约与评测

runtime 内置 19 个 JSON Schema 文件：

• 通用 validate 命令注册并可自动识别的 18 类 contract Schema；
• model-judge primitive 单独消费的 1 个固定 model-judge-output Schema。

通用 validate 校验单个文档的结构、按类型选择的自摘要及该类型可独立证明的语义；validate-graph 另外执行事件链恢复、真实对象解析及跨对象摘要闭合。单独通过 quality-result 校验只证明局部一致性，不授予正式质量权威；正式质量声明仍须绑定精确 QualityPlan 并从原始 evidence graph 重建。model-judge 输出会依据冻结 Schema 从当前响应字节重新解析，而不是接受调用方摘要。

behavior-audit 读取并散列当前候选字节，派生 R/C/K 事实。Python 使用 ast 检查；Markdown 意图与非 Python shell/script 构造使用正则规则匹配。这些匹配只是 inferred 启发式，不是行为契约或运行时安全证书。unknown、dynamic 或需要 runtime enforcement 的行为会保持显式，并可阻断 P1/P2。

Q1/Q2 的 quality-plan 从冻结的执行前 spec、suite、campaign、handoff 与 capability requirements 派生 targets；quality-evidence 再从原始 graph 和当前候选字节重建 target-scoped 结果。调用方提供的 summary 最多只能作为相等性断言；release decision 会自行重建同一权威事实。

production graph 校验会闭合所有适用的 case × configuration × repetition × criterion 单元。确定性 gate 必须同时具备：

• evaluator role 为 validator、kind 为 script；
• 精确的 manifest、implementation 与 output-schema digest；
• 绑定授权和 journal 的 validator receipt；
• 原始有类型 observation，以及由核心重算的 threshold 结果。

开放式模型评审只允许使用冻结的 blind plan。启用时，契约要求至少两个冻结 judge slot、不同 implementation manifest、冻结 confidence threshold、每个 case/repetition 完整的 judge 集，以及 conflict_policy=human_review。当前该 token 只表示 fail-closed 策略：低置信度或冲突面板统一产出已完成的 inconclusive handoff；engine 不会创建 review request、暂停事件或人工 A/B 裁决。当前没有顶层 model-judge-exec 命令，也不声明已经完成独立真实双模型 conformance。

script validator 仅可通过探针验证的 Darwin sandbox-exec 后端执行。冻结的 default-deny profile 只读开放 sealed dependency tree、闭合运行时根、本次 run 绑定的 artifact，以及 Apple 私有 system.sb 自身授予的系统服务/读取路径，并拒绝宿主写入、网络访问与创建子进程；后端、imported profile 字节、OS build、基础策略和有效 artifact allowlist 均绑定摘要。Linux 与其他平台执行 validator 时 fail closed。CI 因此在 Ubuntu 运行普通回归，并在 macOS 运行 validator 正向执行 lane，两者通过后 distribution job 才能运行。这一窄化边界不等于独立 UID、内存、宿主 hermetic 或环境复位隔离。

宿主支持

能力面	Codex	Claude
只读探针	--version、--help、exec --help	--version、--help
保守确认的接口	非交互执行、JSONL、输出 Schema、last-message、ephemeral 与 read-only flag	print/非交互模式、stream JSON、no-session-persistence 与 bare flag
显式宿主执行器	已实现为授权绑定的codex-exec，包含 receipt 捕获与 workspace 漂移拒绝	已实现为授权绑定的 claude-exec（--print、plan 模式、禁用工具），同样捕获 receipt 并拒绝 workspace 漂移
自动路由	未验证	未验证
密封隔离、复位、sealed access	未验证	未验证
稳定 token、通用产物	未验证	未验证
安装后的激活语义	未验证	未验证

帮助文本只能证明接口暴露，不能证明隔离语义或模型行为。项目不硬编码宿主版本；doctor 用于检查，capability-probe 才生成有 journal 支撑的正式能力链。调用方提供的 capability-seal 记录只能是 imported_claims provenance，不能建立正向执行能力。

快速开始

安装 release 包

下载 release 压缩包并按宿主选择对应目录：Codex 使用 codex/，Claude 使用 claude/。将其中的 skill-optimizer/ 目录作为 Skill 安装到该宿主配置的 Skill root，然后使用下面的显式语法调用。release 包已经包含宿主专用文件，不要混用 Codex 与 Claude 两个包。

只通过宿主的显式语法调用本 Skill；普通对话和相似意图不得自动路由到 Skill Optimizer：

Codex：      $skill-optimizer <任务>
Claude Code：/skill-optimizer <任务>

例如：

$skill-optimizer 为 X 创建一个 Codex Skill。
$skill-optimizer 优化 /path/to/skill。
/skill-optimizer 判断 X 是否值得做成 Skill。

显式调用后的文本仍可使用自然语言，但只能进入闭合的 create、optimize、description_only 或 no_skill task mode。这项显式入口策略只约束 Skill Optimizer 自身，不会删除对候选 Skill 的 automatic-routing 评测。

高级 CLI 与自动化

查看组合入口和本地宿主接口：

python3 runtime/skill-optimizer/scripts/optimizer.py --help
python3 runtime/skill-optimizer/scripts/optimizer.py doctor \
  --host codex \
  --workspace "$PWD"

建立可信 capability 与 ProcessPlan 链：

python3 runtime/skill-optimizer/scripts/optimizer.py capability-probe \
  --host codex \
  --workspace "$PWD" \
  --record-id <report-id> \
  --journal <probe-journal.jsonl> \
  --output <capability-report.json>

python3 runtime/skill-optimizer/scripts/optimizer.py capability-resolve \
  --report <capability-report.json> \
  --requirements <capability-requirements.json> \
  --probe-journal <probe-journal.jsonl> \
  --output <capability-resolution.json>

python3 runtime/skill-optimizer/scripts/optimizer.py process-plan \
  --input <process-input.json> \
  --report <capability-report.json> \
  --requirements <capability-requirements.json> \
  --resolution <capability-resolution.json> \
  --probe-journal <probe-journal.jsonl> \
  --workspace "$PWD" \
  --output <process-plan.json>

对于非 R0 计划，<process-input.json> 必须携带冻结的 risk_findings 数组。编译器从 findings 派生 mandatory capability floor，把 risk_findings_digest 绑定进计划，并用 report、requirements contract 与 probe journal 重新解析能力链。

对于已经存在的候选，先审计当前字节，再编译显式 M/Q/R/P 投影：

python3 runtime/skill-optimizer/scripts/optimizer.py behavior-audit \
  --candidate <candidate-skill> \
  --output <behavior-risk-report.json>

python3 runtime/skill-optimizer/scripts/optimizer.py process-plan-v2 \
  --input <m-q-p-input.json> \
  --candidate <candidate-skill> \
  --report <capability-report.json> \
  --requirements <capability-requirements.json> \
  --resolution <capability-resolution.json> \
  --probe-journal <probe-journal.jsonl> \
  --workspace "$PWD" \
  --output <process-plan-v2.json>

Q1/Q2 还必须传入 --quality-plan <quality-plan.json>；该对象由 quality-plan 从冻结执行前输入派生。使用 quality-evidence 重建对应的当前字节结果。Q0 必须省略 QualityPlan，并且只能选择 P0_handoff。

轻量交付 lane 具有闭合命令链：

Q0/P0: draft-target → draft-authorize → draft-create
P1:    personal-install-decision → personal-install-authorize
       → personal-install → 可选 personal-install-rollback
P2:    team-delivery-target → team-delivery-decision
       → team-delivery-authorize → team-delivery-build
       → team-delivery-verify

draft-create 和 P1/P2 sink 读取库派生的固定 workflow log，不接受调用方选择的日志路径。grant 在首个持久/变更事务步骤前或 P2 build 成功返回前一次性消费。P1/P2 decision 命令必须带 --accept-quality-unverified。每个子命令的闭合输入以其 --help 为准。

校验完整 evidence graph：

python3 runtime/skill-optimizer/scripts/optimizer.py validate-graph \
  --spec <skill-spec.json> \
  --suite <eval-suite.json> \
  --campaigns <campaigns.json> \
  --runs <runs.jsonl> \
  --assessments <assessments.jsonl> \
  --events <workflow-events.jsonl> \
  --capability-report <capability-report.json> \
  --capability-requirements <capability-requirements.json> \
  --capability-resolution <capability-resolution.json> \
  --process-plan <process-plan.json> \
  --capability-probe-journal <probe-journal.jsonl>

构建并复验发行物：

python3 runtime/skill-optimizer/scripts/optimizer.py package \
  --host codex \
  --source <candidate-skill> \
  --output <dist-dir> \
  --manifest <manifest.json>

python3 runtime/skill-optimizer/scripts/optimizer.py package-verify \
  --candidate <dist-dir> \
  --manifest <manifest.json> \
  --output <package-receipt.json>

仓库发行物是生成产物，不是源文件：dist/ 已被忽略，不得提交。CI 先在 Ubuntu 运行两组 unittest，并在 macOS 运行 Darwin validator 正向执行测试。distribution job 依赖这两个 lane，通过后才从 runtime/skill-optimizer/ 为两个宿主构建发行物， 再用 package-verify 复验，并上传一份保留权限信息的归档，其中包含两份发行树、 manifest 和 receipt。由于打包器刻意拒绝覆盖现有发行树，本地复现时应使用全新输出目录：

DIST_ROOT="$(mktemp -d)"
mkdir -p "$DIST_ROOT/codex" "$DIST_ROOT/claude"

for host in codex claude; do
  python3 runtime/skill-optimizer/scripts/optimizer.py package \
    --host "$host" \
    --source runtime/skill-optimizer \
    --output "$DIST_ROOT/$host/skill-optimizer" \
    --manifest "$DIST_ROOT/$host/skill-optimizer.manifest.json"
  python3 runtime/skill-optimizer/scripts/optimizer.py package-verify \
    --candidate "$DIST_ROOT/$host/skill-optimizer" \
    --manifest "$DIST_ROOT/$host/skill-optimizer.manifest.json" \
    --output "$DIST_ROOT/$host/package-receipt.json"
done

发布与安装遵循以下信任链：

formal decision
→ fresh package verification receipt
→ formal release snapshot
→ 显式用户接受
→ 精确 InstallActionTarget
→ 单独的用户安装授权
→ 事务安装
→ smoke/digest 结果或 rollback/recovery

每个命令的闭合输入契约以其 --help 为准。CLI 会派生精确 install authorization target，但不会伪造用户 grant。Git commit 同样需要独立授权，当前控制面没有 Git commit 执行命令。

验证

禁用 Python 缓存写入后运行两组回归：

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s dev/optimizer-evals \
  -p 'test_*.py' \
  -v

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s dev/schema-tests \
  -p 'test_*.py' \
  -v

README 不硬编码测试数、包文件数或发行摘要。发行事实以 receipt 为准：从当前 runtime 源构建并执行 package-verify；其中的 manifest version、source-projection digest、tree digest、文件/字节数、read-only flag 与 receipt digest 只对该精确字节集成立。CI artifact 只是对应源码 revision 的构建证据，不能代替正式的带 tag 发布。

根目录 VERSION 是仓库发行版本的唯一文件真值。Skill frontmatter 不承载项目版本；schema、object、adapter 与 manifest version 独立演进。release tag 必须等于 v + VERSION，并指向经过验证的 clean commit。

仓库结构

.
├── SKILL.md                 # 轻量仓库入口
├── VERSION                  # 仓库发行版本的唯一文件真值
├── LICENSE                  # 项目许可证，并随 runtime 发行物分发
├── runtime/skill-optimizer/ # canonical Skill 与确定性控制面
├── dev/                     # 契约、集成、打包与恢复测试
├── .github/workflows/ci.yml # 构建并复验不入库的宿主发行物
└── WORKFLOW_SPEC.md         # 可执行契约的权威规格

许可证

本项目采用 MIT-NonCommercial License。任何全部或部分商业使用均需事先获得版权所有者的书面许可。

参考文献

核心学术论文

1. SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks

   Xiangyi Li et al., arXiv:2602.12670 (2026)。

   其核心实证表明，经过审慎编写的 Skill 明显优于无约束的自动生成；这直接支撑本项目按风险设置自由度、确定性任务脚本化、隔离验证、创建前查重，以及显式/隐式需求分析等设计。

2. SkillGenBench: Benchmarking Skill Generation Pipelines for LLM Agents

   Yifan Zhou et al., arXiv:2605.18693 (2026)。

   其生成管线评测框架为 Skill Optimizer 的 TRIAGE、DEFINE、资源规划，以及可度量的创建/优化迭代闭环提供了方法依据。

官方规范与文档

• Anthropic Skill Creator —— 真实任务、基线对照、产物优先、执行轨迹、人类反馈、留出集，以及“最佳版本不等于最后版本”等原则的主要来源。
• OpenAI Codex Skills 文档 —— 上下文节制、渐进披露、自由度约束、确定性脚本、资源分层与验证指南的主要来源。
• 智谱 GLM 开放平台 LLM 技能 API 开发文档 —— 跨宿主适配边界的参考来源。
• Agent Skills Open Standard —— 可移植 Skill 结构与宿主中立编写约定的参考标准。

社区参考项目

Skill Optimizer 也吸收了相邻社区工具的优点，并在可复现性、证据边界和失败恢复方面继续补强：

• FrancyJGLisboa/agent-skill-creator —— 启发了路由与执行分离、双平面验证和同批次反事实比较。
• sandiiarov/skill-creator —— 启发了确定性检查优先与聚焦 must-pass gate。
• AGI-comming/functional-skill-creator —— 启发了进一步加入执行轨迹、人类反馈、失败归因和有界迭代保护。
• okjpg/skill-creator —— 启发了易变依赖、降级路径和避免无意义版本锁定等维护原则。
• bilibili/skill-eval & skill-benchmark（闭源） —— 启发了具体编写规则、迭代流程、回归问题库、规范契约、审查协议、维护检查和全局裁决原则。