diff --git a/.gitignore b/.gitignore
index 2c74bca..b4744fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,6 +21,7 @@ tests/tmp_system_model/
tests/tmp_security/
tests/tmp_baseline_compare.*
reports/release_snapshots/
+reports/telemetry_events.jsonl
.yao/
# Local business-skill experiments belong outside this meta-skill repo unless promoted intentionally.
diff --git a/Makefile b/Makefile
index 4095fab..659bca1 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@ PYTHON ?= python3
LOCAL_SKILL_INSTALL_DIR ?= $(HOME)/.agents/skills.disabled/yao-meta-skill
ACTIVE_SKILL_INSTALL_DIR ?= $(HOME)/.agents/skills/yao-meta-skill
-.PHONY: eval eval-suite route-scorecard route-confusion-check description-optimization judge-blind-eval description-optimization-check promotion-check yao-cli-check skill-overview-check skill-report-metrics-check skill-report-charts-check skill-ir-check output-eval-check runtime-conformance-check trust-check skill-atlas-check review-viewer-check review-studio-check feedback-check baseline-compare-check reference-scan-check github-benchmark-scan-check intent-confidence-check reference-synthesis-check output-risk-profile-check artifact-design-profile-check prompt-quality-profile-check system-model-check iteration-directions-check description-drift-history iteration-ledger results-panel regression-history context-reports portability-report portability-check failure-regression-check package-check package-failure-check security-boundary-check local-install-sync-check snapshot-check validate lint governance-check resource-boundary-check quality-check sync-local-install sync-active-install test ci-test clean
+.PHONY: eval eval-suite route-scorecard route-confusion-check description-optimization judge-blind-eval description-optimization-check promotion-check yao-cli-check skill-overview-check skill-report-metrics-check skill-report-charts-check skill-ir-check compiler-check output-eval-check output-execution-check output-review-adjudication-check runtime-conformance-check runtime-permission-check trust-check skill-atlas-check registry-audit-check package-verify-check install-simulation-check upgrade-check review-viewer-check review-studio-check feedback-check adoption-drift-check review-waivers-check review-annotations-check baseline-compare-check reference-scan-check github-benchmark-scan-check intent-confidence-check reference-synthesis-check output-risk-profile-check artifact-design-profile-check prompt-quality-profile-check system-model-check iteration-directions-check description-drift-history iteration-ledger results-panel regression-history context-reports portability-report portability-check failure-regression-check package-check package-failure-check security-boundary-check local-install-sync-check snapshot-check validate lint governance-check resource-boundary-check quality-check sync-local-install sync-active-install test ci-test clean
eval:
$(PYTHON) scripts/trigger_eval.py --description-file evals/improved_description.txt --cases evals/trigger_cases.json --baseline-description-file evals/baseline_description.txt
@@ -43,18 +43,42 @@ skill-report-charts-check:
skill-ir-check:
$(PYTHON) tests/verify_skill_ir.py
+compiler-check:
+ $(PYTHON) tests/verify_compile_skill.py
+
output-eval-check:
$(PYTHON) tests/verify_output_eval_lab.py
+output-execution-check:
+ $(PYTHON) tests/verify_output_execution_runs.py
+
+output-review-adjudication-check:
+ $(PYTHON) tests/verify_output_review_adjudication.py
+
runtime-conformance-check:
$(PYTHON) tests/verify_conformance_suite.py
+runtime-permission-check:
+ $(PYTHON) tests/verify_runtime_permission_probes.py
+
trust-check:
$(PYTHON) tests/verify_trust_check.py
skill-atlas-check:
$(PYTHON) tests/verify_skill_atlas.py
+registry-audit-check:
+ $(PYTHON) tests/verify_registry_audit.py
+
+package-verify-check:
+ $(PYTHON) tests/verify_package_verification.py
+
+install-simulation-check:
+ $(PYTHON) tests/verify_install_simulation.py
+
+upgrade-check:
+ $(PYTHON) tests/verify_upgrade_check.py
+
review-viewer-check:
$(PYTHON) tests/verify_review_viewer.py
@@ -64,6 +88,15 @@ review-studio-check:
feedback-check:
$(PYTHON) tests/verify_feedback.py
+adoption-drift-check:
+ $(PYTHON) tests/verify_adoption_drift.py
+
+review-waivers-check:
+ $(PYTHON) tests/verify_review_waivers.py
+
+review-annotations-check:
+ $(PYTHON) tests/verify_review_annotations.py
+
baseline-compare-check:
$(PYTHON) tests/verify_baseline_compare.py
@@ -154,11 +187,11 @@ sync-local-install:
sync-active-install:
$(PYTHON) scripts/sync_local_install.py --install-dir "$(ACTIVE_SKILL_INSTALL_DIR)"
-test: eval eval-suite route-scorecard route-confusion-check description-optimization description-optimization-check promotion-check yao-cli-check skill-overview-check skill-report-metrics-check skill-report-charts-check skill-ir-check output-eval-check runtime-conformance-check trust-check skill-atlas-check review-viewer-check review-studio-check feedback-check baseline-compare-check reference-scan-check github-benchmark-scan-check intent-confidence-check reference-synthesis-check output-risk-profile-check artifact-design-profile-check prompt-quality-profile-check system-model-check iteration-directions-check description-drift-history iteration-ledger regression-history context-reports portability-report portability-check failure-regression-check package-check package-failure-check security-boundary-check local-install-sync-check snapshot-check validate lint governance-check resource-boundary-check quality-check
+test: eval eval-suite route-scorecard route-confusion-check description-optimization description-optimization-check promotion-check yao-cli-check skill-overview-check skill-report-metrics-check skill-report-charts-check skill-ir-check compiler-check output-eval-check output-execution-check output-review-adjudication-check runtime-conformance-check runtime-permission-check trust-check skill-atlas-check registry-audit-check package-verify-check install-simulation-check upgrade-check review-viewer-check review-studio-check feedback-check adoption-drift-check review-waivers-check review-annotations-check baseline-compare-check reference-scan-check github-benchmark-scan-check intent-confidence-check reference-synthesis-check output-risk-profile-check artifact-design-profile-check prompt-quality-profile-check system-model-check iteration-directions-check description-drift-history iteration-ledger regression-history context-reports portability-report portability-check failure-regression-check package-check package-failure-check security-boundary-check local-install-sync-check snapshot-check validate lint governance-check resource-boundary-check quality-check
ci-test:
$(PYTHON) scripts/ci_test.py
clean:
- rm -rf dist tests/tmp tests/tmp_snapshot tests/tmp_cli tests/tmp_skill_overview tests/tmp_skill_report_metrics tests/tmp_skill_report_charts tests/tmp_skill_ir tests/tmp_output_eval tests/tmp_conformance tests/tmp_trust tests/tmp_skill_atlas tests/tmp_reference_scan tests/tmp_iteration_directions tests/tmp_review_viewer tests/tmp_review_studio tests/tmp_feedback tests/tmp_github_benchmark_scan tests/tmp_intent_confidence tests/tmp_reference_synthesis tests/tmp_output_risk_profile tests/tmp_artifact_design_profile tests/tmp_prompt_quality_profile tests/tmp_system_model tests/tmp_security tests/tmp_baseline_compare.json tests/tmp_baseline_compare.md
+ rm -rf dist tests/tmp tests/tmp_snapshot tests/tmp_cli tests/tmp_skill_overview tests/tmp_skill_report_metrics tests/tmp_skill_report_charts tests/tmp_skill_ir tests/tmp_compile_skill tests/tmp_output_eval tests/tmp_output_execution tests/tmp_output_review_adjudication tests/tmp_conformance tests/tmp_runtime_permission tests/tmp_trust tests/tmp_skill_atlas tests/tmp_registry tests/tmp_package_verification tests/tmp_install_simulation tests/tmp_upgrade_check tests/tmp_reference_scan tests/tmp_iteration_directions tests/tmp_review_viewer tests/tmp_review_studio tests/tmp_feedback tests/tmp_adoption_drift tests/tmp_review_waivers tests/tmp_review_annotations tests/tmp_github_benchmark_scan tests/tmp_intent_confidence tests/tmp_reference_synthesis tests/tmp_output_risk_profile tests/tmp_artifact_design_profile tests/tmp_prompt_quality_profile tests/tmp_system_model tests/tmp_security tests/tmp_baseline_compare.json tests/tmp_baseline_compare.md
find . -type d -name __pycache__ -prune -exec rm -rf {} +
diff --git a/README.md b/README.md
index 2a44654..bda3dc8 100644
--- a/README.md
+++ b/README.md
@@ -22,16 +22,20 @@ It turns rough workflows, transcripts, prompts, notes, and runbooks into reusabl
- a front-loaded intent dialogue with an intent confidence gate, so the system keeps clarifying when the true job, outputs, exclusions, or standards are still fuzzy
- a silent-by-default GitHub benchmark scan plus reference synthesis that studies top public repositories and world-class pattern tracks, then surfaces only real conflicts or uncertainty to the user
- a generated visual HTML overview for each newly initialized skill
-- a Review Studio 2.0 HTML gate page that combines intent, trigger, output eval, context, runtime, trust, atlas, and release evidence
+- a Review Studio 2.0 HTML gate page that combines intent, trigger, output eval, context, runtime, trust, atlas, adoption drift, reviewer waivers, reviewer annotations, release evidence, and per-warning fix actions
+- Output Eval Lab evidence with assertion grading, execution/timing/token evidence, a blind A/B review pack, a separate answer key, and reviewer adjudication reports
+- a runtime permission probe report that checks packaged target adapters for explicit permission metadata, native-enforcement flags, metadata fallback notes, and residual risks
- a side-by-side HTML review studio for first-pass human review
- an artifact design profile that defines visual direction, layout patterns, and quality gates for reports, tutorials, dashboards, screenshots, and review pages
- a prompt quality profile that abstracts need modeling, RTF mapping, complexity, and quality checks into reviewer-visible evidence instead of bloating `SKILL.md`
- a systems-thinking model that maps boundaries, feedback loops, drift risks, recurring failure patterns, and highest-leverage quality moves
- three high-value next iteration directions after the first package is created
- a lightweight feedback log that does not require a full promotion cycle
+- a local-first metadata-only adoption and drift report that turns real usage signals into next iteration candidates
- a baseline compare report for with-skill vs baseline review
- a conversation-style, archetype-aware quickstart that steers new packages toward scaffold, production, library, or governed fits
-- Skill IR as the platform-neutral semantic contract plus client-specific adapters
+- Skill IR as the platform-neutral semantic contract, plus compiler reports and client-specific adapters
+- Registry audit metadata with package version, owner, license, checksum, and compatibility matrix
- governance, promotion, and portability checks built into the default flow
## Architecture
@@ -85,7 +89,7 @@ Weighted score formula: `sum(score / 10 * weight)`.
2. Start with a short, human intent dialogue so the real job, outputs, exclusions, constraints, and standards are explicit.
3. Let `quickstart` clarify intent first, then run silent benchmark scan and reference synthesis; it only surfaces explicit questions when intent is still unclear or when there is a real design conflict.
4. Use the archetype-aware `quickstart` or the full authoring flow to generate or improve the package in scaffold, production, library, or governed mode.
-5. Review the generated `reports/skill-overview.html` first for the bilingual HTML skill report. It defaults to Simplified Chinese and provides an English switch in the top right. Then open `reports/review-studio.html` to inspect release blockers and evidence paths in one page before adding more structure.
+5. Review the generated `reports/skill-overview.html` first for the bilingual HTML skill report. It defaults to Simplified Chinese and provides an English switch in the top right. Then open `reports/review-studio.html` to inspect release blockers, permission approvals, and evidence paths in one page before adding more structure.
Or use the unified authoring CLI:
@@ -102,14 +106,26 @@ python3 scripts/yao.py artifact-design-profile my-skill
python3 scripts/yao.py prompt-quality-profile my-skill
python3 scripts/yao.py system-model my-skill
python3 scripts/yao.py feedback my-skill --note "Tighten exclusions before adding scripts." --rating 4 --category boundary
+python3 scripts/yao.py adoption-drift my-skill --record-event skill_activation --activation-type explicit --outcome accepted
+python3 scripts/yao.py review-waivers my-skill --add-waiver --gate-key trust-report --reviewer "Yao Team" --reason "Known warning accepted for this release with bounded follow-up." --expires-at 2026-09-30
+python3 scripts/yao.py review-waivers my-skill --add-waiver --gate-key permission-gates --reviewer "Yao Team" --reason "Permission warning accepted only for this non-governed release window." --expires-at 2026-09-30
+python3 scripts/yao.py review-annotations my-skill --add-annotation --gate-key output-lab --target-path reports/output_quality_scorecard.md --line 1 --body "Clarify recorded fixture vs model-executed evidence before release."
python3 scripts/yao.py baseline-compare
python3 scripts/yao.py check-update
-python3 scripts/yao.py package . --platform generic --output-dir dist
python3 scripts/yao.py skill-ir . --output-json skill-ir/examples/yao-meta-skill.json
+python3 scripts/yao.py compile-skill . --target openai --target claude --target generic
+python3 scripts/yao.py package . --platform generic --output-dir dist
python3 scripts/yao.py output-eval
+python3 scripts/yao.py output-exec
+python3 scripts/yao.py output-review
python3 scripts/yao.py conformance .
python3 scripts/yao.py trust .
+python3 scripts/yao.py runtime-permissions . --package-dir dist
python3 scripts/yao.py skill-atlas --workspace-root .
+python3 scripts/yao.py registry-audit .
+python3 scripts/yao.py package-verify . --package-dir dist --require-zip
+python3 scripts/yao.py install-simulate . --package-dir dist
+python3 scripts/yao.py upgrade-check . --previous-package-json registry/examples/yao-meta-skill-1.0.0.json
```
## Local Development Source
@@ -160,7 +176,9 @@ python3 scripts/judge_blind_eval.py --description-file SKILL.md --cases evals/bl
python3 scripts/context_sizer.py .
python3 scripts/resource_boundary_check.py .
python3 scripts/governance_check.py . --require-manifest
+python3 scripts/compile_skill.py .
python3 scripts/cross_packager.py . --platform openai --platform claude --platform generic --expectations evals/packaging_expectations.json --zip
+python3 scripts/probe_runtime_permissions.py . --package-dir dist
python3 tests/verify_packager_failures.py
```
@@ -179,7 +197,11 @@ python3 scripts/yao.py workspace-flow --target root --label first-pass
python3 scripts/yao.py review-viewer my-skill
python3 scripts/yao.py review --target root
python3 scripts/yao.py release-snapshot --target root --label release-candidate
+python3 scripts/yao.py skill-ir . --output-json skill-ir/examples/yao-meta-skill.json
+python3 scripts/yao.py compile-skill .
python3 scripts/yao.py package . --platform openai --platform claude --platform generic --output-dir dist --zip
+python3 scripts/yao.py runtime-permissions . --package-dir dist
+python3 scripts/yao.py package-verify . --package-dir dist --require-zip
python3 scripts/yao.py test
```
@@ -225,7 +247,9 @@ The homepage panel below is generated from the current eval suite so the family-
Full reports: [reports/eval_suite.json](reports/eval_suite.json) and [reports/family_summary.md](reports/family_summary.md)
-- packaging validation: `openai`, `claude`, and `generic` targets pass contract checks and carry IR provenance plus semantic parity metadata
+- packaging validation: `openai`, `claude`, and `generic` targets pass contract checks and carry IR provenance, semantic parity metadata, and target-native behavior contracts
+- target compiler validation: `openai`, `claude`, `generic`, and Agent Skills compatible contracts are compiled from Skill IR with generated-file mappings, adapter modes, native surfaces, permission enforcement notes, and unsupported-feature notes
+- runtime permission probes: `openai`, `claude`, and `generic` adapters expose explicit permission contracts; current targets report `0` native-enforcement adapters and `3` metadata fallbacks with residual risks visible to reviewers
- portability score: `100/100` with neutral activation, execution, trust, and degradation metadata preserved across all exported targets
- description optimization suite: root, team frontend review, and governed incident command pass blind and adversarial holdout gates; governed incident command still carries one visible holdout miss, and adversarial calibration plus family drift are now tracked separately
- judge-backed blind eval: root, team frontend review, and governed incident command now pass an independent rubric judge on blind holdout prompts
@@ -234,8 +258,8 @@ Full reports: [reports/eval_suite.json](reports/eval_suite.json) and [reports/fa
- governance and resource-boundary checks are part of the default test path
- root governance maturity score: `90/100`; governed benchmark example: `95/100`
- CJK-aware trigger matching is now covered by explicit Chinese build, packaging, eval, and near-neighbor cases
-- context budgets: root `994/1000`, complex benchmark `790/1000`, governed benchmark `760/1000`
-- quality density: root `130.8`, complex benchmark `164.6`, governed benchmark `171.1`
+- context budgets: root `987/1000`, complex benchmark `790/1000`, governed benchmark `760/1000`
+- quality density: root `131.7`, complex benchmark `164.6`, governed benchmark `171.1`
- regression milestones are tracked in [reports/regression_history.md](reports/regression_history.md)
- description drift history is tracked in [reports/description_drift_history.md](reports/description_drift_history.md)
- route confusion is tracked in [reports/route_scorecard.md](reports/route_scorecard.md)
@@ -244,6 +268,14 @@ Full reports: [reports/eval_suite.json](reports/eval_suite.json) and [reports/fa
- candidate lifecycle states are published in [reports/candidate_registry.md](reports/candidate_registry.md)
- lightweight with-skill vs baseline comparison is published in [reports/baseline-compare.md](reports/baseline-compare.md)
- Review Studio 2.0 gate evidence is published in [reports/review-studio.html](reports/review-studio.html)
+- Review Studio fix actions are embedded in [reports/review-studio.json](reports/review-studio.json)
+- reviewer waiver evidence is published in [reports/review_waivers.md](reports/review_waivers.md)
+- target compiler evidence is published in [reports/compiled_targets.md](reports/compiled_targets.md)
+- registry package metadata and audit status are published in [reports/registry_audit.md](reports/registry_audit.md)
+- package archive verification is published in [reports/package_verification.md](reports/package_verification.md)
+- temporary local install simulation is published in [reports/install_simulation.md](reports/install_simulation.md)
+- upgrade diff, version-bump recommendation, and release-note evidence are published in [reports/upgrade_check.md](reports/upgrade_check.md)
+- local-first adoption and drift telemetry is summarized in [reports/adoption_drift_report.md](reports/adoption_drift_report.md)
- context budget summaries are tracked in [reports/context_budget.md](reports/context_budget.md)
- portability status is tracked in [reports/portability_score.md](reports/portability_score.md)
@@ -353,7 +385,7 @@ Utility scripts that make the meta-skill operational:
- `run_description_optimization_suite.py`: runs description optimization across the root skill and governed examples, then writes reusable reports and optional drift snapshots with calibration and family summaries
- `promotion_checker.py`: applies promotion policy to current description candidates, writes promotion decisions, builds candidate registries, and emits iteration bundles with review stubs
- `create_iteration_snapshot.py`: freezes the current promotion decision into a versioned release snapshot with review, route, and context evidence
-- `yao.py`: unified authoring CLI that exposes init, validate, optimize-description, promote-check, review, release-snapshot, workspace-flow, report, package, and test as one entrypoint
+- `yao.py`: unified authoring CLI that exposes init, validate, optimize-description, promote-check, review, release-snapshot, workspace-flow, report, skill-ir, compile-skill, output-exec, output-review, package, registry-audit, package-verify, install-simulate, upgrade-check, review-waivers, and test as one entrypoint
- `render_description_drift_history.py`: turns description-optimization snapshots into a readable drift-history report
- `build_confusion_matrix.py`: scores route confusion across tracked sibling skills and `no_route` cases, then writes a route scorecard and optional milestone snapshot
- `render_iteration_ledger.py`: compresses regression milestones, description optimization drift, and route scorecards into one iteration-facing ledger
@@ -366,10 +398,21 @@ Utility scripts that make the meta-skill operational:
- `render_portability_report.py`: scores cross-environment portability from neutral metadata, degradation rules, and consumer validation coverage
- `render_skill_overview.py`: generates the white-background bilingual HTML skill audit report with sticky four-character Chinese navigation, top-right language switch, v2 scorecard, inline SVG charts, contract boundary, quality review, risk governance, assets, and iteration roadmap
- `export_skill_ir.py`: exports the 2.0 platform-neutral Skill IR contract from `SKILL.md`, manifest, interface metadata, evals, resources, and reports
-- `run_output_eval.py`: runs the Output Eval Lab v0 with static with-skill vs baseline assertion grading and writes `reports/output_quality_scorecard.*`
+- `compile_skill.py`: compiles Skill IR into target-specific semantic contracts, generated-file maps, adapter modes, target-native behavior contracts, preserved semantics, warnings, and unsupported-feature notes
+- `run_output_eval.py`: runs the Output Eval Lab v0 with static with-skill vs baseline assertion grading, blind A/B review pack generation, and separate answer key artifacts
+- `run_output_execution.py`: records output-eval execution evidence, distinguishing recorded fixtures, command runners, and provider-backed model runs with timing and token metadata
+- `local_output_eval_runner.py`: deterministic local runner for command-executed output-eval smoke evidence without claiming provider-backed model generation
+- `adjudicate_output_review.py`: records reviewer choices for blind A/B output evals, compares them with the answer key, and renders pending, match, disagreement, and invalid-decision audit reports
+- `render_review_annotations.py`: records reviewer annotations tied to Review Studio gates, source/report paths, and optional line numbers, with open blocker annotations reflected in Review Studio decisions
- `run_conformance_suite.py`: verifies runtime conformance for OpenAI, Claude, Agent Skills, VS Code/Copilot-style, and generic targets
-- `trust_check.py`: generates the trust/security report for scripts, dependencies, secret risk, trust metadata, and package integrity
+- `trust_check.py`: generates the trust/security report for scripts, dependencies, secret risk, bounded network host policy, execution-level `--help` smoke checks, permission inputs, trust metadata, and stable source-contract integrity
- `build_skill_atlas.py`: builds the Skill Atlas catalog, route-overlap matrix, dependency graph, stale report, owner gaps, and HTML overview for a multi-skill workspace
+- `registry_audit.py`: builds registry package metadata and audits version, owner, license, checksum, Skill IR source, and compatibility matrix
+- `verify_package.py`: verifies generated package manifests, target adapters, zip archive safety, archive checksum, and registry parity
+- `simulate_install.py`: extracts a generated zip into a temporary skill root and verifies entrypoint, manifest, interface, reports, and adapters can be loaded
+- `upgrade_check.py`: compares current and previous registry package metadata, recommends a version bump, and blocks incompatible upgrade claims
+- `render_adoption_drift_report.py`: records metadata-only local telemetry and renders adoption, missed-trigger, bad-output, script-error, and review-drift signals without packaging raw event logs
+- `render_review_waivers.py`: validates human reviewer risk approvals with gate keys, reasons, expiry dates, and blocker-safe waiver policy
- `init_skill.py`, `lint_skill.py`, `validate_skill.py`, `diff_eval.py`: minimal authoring toolchain
- `check_update.py`: checks GitHub for a newer `VERSION` or remote manifest version and reports a reinstall hint without modifying local files
- `render_output_risk_profile.py`: predicts output-specific failure modes such as generic headings, citation clutter, screenshot mistakes, weak Markdown tables, and missing execution assumptions
@@ -444,6 +487,8 @@ The typical flow is:
Examples:
```bash
+python3 scripts/export_skill_ir.py ./yao-meta-skill --output-json ./yao-meta-skill/reports/skill-ir.json
+python3 scripts/compile_skill.py ./yao-meta-skill --target openai --target claude --target generic
python3 scripts/cross_packager.py ./yao-meta-skill --platform openai --platform claude --expectations evals/packaging_expectations.json --zip
python3 scripts/context_sizer.py ./yao-meta-skill
python3 scripts/resource_boundary_check.py ./yao-meta-skill
diff --git a/SKILL.md b/SKILL.md
index ea3762c..34d4901 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -32,11 +32,11 @@ Mode rules: [Method](references/skill-engineering-method.md), [Operating Modes](
6. Add only folders and gates that earn their keep.
7. Surface the top three next iteration directions.
-Core playbooks: [Method](references/skill-engineering-method.md), [Intent](references/intent-dialogue.md), [Reference Scan](references/reference-scan.md), [Skill IR](references/skill-ir-method.md), [Output Eval](references/output-eval-method.md), [Review Studio](references/review-studio-method.md).
+Core playbooks: [Method](references/skill-engineering-method.md), [Intent](references/intent-dialogue.md), [Reference Scan](references/reference-scan.md), [Skill IR](references/skill-ir-method.md), [Output Eval](references/output-eval-method.md), [Registry](references/distribution-registry-method.md), [Telemetry](references/telemetry-drift-method.md), [Waivers](references/review-waiver-method.md), [Review Studio](references/review-studio-method.md).
## Skill OS 2.0 Gates
-For production, library, governed, or team-distributed work, use Skill IR, trigger + output eval, Skill Atlas, runtime conformance, trust report, and Review Studio before release.
+For production, library, governed, or team-distributed work, use Skill IR, target compiler contracts, trigger + output eval, Skill Atlas, runtime conformance, trust report, registry metadata, package verification, install simulation, upgrade check, adoption/drift telemetry, reviewer waiver evidence, and Review Studio before release.
## First-Turn Style
diff --git a/evals/README.md b/evals/README.md
index 56d60e7..e1e848e 100644
--- a/evals/README.md
+++ b/evals/README.md
@@ -15,8 +15,15 @@ Contents:
- `improved_description.txt`: current stronger trigger description
- `../reports/description_optimization*.{json,md}`: generated route-optimization reports for the root skill
- `failure-cases.md`: current weak spots and regression targets
-- `packaging_expectations.json`: required packaging behaviors for supported targets, including IR provenance and semantic parity fields
+- `packaging_expectations.json`: required packaging behaviors for supported targets, including IR provenance, compiler contracts, and semantic parity fields
- `output/`: Output Eval Lab cases, fixtures, and schema for with-skill vs baseline assertion grading
+- registry audit tests verify package metadata, compatibility, checksum, owner, license, and Skill IR provenance
+- package verification tests verify generated manifests, target adapters, zip archive safety, archive checksum, and registry parity
+- install simulation tests verify archive extraction, entrypoint loading, manifest/interface readability, adapter loading, and unsafe zip blocking
+- upgrade check tests verify version-bump recommendations, target diff detection, compatibility regression blocking, and release-note evidence
+- adoption drift tests verify metadata-only telemetry aggregation, privacy-field blocking, and exclusion of raw local telemetry logs from zip packages
+- review waiver tests verify reviewer, reason, expiry, active coverage, expired records, invalid records, and Review Studio integration
+- compiler tests verify Skill IR target contracts, adapter modes, generated-file mappings, unsupported targets, and markdown/json report artifacts
- `../reports/`: generated suite JSON plus the homepage-visible family summary panel source
Use:
@@ -34,10 +41,24 @@ python3 scripts/render_iteration_ledger.py
python3 tests/verify_description_optimization.py
python3 tests/verify_route_confusion.py
python3 tests/verify_failure_regressions.py
+python3 scripts/compile_skill.py . --target openai --target claude --target generic
+python3 tests/verify_compile_skill.py
python3 scripts/cross_packager.py . --platform openai --platform claude --expectations evals/packaging_expectations.json --zip
+python3 scripts/verify_package.py . --package-dir dist --require-zip
python3 tests/verify_packager_failures.py
+python3 tests/verify_package_verification.py
+python3 scripts/simulate_install.py . --package-dir dist
+python3 tests/verify_install_simulation.py
python3 scripts/run_output_eval.py
python3 tests/verify_output_eval_lab.py
+python3 scripts/registry_audit.py .
+python3 tests/verify_registry_audit.py
+python3 scripts/upgrade_check.py . --previous-package-json registry/examples/yao-meta-skill-1.0.0.json
+python3 tests/verify_upgrade_check.py
+python3 scripts/render_adoption_drift_report.py . --record-event skill_activation --activation-type explicit --outcome accepted
+python3 tests/verify_adoption_drift.py
+python3 scripts/render_review_waivers.py .
+python3 tests/verify_review_waivers.py
```
Regression scope now includes:
@@ -58,3 +79,8 @@ Regression scope now includes:
- calibration summaries that surface score gaps, threshold margins, and risk bands for each acceptance gate
- family-level drift history that records which blind and adversarial families stay clean over time
- output-quality scorecards that compare without-skill and with-skill artifacts through assertion grading, including near-neighbor and file-backed governed cases
+- install-simulation checks that prove generated archives can be extracted into a temporary local skill root and loaded without touching the active global skills directory
+- upgrade-readiness checks that compare registry package baselines, recommend semver bumps, and block breaking changes without an adequate declared version
+- local-first adoption drift checks that turn accepted, edited, missed, rejected, script-error, and review-overdue metadata into next iteration candidates without storing raw prompts or outputs
+- reviewer-waiver checks that keep warning acceptance explicit, expiring, and separate from non-waivable blockers
+- compiler checks that turn Skill IR into reviewable target contracts before packaging embeds those contracts into adapters
diff --git a/evals/output/schema.json b/evals/output/schema.json
index 675e24a..f08d8b0 100644
--- a/evals/output/schema.json
+++ b/evals/output/schema.json
@@ -2,7 +2,7 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://yao.example/output-eval-case.schema.json",
"title": "Yao Output Eval Case",
- "description": "Static v0 output-eval case for comparing without-skill and with-skill outputs.",
+ "description": "Output-eval case for comparing without-skill and with-skill outputs, with optional execution metadata.",
"type": "object",
"additionalProperties": false,
"required": ["id", "prompt", "baseline_output", "with_skill_output", "assertions"],
@@ -57,6 +57,26 @@
"type": "object",
"additionalProperties": true
},
+ "execution": {
+ "type": "object",
+ "description": "Optional case-level execution metadata for fixture, command, or provider-backed output runs.",
+ "additionalProperties": true,
+ "properties": {
+ "mode": {
+ "type": "string",
+ "enum": ["recorded_fixture", "command", "model"]
+ },
+ "provider": {
+ "type": "string"
+ },
+ "model": {
+ "type": "string"
+ },
+ "holdout": {
+ "type": "boolean"
+ }
+ }
+ },
"metadata": {
"type": "object",
"additionalProperties": true
diff --git a/evals/packaging_expectations.json b/evals/packaging_expectations.json
index f7766b0..374c905 100644
--- a/evals/packaging_expectations.json
+++ b/evals/packaging_expectations.json
@@ -12,6 +12,12 @@
"ir_schema_version",
"semantic_contract",
"semantic_parity",
+ "compiler",
+ "compiled_contract",
+ "permission_contract",
+ "target_permission_contract",
+ "target_native_contract",
+ "target_transform",
"canonical_metadata",
"canonical_format",
"activation_mode",
diff --git a/references/distribution-registry-method.md b/references/distribution-registry-method.md
new file mode 100644
index 0000000..68bb052
--- /dev/null
+++ b/references/distribution-registry-method.md
@@ -0,0 +1,57 @@
+# Distribution Registry Method
+
+Registry metadata turns a local skill directory into an installable and reviewable package record.
+
+## When To Use
+
+Use registry audit for library, governed, team-distributed, or upgrade-sensitive skills. Scaffold skills can skip it until reuse is real.
+
+## Required Evidence
+
+- package name, version, owner, maturity, review cadence, and license
+- Skill IR source and schema version
+- trust level and package SHA256
+- package verification status and archive SHA256 when a zip distribution is built
+- install simulation status when an archive is meant to be installed locally or by a team
+- adoption/drift aggregate status when local telemetry exists
+- target compatibility matrix
+- upgrade diff, recommended version bump, and breaking-change notes when a previous package baseline exists
+- links to overview, Review Studio, trust report, conformance matrix, package verification, install simulation, adoption drift evidence, and review waivers
+
+## Release Rule
+
+Do not publish a team package when registry audit reports missing version, hash, owner, review cadence, license, valid Skill IR, or passing compatibility for declared targets.
+
+For an installable archive, first build the distribution and run package verification:
+
+```bash
+python3 scripts/yao.py package . --platform openai --platform claude --platform generic --output-dir dist --zip
+python3 scripts/yao.py package-verify . --package-dir dist --require-zip
+python3 scripts/yao.py install-simulate . --package-dir dist
+python3 scripts/yao.py registry-audit .
+python3 scripts/yao.py upgrade-check . --previous-package-json registry/examples/yao-meta-skill-1.0.0.json
+```
+
+Do not claim archive readiness when package verification reports unsafe zip paths, missing target adapters, missing package manifest, registry metadata mismatch, or unreadable archive contents.
+
+Do not claim install readiness when install simulation cannot extract the archive into a temporary skill root, load `SKILL.md` frontmatter, read `manifest.json`, read `agents/interface.yaml`, find the overview and Review Studio reports, or load each generated adapter.
+
+Do not include raw `reports/telemetry_events.jsonl` in a distributed package. Include only aggregate adoption drift reports, and block release review when telemetry contains raw prompts, outputs, transcripts, notes, or messages.
+
+Review waiver evidence may be distributed as `reports/review_waivers.md/json` because it is metadata-only reviewer accountability. Do not store raw prompts, outputs, transcripts, credentials, or private customer detail in waiver reasons.
+
+Do not claim upgrade readiness when upgrade check reports an insufficient version bump, target removal without a major bump, compatibility regression without a major bump, package name change, or invalid semver. Include `reports/upgrade_check.md` in the reviewer evidence bundle so release notes and migration guidance are tied to the exact registry diff.
+
+## Reviewer Gate
+
+A reviewer should be able to answer:
+
+1. Which package version is being installed?
+2. Who owns the package?
+3. Which targets are compatible?
+4. Which checksum identifies the reviewed package contents?
+5. Which reports prove trust and runtime readiness?
+6. Was the installable archive verified, and which checksum identifies it?
+7. Was the archive install-simulated in a temporary local skill root?
+8. What changed since the previous package, and does the declared version bump match the recommended bump?
+9. Are adoption and drift signals summarized without packaging raw local telemetry?
diff --git a/references/output-eval-method.md b/references/output-eval-method.md
index 02947a9..d9d999c 100644
--- a/references/output-eval-method.md
+++ b/references/output-eval-method.md
@@ -38,10 +38,63 @@ The first v0 scorecard reports:
- with-skill pass rate
- absolute delta
- failed assertions and failure taxonomy
+- execution mode, timing, and token evidence when `reports/output_execution_runs.md` is generated
+- blind A/B review pack count
- recommended next fixes
Production promotion should require the with-skill pass rate to beat baseline and should explain every failed assertion.
+## Execution Evidence
+
+Run execution evidence after the scorecard:
+
+```bash
+python3 scripts/yao.py output-exec
+```
+
+By default, this records the current case outputs as `recorded_fixture`. That is useful for reproducibility, but it is not model-executed evidence. To collect real run evidence, pass `--runner-command` with a command or JSON string list. The runner receives a JSON request on stdin and should return JSON with:
+
+- `output`
+- optional `execution_kind`: `command` or `model`
+- optional `provider` and `model`
+- optional `usage.input_tokens`, `usage.output_tokens`, and `usage.total_tokens`
+
+Only runs that return provider/model metadata or `execution_kind: "model"` should count as model-executed. If token usage is absent, the report may estimate tokens, but the estimate must be labeled as estimated.
+
+For local release-gate smoke evidence without external model credentials, use the deterministic runner:
+
+```bash
+python3 scripts/yao.py output-exec --runner-command '["python3","scripts/local_output_eval_runner.py"]'
+```
+
+This verifies the command-runner contract, timing capture, grading path, and failure handling. It must not be described as provider-backed model evidence.
+
+## Blind A/B Review
+
+Every output eval run should also generate:
+
+- `reports/output_blind_review_pack.md`
+- `reports/output_blind_review_pack.json`
+- `reports/output_blind_answer_key.json`
+
+The review pack must hide whether Variant A or Variant B came from the baseline or the skill-guided output. The answer key is separate audit evidence and should only be opened after a reviewer has made a judgment.
+
+## Reviewer Adjudication
+
+After blind review, record reviewer choices in `reports/output_review_decisions.json` and run:
+
+```bash
+python3 scripts/adjudicate_output_review.py --write-template
+python3 scripts/yao.py output-review
+```
+
+The adjudication report writes:
+
+- `reports/output_review_adjudication.json`
+- `reports/output_review_adjudication.md`
+
+When no reviewer decisions exist, the report should say the cases are pending. Do not count pending cases as human agreement. Only a real `winner_variant` of `A` or `B` should contribute to agreement rate, disagreement count, and reviewer judgment count.
+
## Anti-Overfitting
Keep a small public smoke set and a separate holdout set. Rotate real failures into the taxonomy instead of editing only the prompt that failed. Add near-neighbor cases whenever the output looks good but the boundary is still unclear.
diff --git a/references/packaging-contracts.md b/references/packaging-contracts.md
index a760f78..b734d76 100644
--- a/references/packaging-contracts.md
+++ b/references/packaging-contracts.md
@@ -1,6 +1,6 @@
# Packaging Contracts
-`cross_packager.py` is not just an export helper. It defines and validates platform contracts.
+`cross_packager.py` is not just an export helper. It validates platform contracts and embeds target compiler output from `compile_skill.py`.
## Current Targets
@@ -15,8 +15,13 @@ Each target contract defines:
- required output fields
- required output files
- field mapping from the neutral source metadata
+- compiled contract from Skill IR
+- target transform metadata, including generated files and unsupported features
- portable execution metadata
- trust-boundary metadata
+- permission contract metadata from the trust report
+- target-specific permission representation and reviewer notes
+- target-native behavior contract for native surface, activation policy, resource strategy, script strategy, permission enforcement, install scope, review artifacts, and fallback behavior
- degradation strategy metadata
## Failure Handling
@@ -27,6 +32,8 @@ When `--expectations` is provided:
- missing required fields cause exit code `2`
- validation failures are emitted in the JSON report
+After packaging, run `scripts/probe_runtime_permissions.py` against the generated package directory. Packaging creates the permission metadata; the runtime permission probe verifies that each target adapter exposes the contract, target-specific representation, native-enforcement flag, operator note, and residual metadata-fallback risk.
+
## Source Of Truth
The platform-neutral semantic source is Skill IR when it exists:
@@ -39,10 +46,13 @@ The structural validation sources remain:
- `SKILL.md`
- `agents/interface.yaml`
-Target-specific metadata is generated at packaging time. The adapter must carry
-`ir_source`, `ir_schema_version`, `job_to_be_done`, `semantic_contract`, and
-`semantic_parity` so reviewers can see whether the target preserved the core
-skill meaning or fell back to frontmatter-only metadata.
+Target-specific metadata is generated through `scripts/compile_skill.py` and
+then embedded at packaging time. The adapter must carry `compiler`,
+`compiled_contract`, `permission_contract`, `target_permission_contract`,
+`target_native_contract`, `target_transform`, `ir_source`, `ir_schema_version`,
+`job_to_be_done`, `semantic_contract`, and `semantic_parity` so reviewers can
+see whether the target preserved the core skill meaning or fell back to
+frontmatter-only metadata.
## Portability Model
@@ -51,7 +61,10 @@ The packaging layer now preserves four portable semantics from the neutral sourc
- activation
- execution
- trust
+- permissions
- degradation
- platform-neutral skill meaning from Skill IR
+- target-specific native behavior notes for activation, resources, scripts, permission enforcement, install scope, review artifacts, and fallback behavior
+- target-specific compile notes for generated files, adapter mode, preserved semantics, and unsupported features
This means portability is not just "can it export a file?" but also "does the exported target preserve the source package's activation and safety assumptions?"
diff --git a/references/platform-capability-matrix.md b/references/platform-capability-matrix.md
index f06a259..101763d 100644
--- a/references/platform-capability-matrix.md
+++ b/references/platform-capability-matrix.md
@@ -2,17 +2,20 @@
This matrix describes the current packaging targets and their support level.
-| Target | Metadata Adapter | Output Contract | Snapshot Test | Portability Semantics | Notes |
-| --- | --- | --- | --- | --- | --- |
-| `openai` | Yes | Yes | Yes | activation, execution, trust, degradation | Generates `targets/openai/agents/openai.yaml` |
-| `claude` | Yes | Yes | Yes | activation, execution, trust, degradation | Generates `targets/claude/README.md` plus adapter metadata |
-| `generic` | Yes | Yes | Yes | activation, execution, trust, degradation | Uses neutral adapter metadata only |
+| Target | Metadata Adapter | Compiler Contract | Native Behavior Contract | Output Contract | Snapshot Test | Portability Semantics | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `openai` | Yes | Yes | Yes | Yes | Yes | activation, execution, trust, permissions, degradation, native behavior | Generates `targets/openai/agents/openai.yaml` |
+| `claude` | Yes | Yes | Yes | Yes | Yes | activation, execution, trust, permissions, degradation, native behavior | Generates `targets/claude/README.md` plus adapter metadata |
+| `generic` | Yes | Yes | Yes | Yes | Yes | activation, execution, trust, permissions, degradation, native behavior | Uses neutral adapter metadata only |
+| `agent-skills-compatible` | Neutral source | Yes | Yes | Source-compatible | Yes | activation, execution, trust, permissions, degradation, native behavior | Keeps canonical `SKILL.md` plus `agents/interface.yaml` source shape |
## Current Support Model
-- `openai`: strongest metadata adapter support
-- `claude`: lightweight compatibility adapter, behavior still relies mainly on neutral source files
-- `generic`: lowest-friction export for neutral Agent Skills consumers
+- `openai`: strongest metadata adapter support with an explicit compiler contract.
+- `claude`: lightweight compatibility adapter with an explicit compiler contract and fallback notes.
+- `generic`: lowest-friction export for neutral Agent Skills consumers.
+- `agent-skills-compatible`: canonical source shape with compiler evidence for review and distribution.
+- runtime permission probes currently report metadata fallback for generated targets; no target is claimed as native-enforced until a client or installer integration can actually enforce the permission model.
## Portable Semantics
@@ -21,15 +24,19 @@ Each target now preserves:
- activation mode and optional path filters
- execution context and shell choice
- trust tier and remote inline-execution policy
+- permission contract for network, file-write, subprocess, and interactive script surfaces
+- target-native behavior contract for native surface, activation policy, resource strategy, script strategy, permission enforcement, install scope, review artifacts, and fallback behavior
- degradation strategy for unsupported client behavior
+- generated-file mapping and adapter mode from `reports/compiled_targets.json`
## Explicit Non-Goals
This project does not yet implement:
-- runtime-specific behavior transforms
- client SDK integration
- provider-specific execution logic
+- provider-native installer actions or account-level activation changes
+- native runtime permission enforcement
## Degradation Rule
diff --git a/references/review-studio-method.md b/references/review-studio-method.md
index 11b7614..da67a4c 100644
--- a/references/review-studio-method.md
+++ b/references/review-studio-method.md
@@ -6,19 +6,27 @@ Review Studio is the release-facing audit surface for a skill package. It does n
- Show release blockers and warnings before the package deepens.
- Link every gate back to a concrete evidence artifact.
+- Generate review actions for every blocker and warning, with source-fix location and verification command.
+- Make human warning acceptance auditable through a waiver ledger.
+- Make reviewer comments auditable through an annotation ledger tied to gates, source/report paths, and optional line numbers.
- Keep review flow vertical: summary first, gates second, supporting details after.
-- Avoid hiding output quality, runtime, trust, and portfolio issues across separate pages.
+- Avoid hiding output quality, runtime, trust, portfolio, and operating-loop issues across separate pages.
## Required Gates
1. Intent Canvas: intent confidence and unresolved input/output/exclusion gaps.
2. Trigger Lab: route scorecard, misroutes, ambiguous cases, and near-neighbor safety.
-3. Output Lab: with-skill vs baseline delta, case count, file-backed cases, near-neighbor cases, and boundary cases.
+3. Output Lab: with-skill vs baseline delta, execution mode, timing/token evidence, case count, file-backed cases, near-neighbor cases, boundary cases, blind A/B review pack evidence, and reviewer adjudication status.
4. Context Budget: initial load, budget tier, warnings, and quality density.
5. Runtime Matrix: target conformance pass/fail and degradation notes.
6. Trust Report: secret scan, script surface, dependency pinning, network/interactive flags, and package hash.
-7. Skill Atlas: route collisions, stale skills, owner gaps, and no-route opportunities.
-8. Release Notes: promotion status, migration notes, known gaps, and next move.
+7. Permission Gates: reviewer-approved capability scope, reason, expiry, evidence, and target-enforcement notes.
+8. Runtime Permission Probes: packaged adapter permission contracts, native-enforcement flags, metadata fallback notes, and residual risks.
+9. Skill Atlas: route collisions, stale skills, owner gaps, and no-route opportunities.
+10. Operations Loop: local-first metadata-only adoption, missed-trigger, bad-output, script-error, and review-drift signals.
+11. Review Waivers: human risk approvals, active coverage, expired approvals, invalid records, and expiry policy.
+12. Registry Audit: package metadata, install evidence, compatibility entries, and archive/source checksums.
+13. Release Notes: promotion status, migration notes, known gaps, and next move.
## Gate Semantics
@@ -27,3 +35,51 @@ Review Studio is the release-facing audit surface for a skill package. It does n
- `block`: do not claim production, library, governed, or public readiness until fixed.
For library and governed skills, Output Lab should have at least five cases and cover file-backed, near-neighbor, and boundary scenarios.
+
+Production, library, and governed reviews should also show a blind A/B review pack. The Review Studio gate may warn when scorecard evidence exists but no blind pack is present, because the package can prove assertions but not yet reduce reviewer bias.
+
+When `reports/output_execution_runs.json` exists, Review Studio should show the number of variant runs, command-executed runs, model-executed runs, recorded fixtures, timing-observed runs, and token-estimated runs. Recorded fixtures are valid reproducibility evidence, but they must not be described as model-executed output evidence.
+
+When `reports/output_review_adjudication.json` exists, Review Studio should show reviewed pairs and pending pairs. Pending reviewer decisions are acceptable as an explicit state, but they must not be counted as agreement or human review evidence. Invalid adjudication records should block release because they make the blind review audit untrustworthy.
+
+The Operations Loop must never display raw telemetry logs. It should link only to `reports/adoption_drift_report.md`; privacy or schema violations are blockers.
+
+The Runtime Permission Probes gate is evaluated after packaging, because it reads generated target adapters. A missing probe can warn in lighter modes, but governed release should not claim target permission readiness without `reports/runtime_permission_probes.json`.
+
+The Review Waivers gate must never convert a blocker into a pass. Waivers only cover warning-level risks, require reviewer, reason, scope, and expiry, and must link only to `reports/review_waivers.md`.
+
+Review Annotations are not waivers. They are reviewer comments attached to a Review Studio gate plus a relative source/report path and optional line number. Use them to preserve review context, requested edits, and source-line notes. Open blocker annotations should make the Review Studio decision `blocked` until the annotation is resolved or deferred with reviewer rationale. Open warning annotations can move the package into review, but they do not create gate-specific `review_actions`; actions remain reserved for non-pass gates.
+
+## Review Actions
+
+Every non-pass gate must produce a `review_actions` entry in `reports/review-studio.json`. When all gates pass, `review_actions` should be an empty list and the page should explicitly say there are no blocker or warning actions.
+
+Each action must include:
+
+- `gate_key`
+- `status`
+- `summary`
+- `why`
+- `source_fix`
+- `source_refs`
+- `evidence`
+- `verification_command`
+
+`source_refs` must be structured entries with relative `path`, human label, kind, existence flag, best-effort line number, and relative link when the file exists. They should point to the smallest useful report or source file, not just a broad directory.
+
+The HTML page should render these actions before the detailed supporting sections so a reviewer can move directly from warning to fix. Action entries do not change gate count or score; they make the current decision more operational.
+
+## Review Annotations
+
+`reports/review_annotations.json` is the structured ledger, and `reports/review_annotations.md` is the human-readable review note surface. Each annotation should include:
+
+- `gate_key`
+- `target_path`
+- `line` when a useful source line exists
+- `severity`
+- `status`
+- `reviewer`
+- `body`
+- optional `suggested_action`
+
+The ledger should reject absolute paths or paths that escape the skill directory. Missing target files are allowed as visible evidence gaps, not hidden failures.
diff --git a/references/review-waiver-method.md b/references/review-waiver-method.md
new file mode 100644
index 0000000..5872d83
--- /dev/null
+++ b/references/review-waiver-method.md
@@ -0,0 +1,57 @@
+# Review Waiver Method
+
+Review waivers make human risk acceptance explicit. They are not a way to hide problems; they are a local audit record for warning-level risks that the reviewer intentionally accepts for a bounded release window.
+
+## When To Use
+
+Use a waiver when:
+
+- Review Studio shows a warning that is understood and intentionally accepted.
+- The warning cannot be fixed before release without a worse tradeoff.
+- A reviewer can name the reason, scope, evidence, and expiry date.
+
+Do not use a waiver for blocker gates in v0. Blockers must be fixed before production, library, governed, or public readiness is claimed. In governed mode, missing or invalid high-permission approvals are blockers and should be fixed in `security/permission_policy.json`, not waived.
+
+## Required Fields
+
+Every waiver must include:
+
+- `gate_key`: the Review Studio gate being accepted.
+- `decision`: `accepted-risk`, `false-positive`, or `temporary-exception`.
+- `reviewer`: the accountable human or team.
+- `reason`: a concrete reason of at least 20 characters.
+- `created_at`: ISO date.
+- `expires_at`: ISO date.
+- `evidence`: optional path or note that explains the decision.
+- `scope`: default `current-release`.
+
+## Release Semantics
+
+- Invalid waiver records block Review Studio.
+- Expired waiver records stay visible and no longer cover warnings.
+- Active waivers cover only the exact gate key they name.
+- A warning without an active waiver remains visible as a warning.
+- Raw user prompts, outputs, credentials, and private transcripts must not be stored in waiver reasons.
+
+## Commands
+
+Render or validate the ledger:
+
+```bash
+python3 scripts/render_review_waivers.py .
+```
+
+Add a bounded approval:
+
+```bash
+python3 scripts/yao.py review-waivers . \
+ --add-waiver \
+ --gate-key trust-report \
+ --reviewer "Yao Team" \
+ --reason "Network-capable scripts are documented and bounded for this release." \
+ --expires-at 2026-09-30
+```
+
+For a non-governed release where `permission-gates` is only a warning, the same command can name `--gate-key permission-gates`. Governed releases must instead provide reviewer, scope, reason, expiry, evidence, and target-enforcement fields in `security/permission_policy.json`.
+
+Review Studio reads `reports/review_waivers.json` and links to `reports/review_waivers.md`.
diff --git a/references/skill-atlas-method.md b/references/skill-atlas-method.md
index 4bcb473..a0f0455 100644
--- a/references/skill-atlas-method.md
+++ b/references/skill-atlas-method.md
@@ -17,6 +17,12 @@ Single-skill quality is not enough for a team library. A skill portfolio also ne
- Flag stale skills based on `updated_at` and `review_cadence`.
- Extract no-route opportunities from failure notes.
+## Scope Policy
+
+Atlas keeps a full catalog, but release gates should distinguish actionable library skills from examples and test fixtures.
+
+Use `skill_atlas/policy.json` to mark path prefixes as non-actionable when they are intentionally retained as examples, evolution snapshots, embedded generated skills, or validator fixtures. Non-actionable items still appear in the full report, route matrix, stale list, and owner gap list, but Review Studio should use the actionable counts for release readiness.
+
## Reviewer Gate
-Use Atlas before promoting a single skill into a shared library. If a route collision or missing owner appears, fix the portfolio boundary before adding more local complexity to one skill.
+Use Atlas before promoting a single skill into a shared library. If an actionable route collision, missing owner, or stale governed skill appears, fix the portfolio boundary before adding more local complexity to one skill. Non-actionable issues should stay visible as evidence, not as release blockers.
diff --git a/references/telemetry-drift-method.md b/references/telemetry-drift-method.md
new file mode 100644
index 0000000..8633108
--- /dev/null
+++ b/references/telemetry-drift-method.md
@@ -0,0 +1,60 @@
+# Telemetry And Drift Method
+
+Telemetry turns real use into the next iteration queue. It must stay local-first and metadata-only by default.
+
+## When To Use
+
+Use the telemetry drift loop when a skill is production, library, governed, team-distributed, or repeatedly invoked by more than one workflow.
+
+Do not collect raw prompts, model outputs, transcripts, notes, messages, or private files. If a reviewer needs examples, store anonymized fixtures separately and cite them as eval evidence, not telemetry.
+
+## Event Contract
+
+The local event stream is `reports/telemetry_events.jsonl`. It is intentionally narrow:
+
+```json
+{
+ "event": "skill_activation",
+ "skill": "example-skill",
+ "version": "2.0.0",
+ "activation_type": "implicit",
+ "outcome": "accepted",
+ "failure_type": "none",
+ "timestamp": "2026-06-13T10:00:00Z"
+}
+```
+
+Allowed events: `skill_activation`, `skill_output`, `script_run`, `review_event`.
+
+Allowed outcomes: `accepted`, `edited`, `rejected`, `missed`, `failed`, `reviewed`, `unknown`.
+
+Allowed failure types: `wrong_trigger`, `under_trigger`, `bad_output`, `missing_resource`, `script_error`, `review_overdue`, `none`.
+
+## Privacy Rule
+
+The raw JSONL event log is local evidence and should not be distributed in skill packages. The distributable artifact is the aggregate report:
+
+- `reports/adoption_drift_report.json`
+- `reports/adoption_drift_report.md`
+
+Package builders should exclude `reports/telemetry_events.jsonl`. The root repository also ignores this raw event stream so local usage evidence does not become ordinary source history by accident.
+
+## Release Interpretation
+
+- `no-data`: acceptable for a first scaffold, but a warning for governed release review.
+- `low`: events exist and no drift failure signal is present.
+- `medium`: at least one missed trigger, wrong trigger, bad output, script error, or overdue review signal exists.
+- `high`: several drift signals are present; convert them into eval cases or governance actions before calling the skill release-ready.
+
+## Iteration Loop
+
+1. Capture metadata-only events locally.
+2. Render `reports/adoption_drift_report.md`.
+3. Convert missed triggers into trigger eval cases.
+4. Convert bad outputs into Output Eval assertions and failure taxonomy entries.
+5. Convert script errors into non-interactive smoke tests.
+6. Feed review-overdue signals back into Skill Atlas and owner review.
+
+## Review Studio Role
+
+Review Studio should show the aggregate telemetry gate as an operating loop, not as raw logs. A blocker means the telemetry contract was violated. A warning means the evidence is absent or the drift signal needs a follow-up case.
diff --git a/references/trust-security-method.md b/references/trust-security-method.md
index 444820d..ad6c9f5 100644
--- a/references/trust-security-method.md
+++ b/references/trust-security-method.md
@@ -16,11 +16,63 @@ Run the trust report when:
- obvious secret patterns
- script help surface and interactive prompts
+- execution-level `--help` smoke checks
- dependency pinning
- runtime trust metadata
- network-capable scripts
-- package integrity digest
+- bounded host policy for network-capable scripts
+- reviewer-approved permission policy for high-permission capabilities
+- packaged-target runtime permission probes for adapter contracts and metadata fallback limits
+- source-contract integrity digest
+
+## Script Interface Rule
+
+Every Python file under `scripts/` is reviewed as part of the package trust surface.
+
+- CLI scripts should use `argparse` so reviewers and installers can run `python3 scripts/name.py --help` before execution.
+- The trust report executes `python3 scripts/name.py --help` for CLI scripts with `argparse`, with a short timeout, and records pass/fail evidence.
+- Import-only modules should declare `SCRIPT_INTERFACE = "internal-module"` near the top of the file.
+- Internal modules should also declare `SCRIPT_INTERFACE_REASON` with a short explanation of which CLI or renderer imports them.
+- The trust report keeps internal modules in the script inventory, but excludes them from CLI help-surface warnings.
+- A Python file without an explicit internal-module declaration is treated as a CLI script by default.
+- CLI scripts without `argparse` are not smoke-executed; they remain visible as help-surface warnings.
+
+## Network Policy Rule
+
+Network-capable scripts must be bounded by a machine-readable policy before team distribution.
+
+- Put the policy in `security/network_policy.json`.
+- Add one entry per network-capable script under `scripts`.
+- Declare `allowed_hosts`, `allowed_path_prefixes`, purpose, timeout, auth mode, and custom-host behavior.
+- Default to HTTPS-only and deny custom hosts unless a CLI flag or environment variable makes the override explicit.
+- The trust report compares HTTPS URL literals in each script with `allowed_hosts`; missing or mismatched entries remain reviewer-visible warnings.
+
+## Permission Approval Rule
+
+High-permission capabilities must be approved before governed release.
+
+- Put approvals in `security/permission_policy.json`.
+- Cover each required capability detected by the trust report: `network`, `file_write`, `subprocess`, and `interactive` when present.
+- Each approval must include `decision: approved`, `reviewer`, `scope`, `reason`, `expires_at`, `evidence`, and `target_enforcement`.
+- Review Studio surfaces these checks as the `permission-gates` gate.
+- Missing, invalid, or expired approvals block governed mode. They remain visible warnings in lighter modes.
+
+## Runtime Permission Probe Rule
+
+Permission approval validates reviewer intent. Runtime permission probes validate the generated target adapters after packaging.
+
+- Run `python3 scripts/probe_runtime_permissions.py . --package-dir dist` after `cross_packager.py`.
+- The probe writes `reports/runtime_permission_probes.json` and `reports/runtime_permission_probes.md`.
+- A passing probe requires every target adapter to carry `permission_contract`, `target_permission_contract`, declared capabilities, a native-enforcement boolean, representation notes, and operator notes.
+- If a target has no native enforcement, the probe must mark an explicit metadata fallback and keep residual risk reviewer-visible.
+- Review Studio surfaces this as the `permission-runtime` gate.
## Release Rule
High-risk secrets or unrestricted remote inline execution block governed release. Warnings are reviewer-visible but do not block v0 unless the release owner decides the target environment requires stricter policy.
+
+## Hash Scope
+
+`package_sha256` is a stable source-contract digest, not a generated archive digest. It covers the skill entrypoint, metadata, scripts, references, evals, runtime, templates, security notes, Skill IR, and root control files. It deliberately excludes generated `reports/`, packaged `dist/` archives, and raw local telemetry so a report render or local adoption log cannot mutate the trust fingerprint.
+
+Use the package verification or registry audit report for the distributable archive checksum.
diff --git a/registry/examples/yao-meta-skill-1.0.0.json b/registry/examples/yao-meta-skill-1.0.0.json
new file mode 100644
index 0000000..2d5cd36
--- /dev/null
+++ b/registry/examples/yao-meta-skill-1.0.0.json
@@ -0,0 +1,43 @@
+{
+ "schema_version": "2.0",
+ "name": "yao-meta-skill",
+ "version": "1.0.0",
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes.",
+ "targets": [
+ "openai",
+ "claude",
+ "generic"
+ ],
+ "maturity": "governed",
+ "owner": "Yao Team",
+ "review_cadence": "quarterly",
+ "trust_level": "local",
+ "license": "MIT",
+ "checksums": {
+ "package_sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+ },
+ "compatibility": {
+ "openai": "pass",
+ "claude": "pass",
+ "generic": "pass"
+ },
+ "source": {
+ "skill_dir": ".",
+ "skill_ir": "skill-ir/examples/yao-meta-skill.json",
+ "ir_schema_version": "2.0.0",
+ "canonical_metadata": "agents/interface.yaml"
+ },
+ "artifacts": {
+ "overview_html": "reports/skill-overview.html",
+ "review_studio_html": "reports/review-studio.html",
+ "trust_report": "reports/security_trust_report.md",
+ "conformance_matrix": "reports/conformance_matrix.md",
+ "package_metadata": "registry/packages/yao-meta-skill.json"
+ },
+ "distribution": {
+ "archive_verified": false,
+ "archive_sha256": "",
+ "package_verification": ""
+ },
+ "generated_at": "2026-06-12"
+}
diff --git a/registry/index.json b/registry/index.json
new file mode 100644
index 0000000..46e108d
--- /dev/null
+++ b/registry/index.json
@@ -0,0 +1,21 @@
+{
+ "schema_version": "2.0",
+ "generated_at": "2026-06-13",
+ "package_count": 1,
+ "packages": [
+ {
+ "name": "yao-meta-skill",
+ "version": "1.1.0",
+ "maturity": "governed",
+ "owner": "Yao Team",
+ "targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ],
+ "package_metadata": "registry/packages/yao-meta-skill.json",
+ "package_sha256": "9f1d53dbaeb1c90c80d7ffbbc1d10473e50b8032acda68332fbae551bb246abe"
+ }
+ ]
+}
diff --git a/registry/index.schema.json b/registry/index.schema.json
new file mode 100644
index 0000000..b48881e
--- /dev/null
+++ b/registry/index.schema.json
@@ -0,0 +1,30 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://yao.example/registry-index.schema.json",
+ "title": "Yao Skill Registry Index",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["schema_version", "generated_at", "package_count", "packages"],
+ "properties": {
+ "schema_version": {"const": "2.0"},
+ "generated_at": {"type": "string"},
+ "package_count": {"type": "integer", "minimum": 0},
+ "packages": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["name", "version", "maturity", "owner", "targets", "package_metadata", "package_sha256"],
+ "properties": {
+ "name": {"type": "string", "minLength": 1},
+ "version": {"type": "string", "minLength": 1},
+ "maturity": {"type": "string", "minLength": 1},
+ "owner": {"type": "string", "minLength": 1},
+ "targets": {"type": "array", "items": {"type": "string"}},
+ "package_metadata": {"type": "string", "minLength": 1},
+ "package_sha256": {"type": "string", "minLength": 64, "maxLength": 64}
+ }
+ }
+ }
+ }
+}
diff --git a/registry/package.schema.json b/registry/package.schema.json
new file mode 100644
index 0000000..f714b79
--- /dev/null
+++ b/registry/package.schema.json
@@ -0,0 +1,53 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://yao.example/registry-package.schema.json",
+ "title": "Yao Skill Registry Package",
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "schema_version",
+ "name",
+ "version",
+ "description",
+ "targets",
+ "maturity",
+ "owner",
+ "review_cadence",
+ "trust_level",
+ "license",
+ "checksums",
+ "compatibility",
+ "source",
+ "artifacts",
+ "generated_at"
+ ],
+ "properties": {
+ "schema_version": {"const": "2.0"},
+ "name": {"type": "string", "minLength": 1},
+ "version": {"type": "string", "minLength": 1},
+ "description": {"type": "string", "minLength": 1},
+ "targets": {"type": "array", "items": {"type": "string"}},
+ "maturity": {"type": "string", "minLength": 1},
+ "owner": {"type": "string", "minLength": 1},
+ "review_cadence": {"type": "string", "minLength": 1},
+ "trust_level": {"type": "string", "minLength": 1},
+ "license": {"type": "string", "minLength": 1},
+ "checksums": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["package_sha256"],
+ "properties": {
+ "package_sha256": {"type": "string", "minLength": 64, "maxLength": 64},
+ "archive_sha256": {"type": "string", "minLength": 64, "maxLength": 64}
+ }
+ },
+ "compatibility": {
+ "type": "object",
+ "additionalProperties": {"enum": ["pass", "warn", "fail", "missing", "unknown"]}
+ },
+ "source": {"type": "object"},
+ "artifacts": {"type": "object"},
+ "distribution": {"type": "object"},
+ "generated_at": {"type": "string"}
+ }
+}
diff --git a/registry/packages/yao-meta-skill.json b/registry/packages/yao-meta-skill.json
new file mode 100644
index 0000000..72a338c
--- /dev/null
+++ b/registry/packages/yao-meta-skill.json
@@ -0,0 +1,56 @@
+{
+ "schema_version": "2.0",
+ "name": "yao-meta-skill",
+ "version": "1.1.0",
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ],
+ "maturity": "governed",
+ "owner": "Yao Team",
+ "review_cadence": "quarterly",
+ "trust_level": "local",
+ "license": "MIT",
+ "checksums": {
+ "package_sha256": "9f1d53dbaeb1c90c80d7ffbbc1d10473e50b8032acda68332fbae551bb246abe",
+ "archive_sha256": "4d1227dc0996a97aa4987761d46081391fe15b36362e19765e1e7aa8e5d41c06"
+ },
+ "compatibility": {
+ "openai": "pass",
+ "claude": "pass",
+ "agent-skills": "pass",
+ "vscode": "pass",
+ "generic": "pass",
+ "agent-skills-compatible": "pass"
+ },
+ "source": {
+ "skill_dir": ".",
+ "skill_ir": "skill-ir/examples/yao-meta-skill.json",
+ "ir_schema_version": "2.0.0",
+ "canonical_metadata": "agents/interface.yaml"
+ },
+ "artifacts": {
+ "overview_html": "reports/skill-overview.html",
+ "review_studio_html": "reports/review-studio.html",
+ "trust_report": "reports/security_trust_report.md",
+ "conformance_matrix": "reports/conformance_matrix.md",
+ "compiled_targets": "reports/compiled_targets.md",
+ "package_verification": "reports/package_verification.md",
+ "install_simulation": "reports/install_simulation.md",
+ "adoption_drift": "reports/adoption_drift_report.md",
+ "review_waivers": "reports/review_waivers.md",
+ "review_annotations": "reports/review_annotations.md",
+ "package_metadata": "registry/packages/yao-meta-skill.json"
+ },
+ "distribution": {
+ "archive_verified": true,
+ "archive_sha256": "4d1227dc0996a97aa4987761d46081391fe15b36362e19765e1e7aa8e5d41c06",
+ "package_verification": "reports/package_verification.json",
+ "install_simulated": true,
+ "install_simulation": "reports/install_simulation.json"
+ },
+ "generated_at": "2026-06-13"
+}
diff --git a/reports/adoption_drift_report.json b/reports/adoption_drift_report.json
new file mode 100644
index 0000000..8575418
--- /dev/null
+++ b/reports/adoption_drift_report.json
@@ -0,0 +1,76 @@
+{
+ "ok": true,
+ "schema_version": "2.0",
+ "generated_at": "2026-06-13T09:57:51Z",
+ "skill_dir": ".",
+ "privacy_contract": {
+ "storage": "local-first",
+ "event_scope": "metadata-only",
+ "raw_content_allowed": false,
+ "raw_event_log_packaged": false,
+ "blocked_fields": [
+ "content",
+ "input",
+ "inputs",
+ "message",
+ "messages",
+ "note",
+ "output",
+ "outputs",
+ "prompt",
+ "raw",
+ "text",
+ "transcript"
+ ]
+ },
+ "summary": {
+ "event_count": 1,
+ "activation_count": 1,
+ "accepted_count": 1,
+ "edited_count": 0,
+ "rejected_count": 0,
+ "missed_count": 0,
+ "failed_count": 0,
+ "adoption_rate": 100.0,
+ "missed_trigger_count": 0,
+ "wrong_trigger_count": 0,
+ "bad_output_count": 0,
+ "script_error_count": 0,
+ "missing_resource_count": 0,
+ "review_overdue_count": 0,
+ "risk_band": "low",
+ "event_types": {
+ "skill_activation": 1
+ },
+ "failure_types": {}
+ },
+ "adoption_by_skill": [
+ {
+ "skill": "yao-meta-skill",
+ "events": 1,
+ "accepted": 1,
+ "edited": 0,
+ "rejected": 0,
+ "missed": 0,
+ "adoption_rate": 100.0
+ }
+ ],
+ "next_iteration_candidates": [],
+ "recent_events": [
+ {
+ "event": "skill_activation",
+ "skill": "yao-meta-skill",
+ "version": "1.1.0",
+ "activation_type": "explicit",
+ "outcome": "accepted",
+ "failure_type": "none",
+ "timestamp": "2026-06-13T10:00:00Z"
+ }
+ ],
+ "failures": [],
+ "artifacts": {
+ "events_jsonl": "tests/tmp_review_studio/telemetry_events.jsonl",
+ "json": "reports/adoption_drift_report.json",
+ "markdown": "reports/adoption_drift_report.md"
+ }
+}
diff --git a/reports/adoption_drift_report.md b/reports/adoption_drift_report.md
new file mode 100644
index 0000000..743dd61
--- /dev/null
+++ b/reports/adoption_drift_report.md
@@ -0,0 +1,35 @@
+# Adoption And Drift Report
+
+Local-first, metadata-only telemetry for skill operations. Raw prompts, outputs, transcripts, and notes are not allowed in the event stream.
+
+## Summary
+
+- Events: `1`
+- Activation events: `1`
+- Adoption rate: `100.0`
+- Missed trigger signals: `0`
+- Bad output signals: `0`
+- Script error signals: `0`
+- Review overdue signals: `0`
+- Risk band: `low`
+
+## Privacy Contract
+
+- Storage is local-first.
+- Events are metadata-only.
+- Raw user prompts, model outputs, transcripts, notes, and messages are blocked.
+- Distributed packages should include this aggregate report, not raw `reports/telemetry_events.jsonl`.
+
+## Adoption By Skill
+
+| Skill | Events | Accepted | Edited | Rejected | Missed | Adoption Rate |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `yao-meta-skill` | 1 | 1 | 0 | 0 | 0 | 100.0 |
+
+## Next Iteration Candidates
+
+- No telemetry-driven iteration candidate yet.
+
+## Recent Metadata Events
+
+- `2026-06-13T10:00:00Z` `yao-meta-skill` event=`skill_activation` activation=`explicit` outcome=`accepted` failure=`none`
diff --git a/reports/artifact-design-profile.json b/reports/artifact-design-profile.json
index 7f52095..2e76f3c 100644
--- a/reports/artifact-design-profile.json
+++ b/reports/artifact-design-profile.json
@@ -1,6 +1,6 @@
{
"skill_name": "yao-meta-skill",
- "design_system": "review studio",
+ "design_system": "metric editorial",
"primary_artifact": {
"key": "code_or_cli",
"label": "Code, CLI, or implementation guide",
@@ -36,12 +36,22 @@
{
"key": "review_viewer",
"label": "Review viewer",
- "score": 1,
+ "score": 2,
"matched_keywords": [
- "review"
+ "review",
+ "viewer"
],
"direction": "Side-by-side reviewer studio with explicit tradeoffs, evidence readiness, and fast paths for approving, blocking, or requesting one focused fix."
},
+ {
+ "key": "dashboard",
+ "label": "Dashboard or metrics page",
+ "score": 1,
+ "matched_keywords": [
+ "table"
+ ],
+ "direction": "Metric-first dashboard with stable dimensions, short labels, visible deltas, and narrative callouts only where they change interpretation."
+ },
{
"key": "visual_capture",
"label": "Screenshot or visual evidence",
diff --git a/reports/artifact-design-profile.md b/reports/artifact-design-profile.md
index 000e94b..4b70889 100644
--- a/reports/artifact-design-profile.md
+++ b/reports/artifact-design-profile.md
@@ -1,7 +1,7 @@
# Artifact Design Profile
Skill: `yao-meta-skill`
-Design system: `review studio`
+Design system: `metric editorial`
## Primary Artifact Direction
@@ -22,10 +22,15 @@ Execution-focused technical artifact with environment assumptions, copyable comm
- Direction: High-trust editorial report with a clear first-screen thesis, compact evidence blocks, and decisions separated from supporting detail.
### Review viewer
-- Matched keywords: review
-- Score: `1`
+- Matched keywords: review, viewer
+- Score: `2`
- Direction: Side-by-side reviewer studio with explicit tradeoffs, evidence readiness, and fast paths for approving, blocking, or requesting one focused fix.
+### Dashboard or metrics page
+- Matched keywords: table
+- Score: `1`
+- Direction: Metric-first dashboard with stable dimensions, short labels, visible deltas, and narrative callouts only where they change interpretation.
+
### Screenshot or visual evidence
- Matched keywords: screenshot
- Score: `1`
diff --git a/reports/compiled_targets.json b/reports/compiled_targets.json
new file mode 100644
index 0000000..0f32d4d
--- /dev/null
+++ b/reports/compiled_targets.json
@@ -0,0 +1,3130 @@
+{
+ "schema_version": "1.0",
+ "ok": true,
+ "generated_at": "2026-06-13",
+ "skill_dir": ".",
+ "summary": {
+ "target_count": 4,
+ "pass_count": 4,
+ "warn_count": 0,
+ "block_count": 0,
+ "failure_count": 0,
+ "warning_count": 0
+ },
+ "targets": [
+ {
+ "schema_version": "1.0",
+ "target": "openai",
+ "status": "pass",
+ "compiler": {
+ "name": "yao-skill-ir-compiler",
+ "schema_version": "1.0",
+ "source": "skill-ir",
+ "ir_source": "skill-ir/examples/yao-meta-skill.json",
+ "ir_schema_version": "2.0.0"
+ },
+ "source": {
+ "skill_dir": ".",
+ "canonical_metadata": "agents/interface.yaml",
+ "declared_targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ]
+ },
+ "compiled_contract": {
+ "name": "yao-meta-skill",
+ "title": "Yao Meta Skill",
+ "version": "1.1.0",
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "job_to_be_done": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.",
+ "trigger": {
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "should_trigger": [
+ "Create a skill from this repeated workflow.",
+ "Turn this runbook into a reusable agent skill.",
+ "Convert this process note into a reusable skill package for the team.",
+ "Improve this skill description and add evals.",
+ "Refactor this prompt into a proper skill package.",
+ "Package this skill for team reuse.",
+ "Create a meta-skill for packaging internal workflows.",
+ "Standardize this recurring workflow as a shareable skill package with references."
+ ],
+ "should_not_trigger": [
+ "Explain what a workflow is.",
+ "Just explain what a skill is.",
+ "Summarize this random note.",
+ "Translate this README into Japanese.",
+ "Write a product headline for this landing page.",
+ "Draft a blog title for this article.",
+ "Rewrite this paragraph more clearly, but do not package anything.",
+ "Explain the difference between a runbook and a workflow.",
+ "one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill",
+ "general code review or debugging unless the user is packaging that workflow as a skill"
+ ],
+ "edge_cases": [
+ "Create a one-off prompt for this task.",
+ "Write a custom answer for this request without creating a skill package.",
+ "Help me brainstorm process ideas without building a skill.",
+ "Improve this README but do not turn it into a skill.",
+ "Make a checklist for this task, but not a reusable skill.",
+ "Create a reusable-looking checklist, but keep it as a plain note instead of a skill.",
+ "Review this process note and explain it, no packaging needed.",
+ "Turn this into a checklist and template, but stop short of making a full skill."
+ ]
+ },
+ "workflow": {
+ "steps": [
+ "Decide whether the request should become a skill and choose the lightest fit.",
+ "Capture job, output, exclusions, constraints, and standards.",
+ "Run reference scan: external benchmarks first, user references second, local fit third; surface only uncertainty or conflict.",
+ "Write the `description` early and test route quality before expanding the package.",
+ "Add output-risk, artifact-design, prompt-quality, and system-model reports only when they matter.",
+ "Add only folders and gates that earn their keep.",
+ "Surface the top three next iteration directions."
+ ],
+ "decision_points": [
+ "Route by frontmatter `description`.",
+ "Keep `SKILL.md` lean; put guidance in `references/`, logic in `scripts/`, and evidence in `reports/`.",
+ "Use the lightest reliable process.",
+ "`Scaffold`: exploratory or personal.",
+ "`Production`: team reuse.",
+ "`Library`: shared infrastructure.",
+ "Ask one focused clarification when the real job, output, or exclusion boundary is unclear.",
+ "Escalate visible tradeoffs when benchmark patterns conflict with local privacy, naming, or governance constraints.",
+ "Do not silently broaden the skill into adjacent jobs just because the examples are nearby."
+ ],
+ "failure_modes": [
+ "Tables can render as dense grids with weak hierarchy or poor mobile readability.",
+ "Long bullets can make the output look complete while hiding the actual decision logic.",
+ "Footnote markers or dense citation notes can interrupt the reading flow.",
+ "Evidence can be over-attached to obvious statements and under-attached to risky claims.",
+ "Screenshots can be captured from the wrong state, wrong viewport, or wrong crop.",
+ "Missing screenshots can cause the skill to invent visual references instead of declaring the gap.",
+ "Users start invoking the skill for adjacent one-off or explanation-only requests.",
+ "Outputs remain valid but become generic, cluttered, or weakly aligned with the user's domain.",
+ "Borrowed benchmark patterns no longer fit the local job or add ceremony without payoff.",
+ "Skill usage becomes team-critical while ownership, review cadence, or rollback evidence stays informal."
+ ]
+ },
+ "resources": {
+ "references": [
+ "references/artifact-design-doctrine.md",
+ "references/authoring-discipline.md",
+ "references/distribution-registry-method.md",
+ "references/eval-playbook.md",
+ "references/gate-selection.md",
+ "references/governance.md",
+ "references/human-review-template.md",
+ "references/intent-dialogue.md",
+ "references/iteration-philosophy.md",
+ "references/non-skill-decision-tree.md",
+ "references/operating-modes.md",
+ "references/output-eval-method.md",
+ "references/output-quality-risk.md",
+ "references/output-visual-quality.md",
+ "references/packaging-contracts.md",
+ "references/pattern-extraction-doctrine.md",
+ "references/platform-capability-matrix.md",
+ "references/prompt-engineering-doctrine.md",
+ "references/qa-ladder.md",
+ "references/reference-scan.md",
+ "references/regression-cause-taxonomy.md",
+ "references/resource-boundaries.md",
+ "references/review-studio-method.md",
+ "references/review-waiver-method.md",
+ "references/runtime-conformance-method.md",
+ "references/skill-archetypes.md",
+ "references/skill-atlas-method.md",
+ "references/skill-engineering-method.md",
+ "references/skill-ir-method.md",
+ "references/systems-thinking-doctrine.md",
+ "references/telemetry-drift-method.md",
+ "references/trust-security-method.md"
+ ],
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/context_sizer.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/diff_eval.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/governance_check.py",
+ "scripts/init_skill.py",
+ "scripts/judge_blind_eval.py",
+ "scripts/lint_skill.py",
+ "scripts/local_output_eval_runner.py",
+ "scripts/optimize_description.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/resource_boundary_check.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/skill_report_charts.py",
+ "scripts/skill_report_metrics.py",
+ "scripts/skill_report_model.py",
+ "scripts/sync_local_install.py",
+ "scripts/trigger_eval.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/validate_skill.py",
+ "scripts/verify_package.py",
+ "scripts/yao.py"
+ ],
+ "assets": [
+ "templates/basic_skill.md.j2",
+ "templates/complex_skill.md.j2"
+ ],
+ "reports": [
+ "reports/benchmark_methodology.md",
+ "reports/intent-context.json",
+ "reports/intent-confidence.json",
+ "reports/intent-confidence.md",
+ "reports/reference-synthesis.json",
+ "reports/reference-synthesis.md",
+ "reports/output-risk-profile.json",
+ "reports/output-risk-profile.md",
+ "reports/artifact-design-profile.json",
+ "reports/artifact-design-profile.md",
+ "reports/prompt-quality-profile.json",
+ "reports/prompt-quality-profile.md",
+ "reports/system-model.json",
+ "reports/system-model.md",
+ "reports/iteration-directions.json",
+ "reports/iteration-directions.md",
+ "reports/skill-overview.json",
+ "reports/skill-overview.html",
+ "reports/output_quality_scorecard.json",
+ "reports/output_quality_scorecard.md",
+ "reports/output_execution_runs.json",
+ "reports/output_execution_runs.md",
+ "reports/output_blind_review_pack.json",
+ "reports/output_blind_review_pack.md",
+ "reports/output_blind_answer_key.json",
+ "reports/output_review_adjudication.json",
+ "reports/output_review_adjudication.md",
+ "reports/review_annotations.json",
+ "reports/review_annotations.md",
+ "reports/conformance_matrix.json",
+ "reports/conformance_matrix.md",
+ "reports/security_trust_report.json",
+ "reports/security_trust_report.md",
+ "reports/runtime_permission_probes.json",
+ "reports/runtime_permission_probes.md",
+ "reports/skill_atlas.json",
+ "reports/skill_atlas.html",
+ "reports/skill-os-2-review.md",
+ "reports/portability_score.json",
+ "reports/portability_score.md",
+ "reports/governance_score.json"
+ ],
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ }
+ },
+ "eval_plan": {
+ "trigger": [
+ "evals/README.md",
+ "evals/adversarial/trigger_cases.json",
+ "evals/blind_holdout/trigger_cases.json",
+ "evals/confusion/route_cases.json",
+ "evals/dev/trigger_cases.json",
+ "evals/failure-cases.md",
+ "evals/history/2026-03-31-context-first-pack.json",
+ "evals/history/2026-03-31-family-suite-expansion.json",
+ "evals/history/2026-03-31-governance-quality-gates.json",
+ "evals/history/2026-03-31-governed-assets-and-history.json",
+ "evals/history/2026-04-01-route-scorecard-foundation.json",
+ "evals/history/README.md",
+ "evals/history/description_optimization/2026-03-31-description-optimization-suite.json",
+ "evals/history/description_optimization/2026-04-01-adversarial-calibration-and-family-drift.json",
+ "evals/history/description_optimization/2026-04-01-blind-holdout-and-drift-history.json",
+ "evals/history/description_optimization/2026-04-01-judge-backed-blind-eval.json",
+ "evals/history/description_optimization/README.md",
+ "evals/holdout/trigger_cases.json",
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json",
+ "evals/packaging_expectations.json",
+ "evals/promotion_policy.md",
+ "evals/semantic_config.json",
+ "evals/train/trigger_cases.json",
+ "evals/trigger_cases.json"
+ ],
+ "output": [
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json"
+ ],
+ "adversarial": [
+ "evals/adversarial/trigger_cases.json"
+ ],
+ "baseline": "without_skill",
+ "counts": {
+ "trigger": 26,
+ "output": 3,
+ "adversarial": 1,
+ "baseline": 1
+ }
+ },
+ "risk": {
+ "output_risk": "high",
+ "execution_risk": "medium",
+ "trust_boundary": "external"
+ },
+ "governance": {
+ "owner": "Yao Team",
+ "maturity": "governed",
+ "review_cadence": "quarterly",
+ "review_due": ""
+ },
+ "runtime": {
+ "activation": {
+ "mode": "manual",
+ "paths": []
+ },
+ "execution": {
+ "context": "inline",
+ "shell": "bash"
+ },
+ "trust": {
+ "source_tier": "local",
+ "remote_inline_execution": "forbid",
+ "remote_metadata_policy": "allow-metadata-only"
+ },
+ "adapter_targets": [
+ "openai",
+ "claude",
+ "generic"
+ ],
+ "canonical_format": "agent-skills"
+ },
+ "permissions": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "source_files_count": 6,
+ "target": "openai",
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "openai",
+ "permission_model": "metadata-only",
+ "native_enforcement": false,
+ "representation": "targets/openai/agents/openai.yaml::compatibility.permission_contract plus adapter.json",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "OpenAI target carries permission metadata for reviewer visibility; host enforcement remains outside the package."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "openai",
+ "native_surface": "OpenAI-style interface metadata plus neutral Agent Skills source",
+ "activation": {
+ "policy": "Use frontmatter description for catalog routing and targets/openai/agents/openai.yaml for display name, default prompt, and compatibility metadata.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Ship the neutral source tree and expose OpenAI-facing interface metadata as a generated companion file.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "targets/openai/adapter.json",
+ "targets/openai/agents/openai.yaml"
+ ]
+ },
+ "scripts": {
+ "strategy": "Keep scripts as local package resources; expose help-smoke and permission metadata for reviewer approval before execution.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "metadata-only",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "targets/openai/agents/openai.yaml",
+ "targets/openai/adapter.json",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "If OpenAI-native metadata is ignored, the package remains readable as neutral Agent Skills source.",
+ "unsupported_native_features": [
+ "client-native permission prompts",
+ "provider-executed scripts",
+ "client-native script permission prompts are represented as permission contract metadata"
+ ]
+ },
+ "install_scope": "plugin or skill package consumer"
+ },
+ "degradation_strategy": "metadata-adapter",
+ "target_runtime": {
+ "adapter_mode": "metadata-adapter",
+ "generated_files": [
+ "targets/openai/adapter.json",
+ "targets/openai/agents/openai.yaml"
+ ],
+ "metadata_mapping": {
+ "display_name": "targets/openai/agents/openai.yaml::interface.display_name",
+ "default_prompt": "targets/openai/agents/openai.yaml::interface.default_prompt",
+ "activation": "targets/openai/agents/openai.yaml::compatibility.activation_mode",
+ "execution": "targets/openai/agents/openai.yaml::compatibility.execution_context",
+ "trust": "targets/openai/agents/openai.yaml::compatibility.trust_level",
+ "permissions": "targets/openai/agents/openai.yaml::compatibility.permission_contract",
+ "degradation": "targets/openai/agents/openai.yaml::compatibility.degradation_strategy"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow-counts",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "native_surface": "OpenAI-style interface metadata plus neutral Agent Skills source"
+ }
+ },
+ "permission_contract": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "openai",
+ "permission_model": "metadata-only",
+ "native_enforcement": false,
+ "representation": "targets/openai/agents/openai.yaml::compatibility.permission_contract plus adapter.json",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "OpenAI target carries permission metadata for reviewer visibility; host enforcement remains outside the package."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "openai",
+ "native_surface": "OpenAI-style interface metadata plus neutral Agent Skills source",
+ "activation": {
+ "policy": "Use frontmatter description for catalog routing and targets/openai/agents/openai.yaml for display name, default prompt, and compatibility metadata.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Ship the neutral source tree and expose OpenAI-facing interface metadata as a generated companion file.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "targets/openai/adapter.json",
+ "targets/openai/agents/openai.yaml"
+ ]
+ },
+ "scripts": {
+ "strategy": "Keep scripts as local package resources; expose help-smoke and permission metadata for reviewer approval before execution.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "metadata-only",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "targets/openai/agents/openai.yaml",
+ "targets/openai/adapter.json",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "If OpenAI-native metadata is ignored, the package remains readable as neutral Agent Skills source.",
+ "unsupported_native_features": [
+ "client-native permission prompts",
+ "provider-executed scripts",
+ "client-native script permission prompts are represented as permission contract metadata"
+ ]
+ },
+ "install_scope": "plugin or skill package consumer"
+ },
+ "target_transform": {
+ "target": "openai",
+ "adapter_mode": "metadata-adapter",
+ "generated_files": [
+ "targets/openai/adapter.json",
+ "targets/openai/agents/openai.yaml"
+ ],
+ "metadata_mapping": {
+ "display_name": "targets/openai/agents/openai.yaml::interface.display_name",
+ "default_prompt": "targets/openai/agents/openai.yaml::interface.default_prompt",
+ "activation": "targets/openai/agents/openai.yaml::compatibility.activation_mode",
+ "execution": "targets/openai/agents/openai.yaml::compatibility.execution_context",
+ "trust": "targets/openai/agents/openai.yaml::compatibility.trust_level",
+ "permissions": "targets/openai/agents/openai.yaml::compatibility.permission_contract",
+ "degradation": "targets/openai/agents/openai.yaml::compatibility.degradation_strategy"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow-counts",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "degradation_strategy": "metadata-adapter",
+ "permission_representation": "targets/openai/agents/openai.yaml::compatibility.permission_contract plus adapter.json",
+ "native_surface": "OpenAI-style interface metadata plus neutral Agent Skills source",
+ "activation_policy": "Use frontmatter description for catalog routing and targets/openai/agents/openai.yaml for display name, default prompt, and compatibility metadata.",
+ "resource_strategy": "Ship the neutral source tree and expose OpenAI-facing interface metadata as a generated companion file.",
+ "script_strategy": "Keep scripts as local package resources; expose help-smoke and permission metadata for reviewer approval before execution.",
+ "permission_enforcement": "metadata-only"
+ },
+ "unsupported_features": [
+ "client-native script permission prompts are represented as permission contract metadata"
+ ],
+ "warnings": [],
+ "failures": []
+ },
+ {
+ "schema_version": "1.0",
+ "target": "claude",
+ "status": "pass",
+ "compiler": {
+ "name": "yao-skill-ir-compiler",
+ "schema_version": "1.0",
+ "source": "skill-ir",
+ "ir_source": "skill-ir/examples/yao-meta-skill.json",
+ "ir_schema_version": "2.0.0"
+ },
+ "source": {
+ "skill_dir": ".",
+ "canonical_metadata": "agents/interface.yaml",
+ "declared_targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ]
+ },
+ "compiled_contract": {
+ "name": "yao-meta-skill",
+ "title": "Yao Meta Skill",
+ "version": "1.1.0",
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "job_to_be_done": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.",
+ "trigger": {
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "should_trigger": [
+ "Create a skill from this repeated workflow.",
+ "Turn this runbook into a reusable agent skill.",
+ "Convert this process note into a reusable skill package for the team.",
+ "Improve this skill description and add evals.",
+ "Refactor this prompt into a proper skill package.",
+ "Package this skill for team reuse.",
+ "Create a meta-skill for packaging internal workflows.",
+ "Standardize this recurring workflow as a shareable skill package with references."
+ ],
+ "should_not_trigger": [
+ "Explain what a workflow is.",
+ "Just explain what a skill is.",
+ "Summarize this random note.",
+ "Translate this README into Japanese.",
+ "Write a product headline for this landing page.",
+ "Draft a blog title for this article.",
+ "Rewrite this paragraph more clearly, but do not package anything.",
+ "Explain the difference between a runbook and a workflow.",
+ "one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill",
+ "general code review or debugging unless the user is packaging that workflow as a skill"
+ ],
+ "edge_cases": [
+ "Create a one-off prompt for this task.",
+ "Write a custom answer for this request without creating a skill package.",
+ "Help me brainstorm process ideas without building a skill.",
+ "Improve this README but do not turn it into a skill.",
+ "Make a checklist for this task, but not a reusable skill.",
+ "Create a reusable-looking checklist, but keep it as a plain note instead of a skill.",
+ "Review this process note and explain it, no packaging needed.",
+ "Turn this into a checklist and template, but stop short of making a full skill."
+ ]
+ },
+ "workflow": {
+ "steps": [
+ "Decide whether the request should become a skill and choose the lightest fit.",
+ "Capture job, output, exclusions, constraints, and standards.",
+ "Run reference scan: external benchmarks first, user references second, local fit third; surface only uncertainty or conflict.",
+ "Write the `description` early and test route quality before expanding the package.",
+ "Add output-risk, artifact-design, prompt-quality, and system-model reports only when they matter.",
+ "Add only folders and gates that earn their keep.",
+ "Surface the top three next iteration directions."
+ ],
+ "decision_points": [
+ "Route by frontmatter `description`.",
+ "Keep `SKILL.md` lean; put guidance in `references/`, logic in `scripts/`, and evidence in `reports/`.",
+ "Use the lightest reliable process.",
+ "`Scaffold`: exploratory or personal.",
+ "`Production`: team reuse.",
+ "`Library`: shared infrastructure.",
+ "Ask one focused clarification when the real job, output, or exclusion boundary is unclear.",
+ "Escalate visible tradeoffs when benchmark patterns conflict with local privacy, naming, or governance constraints.",
+ "Do not silently broaden the skill into adjacent jobs just because the examples are nearby."
+ ],
+ "failure_modes": [
+ "Tables can render as dense grids with weak hierarchy or poor mobile readability.",
+ "Long bullets can make the output look complete while hiding the actual decision logic.",
+ "Footnote markers or dense citation notes can interrupt the reading flow.",
+ "Evidence can be over-attached to obvious statements and under-attached to risky claims.",
+ "Screenshots can be captured from the wrong state, wrong viewport, or wrong crop.",
+ "Missing screenshots can cause the skill to invent visual references instead of declaring the gap.",
+ "Users start invoking the skill for adjacent one-off or explanation-only requests.",
+ "Outputs remain valid but become generic, cluttered, or weakly aligned with the user's domain.",
+ "Borrowed benchmark patterns no longer fit the local job or add ceremony without payoff.",
+ "Skill usage becomes team-critical while ownership, review cadence, or rollback evidence stays informal."
+ ]
+ },
+ "resources": {
+ "references": [
+ "references/artifact-design-doctrine.md",
+ "references/authoring-discipline.md",
+ "references/distribution-registry-method.md",
+ "references/eval-playbook.md",
+ "references/gate-selection.md",
+ "references/governance.md",
+ "references/human-review-template.md",
+ "references/intent-dialogue.md",
+ "references/iteration-philosophy.md",
+ "references/non-skill-decision-tree.md",
+ "references/operating-modes.md",
+ "references/output-eval-method.md",
+ "references/output-quality-risk.md",
+ "references/output-visual-quality.md",
+ "references/packaging-contracts.md",
+ "references/pattern-extraction-doctrine.md",
+ "references/platform-capability-matrix.md",
+ "references/prompt-engineering-doctrine.md",
+ "references/qa-ladder.md",
+ "references/reference-scan.md",
+ "references/regression-cause-taxonomy.md",
+ "references/resource-boundaries.md",
+ "references/review-studio-method.md",
+ "references/review-waiver-method.md",
+ "references/runtime-conformance-method.md",
+ "references/skill-archetypes.md",
+ "references/skill-atlas-method.md",
+ "references/skill-engineering-method.md",
+ "references/skill-ir-method.md",
+ "references/systems-thinking-doctrine.md",
+ "references/telemetry-drift-method.md",
+ "references/trust-security-method.md"
+ ],
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/context_sizer.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/diff_eval.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/governance_check.py",
+ "scripts/init_skill.py",
+ "scripts/judge_blind_eval.py",
+ "scripts/lint_skill.py",
+ "scripts/local_output_eval_runner.py",
+ "scripts/optimize_description.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/resource_boundary_check.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/skill_report_charts.py",
+ "scripts/skill_report_metrics.py",
+ "scripts/skill_report_model.py",
+ "scripts/sync_local_install.py",
+ "scripts/trigger_eval.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/validate_skill.py",
+ "scripts/verify_package.py",
+ "scripts/yao.py"
+ ],
+ "assets": [
+ "templates/basic_skill.md.j2",
+ "templates/complex_skill.md.j2"
+ ],
+ "reports": [
+ "reports/benchmark_methodology.md",
+ "reports/intent-context.json",
+ "reports/intent-confidence.json",
+ "reports/intent-confidence.md",
+ "reports/reference-synthesis.json",
+ "reports/reference-synthesis.md",
+ "reports/output-risk-profile.json",
+ "reports/output-risk-profile.md",
+ "reports/artifact-design-profile.json",
+ "reports/artifact-design-profile.md",
+ "reports/prompt-quality-profile.json",
+ "reports/prompt-quality-profile.md",
+ "reports/system-model.json",
+ "reports/system-model.md",
+ "reports/iteration-directions.json",
+ "reports/iteration-directions.md",
+ "reports/skill-overview.json",
+ "reports/skill-overview.html",
+ "reports/output_quality_scorecard.json",
+ "reports/output_quality_scorecard.md",
+ "reports/output_execution_runs.json",
+ "reports/output_execution_runs.md",
+ "reports/output_blind_review_pack.json",
+ "reports/output_blind_review_pack.md",
+ "reports/output_blind_answer_key.json",
+ "reports/output_review_adjudication.json",
+ "reports/output_review_adjudication.md",
+ "reports/review_annotations.json",
+ "reports/review_annotations.md",
+ "reports/conformance_matrix.json",
+ "reports/conformance_matrix.md",
+ "reports/security_trust_report.json",
+ "reports/security_trust_report.md",
+ "reports/runtime_permission_probes.json",
+ "reports/runtime_permission_probes.md",
+ "reports/skill_atlas.json",
+ "reports/skill_atlas.html",
+ "reports/skill-os-2-review.md",
+ "reports/portability_score.json",
+ "reports/portability_score.md",
+ "reports/governance_score.json"
+ ],
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ }
+ },
+ "eval_plan": {
+ "trigger": [
+ "evals/README.md",
+ "evals/adversarial/trigger_cases.json",
+ "evals/blind_holdout/trigger_cases.json",
+ "evals/confusion/route_cases.json",
+ "evals/dev/trigger_cases.json",
+ "evals/failure-cases.md",
+ "evals/history/2026-03-31-context-first-pack.json",
+ "evals/history/2026-03-31-family-suite-expansion.json",
+ "evals/history/2026-03-31-governance-quality-gates.json",
+ "evals/history/2026-03-31-governed-assets-and-history.json",
+ "evals/history/2026-04-01-route-scorecard-foundation.json",
+ "evals/history/README.md",
+ "evals/history/description_optimization/2026-03-31-description-optimization-suite.json",
+ "evals/history/description_optimization/2026-04-01-adversarial-calibration-and-family-drift.json",
+ "evals/history/description_optimization/2026-04-01-blind-holdout-and-drift-history.json",
+ "evals/history/description_optimization/2026-04-01-judge-backed-blind-eval.json",
+ "evals/history/description_optimization/README.md",
+ "evals/holdout/trigger_cases.json",
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json",
+ "evals/packaging_expectations.json",
+ "evals/promotion_policy.md",
+ "evals/semantic_config.json",
+ "evals/train/trigger_cases.json",
+ "evals/trigger_cases.json"
+ ],
+ "output": [
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json"
+ ],
+ "adversarial": [
+ "evals/adversarial/trigger_cases.json"
+ ],
+ "baseline": "without_skill",
+ "counts": {
+ "trigger": 26,
+ "output": 3,
+ "adversarial": 1,
+ "baseline": 1
+ }
+ },
+ "risk": {
+ "output_risk": "high",
+ "execution_risk": "medium",
+ "trust_boundary": "external"
+ },
+ "governance": {
+ "owner": "Yao Team",
+ "maturity": "governed",
+ "review_cadence": "quarterly",
+ "review_due": ""
+ },
+ "runtime": {
+ "activation": {
+ "mode": "manual",
+ "paths": []
+ },
+ "execution": {
+ "context": "inline",
+ "shell": "bash"
+ },
+ "trust": {
+ "source_tier": "local",
+ "remote_inline_execution": "forbid",
+ "remote_metadata_policy": "allow-metadata-only"
+ },
+ "adapter_targets": [
+ "openai",
+ "claude",
+ "generic"
+ ],
+ "canonical_format": "agent-skills"
+ },
+ "permissions": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "source_files_count": 6,
+ "target": "claude",
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "claude",
+ "permission_model": "neutral-source-plus-adapter",
+ "native_enforcement": false,
+ "representation": "targets/claude/adapter.json::target_permission_contract and README notes",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "Claude-compatible package keeps permission intent in adapter metadata for install review."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "claude",
+ "native_surface": "Claude-compatible neutral source folder with adapter notes",
+ "activation": {
+ "policy": "Use SKILL.md frontmatter description as the primary activation contract and adapter.json for review metadata.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Preserve the source tree directly; write target notes in targets/claude/README.md.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "targets/claude/adapter.json",
+ "targets/claude/README.md"
+ ]
+ },
+ "scripts": {
+ "strategy": "Scripts remain local package resources and must be reviewed through trust and permission reports before use.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "metadata-fallback",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "targets/claude/README.md",
+ "targets/claude/adapter.json",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "If Claude-specific metadata is not consumed, SKILL.md and references remain the source of truth.",
+ "unsupported_native_features": [
+ "vendor-native permission enforcement",
+ "provider-specific execution transforms",
+ "vendor-native metadata fields are carried as adapter JSON and README notes"
+ ]
+ },
+ "install_scope": "user or project skill directory"
+ },
+ "degradation_strategy": "neutral-source-plus-adapter",
+ "target_runtime": {
+ "adapter_mode": "neutral-source-plus-adapter",
+ "generated_files": [
+ "targets/claude/adapter.json",
+ "targets/claude/README.md"
+ ],
+ "metadata_mapping": {
+ "display_name": "targets/claude/adapter.json::display_name",
+ "default_prompt": "targets/claude/adapter.json::default_prompt",
+ "activation": "targets/claude/adapter.json::activation_mode",
+ "execution": "targets/claude/adapter.json::execution_context",
+ "trust": "targets/claude/adapter.json::trust_level",
+ "permissions": "targets/claude/adapter.json::target_permission_contract",
+ "degradation": "targets/claude/adapter.json::degradation_strategy"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow-counts",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "native_surface": "Claude-compatible neutral source folder with adapter notes"
+ }
+ },
+ "permission_contract": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "claude",
+ "permission_model": "neutral-source-plus-adapter",
+ "native_enforcement": false,
+ "representation": "targets/claude/adapter.json::target_permission_contract and README notes",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "Claude-compatible package keeps permission intent in adapter metadata for install review."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "claude",
+ "native_surface": "Claude-compatible neutral source folder with adapter notes",
+ "activation": {
+ "policy": "Use SKILL.md frontmatter description as the primary activation contract and adapter.json for review metadata.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Preserve the source tree directly; write target notes in targets/claude/README.md.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "targets/claude/adapter.json",
+ "targets/claude/README.md"
+ ]
+ },
+ "scripts": {
+ "strategy": "Scripts remain local package resources and must be reviewed through trust and permission reports before use.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "metadata-fallback",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "targets/claude/README.md",
+ "targets/claude/adapter.json",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "If Claude-specific metadata is not consumed, SKILL.md and references remain the source of truth.",
+ "unsupported_native_features": [
+ "vendor-native permission enforcement",
+ "provider-specific execution transforms",
+ "vendor-native metadata fields are carried as adapter JSON and README notes"
+ ]
+ },
+ "install_scope": "user or project skill directory"
+ },
+ "target_transform": {
+ "target": "claude",
+ "adapter_mode": "neutral-source-plus-adapter",
+ "generated_files": [
+ "targets/claude/adapter.json",
+ "targets/claude/README.md"
+ ],
+ "metadata_mapping": {
+ "display_name": "targets/claude/adapter.json::display_name",
+ "default_prompt": "targets/claude/adapter.json::default_prompt",
+ "activation": "targets/claude/adapter.json::activation_mode",
+ "execution": "targets/claude/adapter.json::execution_context",
+ "trust": "targets/claude/adapter.json::trust_level",
+ "permissions": "targets/claude/adapter.json::target_permission_contract",
+ "degradation": "targets/claude/adapter.json::degradation_strategy"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow-counts",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "degradation_strategy": "neutral-source-plus-adapter",
+ "permission_representation": "targets/claude/adapter.json::target_permission_contract and README notes",
+ "native_surface": "Claude-compatible neutral source folder with adapter notes",
+ "activation_policy": "Use SKILL.md frontmatter description as the primary activation contract and adapter.json for review metadata.",
+ "resource_strategy": "Preserve the source tree directly; write target notes in targets/claude/README.md.",
+ "script_strategy": "Scripts remain local package resources and must be reviewed through trust and permission reports before use.",
+ "permission_enforcement": "metadata-fallback"
+ },
+ "unsupported_features": [
+ "vendor-native metadata fields are carried as adapter JSON and README notes"
+ ],
+ "warnings": [],
+ "failures": []
+ },
+ {
+ "schema_version": "1.0",
+ "target": "generic",
+ "status": "pass",
+ "compiler": {
+ "name": "yao-skill-ir-compiler",
+ "schema_version": "1.0",
+ "source": "skill-ir",
+ "ir_source": "skill-ir/examples/yao-meta-skill.json",
+ "ir_schema_version": "2.0.0"
+ },
+ "source": {
+ "skill_dir": ".",
+ "canonical_metadata": "agents/interface.yaml",
+ "declared_targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ]
+ },
+ "compiled_contract": {
+ "name": "yao-meta-skill",
+ "title": "Yao Meta Skill",
+ "version": "1.1.0",
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "job_to_be_done": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.",
+ "trigger": {
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "should_trigger": [
+ "Create a skill from this repeated workflow.",
+ "Turn this runbook into a reusable agent skill.",
+ "Convert this process note into a reusable skill package for the team.",
+ "Improve this skill description and add evals.",
+ "Refactor this prompt into a proper skill package.",
+ "Package this skill for team reuse.",
+ "Create a meta-skill for packaging internal workflows.",
+ "Standardize this recurring workflow as a shareable skill package with references."
+ ],
+ "should_not_trigger": [
+ "Explain what a workflow is.",
+ "Just explain what a skill is.",
+ "Summarize this random note.",
+ "Translate this README into Japanese.",
+ "Write a product headline for this landing page.",
+ "Draft a blog title for this article.",
+ "Rewrite this paragraph more clearly, but do not package anything.",
+ "Explain the difference between a runbook and a workflow.",
+ "one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill",
+ "general code review or debugging unless the user is packaging that workflow as a skill"
+ ],
+ "edge_cases": [
+ "Create a one-off prompt for this task.",
+ "Write a custom answer for this request without creating a skill package.",
+ "Help me brainstorm process ideas without building a skill.",
+ "Improve this README but do not turn it into a skill.",
+ "Make a checklist for this task, but not a reusable skill.",
+ "Create a reusable-looking checklist, but keep it as a plain note instead of a skill.",
+ "Review this process note and explain it, no packaging needed.",
+ "Turn this into a checklist and template, but stop short of making a full skill."
+ ]
+ },
+ "workflow": {
+ "steps": [
+ "Decide whether the request should become a skill and choose the lightest fit.",
+ "Capture job, output, exclusions, constraints, and standards.",
+ "Run reference scan: external benchmarks first, user references second, local fit third; surface only uncertainty or conflict.",
+ "Write the `description` early and test route quality before expanding the package.",
+ "Add output-risk, artifact-design, prompt-quality, and system-model reports only when they matter.",
+ "Add only folders and gates that earn their keep.",
+ "Surface the top three next iteration directions."
+ ],
+ "decision_points": [
+ "Route by frontmatter `description`.",
+ "Keep `SKILL.md` lean; put guidance in `references/`, logic in `scripts/`, and evidence in `reports/`.",
+ "Use the lightest reliable process.",
+ "`Scaffold`: exploratory or personal.",
+ "`Production`: team reuse.",
+ "`Library`: shared infrastructure.",
+ "Ask one focused clarification when the real job, output, or exclusion boundary is unclear.",
+ "Escalate visible tradeoffs when benchmark patterns conflict with local privacy, naming, or governance constraints.",
+ "Do not silently broaden the skill into adjacent jobs just because the examples are nearby."
+ ],
+ "failure_modes": [
+ "Tables can render as dense grids with weak hierarchy or poor mobile readability.",
+ "Long bullets can make the output look complete while hiding the actual decision logic.",
+ "Footnote markers or dense citation notes can interrupt the reading flow.",
+ "Evidence can be over-attached to obvious statements and under-attached to risky claims.",
+ "Screenshots can be captured from the wrong state, wrong viewport, or wrong crop.",
+ "Missing screenshots can cause the skill to invent visual references instead of declaring the gap.",
+ "Users start invoking the skill for adjacent one-off or explanation-only requests.",
+ "Outputs remain valid but become generic, cluttered, or weakly aligned with the user's domain.",
+ "Borrowed benchmark patterns no longer fit the local job or add ceremony without payoff.",
+ "Skill usage becomes team-critical while ownership, review cadence, or rollback evidence stays informal."
+ ]
+ },
+ "resources": {
+ "references": [
+ "references/artifact-design-doctrine.md",
+ "references/authoring-discipline.md",
+ "references/distribution-registry-method.md",
+ "references/eval-playbook.md",
+ "references/gate-selection.md",
+ "references/governance.md",
+ "references/human-review-template.md",
+ "references/intent-dialogue.md",
+ "references/iteration-philosophy.md",
+ "references/non-skill-decision-tree.md",
+ "references/operating-modes.md",
+ "references/output-eval-method.md",
+ "references/output-quality-risk.md",
+ "references/output-visual-quality.md",
+ "references/packaging-contracts.md",
+ "references/pattern-extraction-doctrine.md",
+ "references/platform-capability-matrix.md",
+ "references/prompt-engineering-doctrine.md",
+ "references/qa-ladder.md",
+ "references/reference-scan.md",
+ "references/regression-cause-taxonomy.md",
+ "references/resource-boundaries.md",
+ "references/review-studio-method.md",
+ "references/review-waiver-method.md",
+ "references/runtime-conformance-method.md",
+ "references/skill-archetypes.md",
+ "references/skill-atlas-method.md",
+ "references/skill-engineering-method.md",
+ "references/skill-ir-method.md",
+ "references/systems-thinking-doctrine.md",
+ "references/telemetry-drift-method.md",
+ "references/trust-security-method.md"
+ ],
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/context_sizer.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/diff_eval.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/governance_check.py",
+ "scripts/init_skill.py",
+ "scripts/judge_blind_eval.py",
+ "scripts/lint_skill.py",
+ "scripts/local_output_eval_runner.py",
+ "scripts/optimize_description.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/resource_boundary_check.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/skill_report_charts.py",
+ "scripts/skill_report_metrics.py",
+ "scripts/skill_report_model.py",
+ "scripts/sync_local_install.py",
+ "scripts/trigger_eval.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/validate_skill.py",
+ "scripts/verify_package.py",
+ "scripts/yao.py"
+ ],
+ "assets": [
+ "templates/basic_skill.md.j2",
+ "templates/complex_skill.md.j2"
+ ],
+ "reports": [
+ "reports/benchmark_methodology.md",
+ "reports/intent-context.json",
+ "reports/intent-confidence.json",
+ "reports/intent-confidence.md",
+ "reports/reference-synthesis.json",
+ "reports/reference-synthesis.md",
+ "reports/output-risk-profile.json",
+ "reports/output-risk-profile.md",
+ "reports/artifact-design-profile.json",
+ "reports/artifact-design-profile.md",
+ "reports/prompt-quality-profile.json",
+ "reports/prompt-quality-profile.md",
+ "reports/system-model.json",
+ "reports/system-model.md",
+ "reports/iteration-directions.json",
+ "reports/iteration-directions.md",
+ "reports/skill-overview.json",
+ "reports/skill-overview.html",
+ "reports/output_quality_scorecard.json",
+ "reports/output_quality_scorecard.md",
+ "reports/output_execution_runs.json",
+ "reports/output_execution_runs.md",
+ "reports/output_blind_review_pack.json",
+ "reports/output_blind_review_pack.md",
+ "reports/output_blind_answer_key.json",
+ "reports/output_review_adjudication.json",
+ "reports/output_review_adjudication.md",
+ "reports/review_annotations.json",
+ "reports/review_annotations.md",
+ "reports/conformance_matrix.json",
+ "reports/conformance_matrix.md",
+ "reports/security_trust_report.json",
+ "reports/security_trust_report.md",
+ "reports/runtime_permission_probes.json",
+ "reports/runtime_permission_probes.md",
+ "reports/skill_atlas.json",
+ "reports/skill_atlas.html",
+ "reports/skill-os-2-review.md",
+ "reports/portability_score.json",
+ "reports/portability_score.md",
+ "reports/governance_score.json"
+ ],
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ }
+ },
+ "eval_plan": {
+ "trigger": [
+ "evals/README.md",
+ "evals/adversarial/trigger_cases.json",
+ "evals/blind_holdout/trigger_cases.json",
+ "evals/confusion/route_cases.json",
+ "evals/dev/trigger_cases.json",
+ "evals/failure-cases.md",
+ "evals/history/2026-03-31-context-first-pack.json",
+ "evals/history/2026-03-31-family-suite-expansion.json",
+ "evals/history/2026-03-31-governance-quality-gates.json",
+ "evals/history/2026-03-31-governed-assets-and-history.json",
+ "evals/history/2026-04-01-route-scorecard-foundation.json",
+ "evals/history/README.md",
+ "evals/history/description_optimization/2026-03-31-description-optimization-suite.json",
+ "evals/history/description_optimization/2026-04-01-adversarial-calibration-and-family-drift.json",
+ "evals/history/description_optimization/2026-04-01-blind-holdout-and-drift-history.json",
+ "evals/history/description_optimization/2026-04-01-judge-backed-blind-eval.json",
+ "evals/history/description_optimization/README.md",
+ "evals/holdout/trigger_cases.json",
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json",
+ "evals/packaging_expectations.json",
+ "evals/promotion_policy.md",
+ "evals/semantic_config.json",
+ "evals/train/trigger_cases.json",
+ "evals/trigger_cases.json"
+ ],
+ "output": [
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json"
+ ],
+ "adversarial": [
+ "evals/adversarial/trigger_cases.json"
+ ],
+ "baseline": "without_skill",
+ "counts": {
+ "trigger": 26,
+ "output": 3,
+ "adversarial": 1,
+ "baseline": 1
+ }
+ },
+ "risk": {
+ "output_risk": "high",
+ "execution_risk": "medium",
+ "trust_boundary": "external"
+ },
+ "governance": {
+ "owner": "Yao Team",
+ "maturity": "governed",
+ "review_cadence": "quarterly",
+ "review_due": ""
+ },
+ "runtime": {
+ "activation": {
+ "mode": "manual",
+ "paths": []
+ },
+ "execution": {
+ "context": "inline",
+ "shell": "bash"
+ },
+ "trust": {
+ "source_tier": "local",
+ "remote_inline_execution": "forbid",
+ "remote_metadata_policy": "allow-metadata-only"
+ },
+ "adapter_targets": [
+ "openai",
+ "claude",
+ "generic"
+ ],
+ "canonical_format": "agent-skills"
+ },
+ "permissions": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "source_files_count": 6,
+ "target": "generic",
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "generic",
+ "permission_model": "agent-skills-compatible-metadata",
+ "native_enforcement": false,
+ "representation": "targets/generic/adapter.json::target_permission_contract",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "Generic target exposes permission metadata for downstream clients to enforce or review."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "generic",
+ "native_surface": "Agent Skills compatible neutral package",
+ "activation": {
+ "policy": "Use SKILL.md name and description; consumers decide automatic or manual activation.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Preserve references, scripts, assets, evals, reports, and adapter metadata as relative package resources.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "targets/generic/adapter.json"
+ ]
+ },
+ "scripts": {
+ "strategy": "Expose script and permission metadata for downstream clients or installers to enforce.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "consumer-enforced-or-metadata-only",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "targets/generic/adapter.json",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "Neutral source is the runtime fallback.",
+ "unsupported_native_features": []
+ },
+ "install_scope": "generic Agent Skills compatible root"
+ },
+ "degradation_strategy": "neutral-source",
+ "target_runtime": {
+ "adapter_mode": "agent-skills-compatible",
+ "generated_files": [
+ "targets/generic/adapter.json"
+ ],
+ "metadata_mapping": {
+ "display_name": "targets/generic/adapter.json::display_name",
+ "default_prompt": "targets/generic/adapter.json::default_prompt",
+ "activation": "targets/generic/adapter.json::activation_mode",
+ "execution": "targets/generic/adapter.json::execution_context",
+ "trust": "targets/generic/adapter.json::trust_level",
+ "permissions": "targets/generic/adapter.json::target_permission_contract",
+ "degradation": "targets/generic/adapter.json::degradation_strategy"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow-counts",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "native_surface": "Agent Skills compatible neutral package"
+ }
+ },
+ "permission_contract": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "generic",
+ "permission_model": "agent-skills-compatible-metadata",
+ "native_enforcement": false,
+ "representation": "targets/generic/adapter.json::target_permission_contract",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "Generic target exposes permission metadata for downstream clients to enforce or review."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "generic",
+ "native_surface": "Agent Skills compatible neutral package",
+ "activation": {
+ "policy": "Use SKILL.md name and description; consumers decide automatic or manual activation.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Preserve references, scripts, assets, evals, reports, and adapter metadata as relative package resources.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "targets/generic/adapter.json"
+ ]
+ },
+ "scripts": {
+ "strategy": "Expose script and permission metadata for downstream clients or installers to enforce.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "consumer-enforced-or-metadata-only",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "targets/generic/adapter.json",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "Neutral source is the runtime fallback.",
+ "unsupported_native_features": []
+ },
+ "install_scope": "generic Agent Skills compatible root"
+ },
+ "target_transform": {
+ "target": "generic",
+ "adapter_mode": "agent-skills-compatible",
+ "generated_files": [
+ "targets/generic/adapter.json"
+ ],
+ "metadata_mapping": {
+ "display_name": "targets/generic/adapter.json::display_name",
+ "default_prompt": "targets/generic/adapter.json::default_prompt",
+ "activation": "targets/generic/adapter.json::activation_mode",
+ "execution": "targets/generic/adapter.json::execution_context",
+ "trust": "targets/generic/adapter.json::trust_level",
+ "permissions": "targets/generic/adapter.json::target_permission_contract",
+ "degradation": "targets/generic/adapter.json::degradation_strategy"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow-counts",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "degradation_strategy": "neutral-source",
+ "permission_representation": "targets/generic/adapter.json::target_permission_contract",
+ "native_surface": "Agent Skills compatible neutral package",
+ "activation_policy": "Use SKILL.md name and description; consumers decide automatic or manual activation.",
+ "resource_strategy": "Preserve references, scripts, assets, evals, reports, and adapter metadata as relative package resources.",
+ "script_strategy": "Expose script and permission metadata for downstream clients or installers to enforce.",
+ "permission_enforcement": "consumer-enforced-or-metadata-only"
+ },
+ "unsupported_features": [],
+ "warnings": [],
+ "failures": []
+ },
+ {
+ "schema_version": "1.0",
+ "target": "agent-skills-compatible",
+ "status": "pass",
+ "compiler": {
+ "name": "yao-skill-ir-compiler",
+ "schema_version": "1.0",
+ "source": "skill-ir",
+ "ir_source": "skill-ir/examples/yao-meta-skill.json",
+ "ir_schema_version": "2.0.0"
+ },
+ "source": {
+ "skill_dir": ".",
+ "canonical_metadata": "agents/interface.yaml",
+ "declared_targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ]
+ },
+ "compiled_contract": {
+ "name": "yao-meta-skill",
+ "title": "Yao Meta Skill",
+ "version": "1.1.0",
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "job_to_be_done": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.",
+ "trigger": {
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "should_trigger": [
+ "Create a skill from this repeated workflow.",
+ "Turn this runbook into a reusable agent skill.",
+ "Convert this process note into a reusable skill package for the team.",
+ "Improve this skill description and add evals.",
+ "Refactor this prompt into a proper skill package.",
+ "Package this skill for team reuse.",
+ "Create a meta-skill for packaging internal workflows.",
+ "Standardize this recurring workflow as a shareable skill package with references."
+ ],
+ "should_not_trigger": [
+ "Explain what a workflow is.",
+ "Just explain what a skill is.",
+ "Summarize this random note.",
+ "Translate this README into Japanese.",
+ "Write a product headline for this landing page.",
+ "Draft a blog title for this article.",
+ "Rewrite this paragraph more clearly, but do not package anything.",
+ "Explain the difference between a runbook and a workflow.",
+ "one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill",
+ "general code review or debugging unless the user is packaging that workflow as a skill"
+ ],
+ "edge_cases": [
+ "Create a one-off prompt for this task.",
+ "Write a custom answer for this request without creating a skill package.",
+ "Help me brainstorm process ideas without building a skill.",
+ "Improve this README but do not turn it into a skill.",
+ "Make a checklist for this task, but not a reusable skill.",
+ "Create a reusable-looking checklist, but keep it as a plain note instead of a skill.",
+ "Review this process note and explain it, no packaging needed.",
+ "Turn this into a checklist and template, but stop short of making a full skill."
+ ]
+ },
+ "workflow": {
+ "steps": [
+ "Decide whether the request should become a skill and choose the lightest fit.",
+ "Capture job, output, exclusions, constraints, and standards.",
+ "Run reference scan: external benchmarks first, user references second, local fit third; surface only uncertainty or conflict.",
+ "Write the `description` early and test route quality before expanding the package.",
+ "Add output-risk, artifact-design, prompt-quality, and system-model reports only when they matter.",
+ "Add only folders and gates that earn their keep.",
+ "Surface the top three next iteration directions."
+ ],
+ "decision_points": [
+ "Route by frontmatter `description`.",
+ "Keep `SKILL.md` lean; put guidance in `references/`, logic in `scripts/`, and evidence in `reports/`.",
+ "Use the lightest reliable process.",
+ "`Scaffold`: exploratory or personal.",
+ "`Production`: team reuse.",
+ "`Library`: shared infrastructure.",
+ "Ask one focused clarification when the real job, output, or exclusion boundary is unclear.",
+ "Escalate visible tradeoffs when benchmark patterns conflict with local privacy, naming, or governance constraints.",
+ "Do not silently broaden the skill into adjacent jobs just because the examples are nearby."
+ ],
+ "failure_modes": [
+ "Tables can render as dense grids with weak hierarchy or poor mobile readability.",
+ "Long bullets can make the output look complete while hiding the actual decision logic.",
+ "Footnote markers or dense citation notes can interrupt the reading flow.",
+ "Evidence can be over-attached to obvious statements and under-attached to risky claims.",
+ "Screenshots can be captured from the wrong state, wrong viewport, or wrong crop.",
+ "Missing screenshots can cause the skill to invent visual references instead of declaring the gap.",
+ "Users start invoking the skill for adjacent one-off or explanation-only requests.",
+ "Outputs remain valid but become generic, cluttered, or weakly aligned with the user's domain.",
+ "Borrowed benchmark patterns no longer fit the local job or add ceremony without payoff.",
+ "Skill usage becomes team-critical while ownership, review cadence, or rollback evidence stays informal."
+ ]
+ },
+ "resources": {
+ "references": [
+ "references/artifact-design-doctrine.md",
+ "references/authoring-discipline.md",
+ "references/distribution-registry-method.md",
+ "references/eval-playbook.md",
+ "references/gate-selection.md",
+ "references/governance.md",
+ "references/human-review-template.md",
+ "references/intent-dialogue.md",
+ "references/iteration-philosophy.md",
+ "references/non-skill-decision-tree.md",
+ "references/operating-modes.md",
+ "references/output-eval-method.md",
+ "references/output-quality-risk.md",
+ "references/output-visual-quality.md",
+ "references/packaging-contracts.md",
+ "references/pattern-extraction-doctrine.md",
+ "references/platform-capability-matrix.md",
+ "references/prompt-engineering-doctrine.md",
+ "references/qa-ladder.md",
+ "references/reference-scan.md",
+ "references/regression-cause-taxonomy.md",
+ "references/resource-boundaries.md",
+ "references/review-studio-method.md",
+ "references/review-waiver-method.md",
+ "references/runtime-conformance-method.md",
+ "references/skill-archetypes.md",
+ "references/skill-atlas-method.md",
+ "references/skill-engineering-method.md",
+ "references/skill-ir-method.md",
+ "references/systems-thinking-doctrine.md",
+ "references/telemetry-drift-method.md",
+ "references/trust-security-method.md"
+ ],
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/context_sizer.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/diff_eval.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/governance_check.py",
+ "scripts/init_skill.py",
+ "scripts/judge_blind_eval.py",
+ "scripts/lint_skill.py",
+ "scripts/local_output_eval_runner.py",
+ "scripts/optimize_description.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/resource_boundary_check.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/skill_report_charts.py",
+ "scripts/skill_report_metrics.py",
+ "scripts/skill_report_model.py",
+ "scripts/sync_local_install.py",
+ "scripts/trigger_eval.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/validate_skill.py",
+ "scripts/verify_package.py",
+ "scripts/yao.py"
+ ],
+ "assets": [
+ "templates/basic_skill.md.j2",
+ "templates/complex_skill.md.j2"
+ ],
+ "reports": [
+ "reports/benchmark_methodology.md",
+ "reports/intent-context.json",
+ "reports/intent-confidence.json",
+ "reports/intent-confidence.md",
+ "reports/reference-synthesis.json",
+ "reports/reference-synthesis.md",
+ "reports/output-risk-profile.json",
+ "reports/output-risk-profile.md",
+ "reports/artifact-design-profile.json",
+ "reports/artifact-design-profile.md",
+ "reports/prompt-quality-profile.json",
+ "reports/prompt-quality-profile.md",
+ "reports/system-model.json",
+ "reports/system-model.md",
+ "reports/iteration-directions.json",
+ "reports/iteration-directions.md",
+ "reports/skill-overview.json",
+ "reports/skill-overview.html",
+ "reports/output_quality_scorecard.json",
+ "reports/output_quality_scorecard.md",
+ "reports/output_execution_runs.json",
+ "reports/output_execution_runs.md",
+ "reports/output_blind_review_pack.json",
+ "reports/output_blind_review_pack.md",
+ "reports/output_blind_answer_key.json",
+ "reports/output_review_adjudication.json",
+ "reports/output_review_adjudication.md",
+ "reports/review_annotations.json",
+ "reports/review_annotations.md",
+ "reports/conformance_matrix.json",
+ "reports/conformance_matrix.md",
+ "reports/security_trust_report.json",
+ "reports/security_trust_report.md",
+ "reports/runtime_permission_probes.json",
+ "reports/runtime_permission_probes.md",
+ "reports/skill_atlas.json",
+ "reports/skill_atlas.html",
+ "reports/skill-os-2-review.md",
+ "reports/portability_score.json",
+ "reports/portability_score.md",
+ "reports/governance_score.json"
+ ],
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ }
+ },
+ "eval_plan": {
+ "trigger": [
+ "evals/README.md",
+ "evals/adversarial/trigger_cases.json",
+ "evals/blind_holdout/trigger_cases.json",
+ "evals/confusion/route_cases.json",
+ "evals/dev/trigger_cases.json",
+ "evals/failure-cases.md",
+ "evals/history/2026-03-31-context-first-pack.json",
+ "evals/history/2026-03-31-family-suite-expansion.json",
+ "evals/history/2026-03-31-governance-quality-gates.json",
+ "evals/history/2026-03-31-governed-assets-and-history.json",
+ "evals/history/2026-04-01-route-scorecard-foundation.json",
+ "evals/history/README.md",
+ "evals/history/description_optimization/2026-03-31-description-optimization-suite.json",
+ "evals/history/description_optimization/2026-04-01-adversarial-calibration-and-family-drift.json",
+ "evals/history/description_optimization/2026-04-01-blind-holdout-and-drift-history.json",
+ "evals/history/description_optimization/2026-04-01-judge-backed-blind-eval.json",
+ "evals/history/description_optimization/README.md",
+ "evals/holdout/trigger_cases.json",
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json",
+ "evals/packaging_expectations.json",
+ "evals/promotion_policy.md",
+ "evals/semantic_config.json",
+ "evals/train/trigger_cases.json",
+ "evals/trigger_cases.json"
+ ],
+ "output": [
+ "evals/output/cases.jsonl",
+ "evals/output/fixtures/release-brief-source.md",
+ "evals/output/schema.json"
+ ],
+ "adversarial": [
+ "evals/adversarial/trigger_cases.json"
+ ],
+ "baseline": "without_skill",
+ "counts": {
+ "trigger": 26,
+ "output": 3,
+ "adversarial": 1,
+ "baseline": 1
+ }
+ },
+ "risk": {
+ "output_risk": "high",
+ "execution_risk": "medium",
+ "trust_boundary": "external"
+ },
+ "governance": {
+ "owner": "Yao Team",
+ "maturity": "governed",
+ "review_cadence": "quarterly",
+ "review_due": ""
+ },
+ "runtime": {
+ "activation": {
+ "mode": "manual",
+ "paths": []
+ },
+ "execution": {
+ "context": "inline",
+ "shell": "bash"
+ },
+ "trust": {
+ "source_tier": "local",
+ "remote_inline_execution": "forbid",
+ "remote_metadata_policy": "allow-metadata-only"
+ },
+ "adapter_targets": [
+ "openai",
+ "claude",
+ "generic"
+ ],
+ "canonical_format": "agent-skills"
+ },
+ "permissions": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "source_files_count": 6,
+ "target": "agent-skills-compatible",
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "agent-skills-compatible",
+ "permission_model": "metadata-only",
+ "native_enforcement": false,
+ "representation": "adapter metadata",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "Permission semantics are preserved as metadata for reviewer visibility."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "agent-skills-compatible",
+ "native_surface": "Agent Skills standard source tree",
+ "activation": {
+ "policy": "Use SKILL.md frontmatter name and description for progressive disclosure.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Keep optional directories as relative resources next to SKILL.md.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "SKILL.md",
+ "agents/interface.yaml"
+ ]
+ },
+ "scripts": {
+ "strategy": "Scripts remain local optional resources and should advertise --help when executable.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "consumer-enforced-or-metadata-only",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "SKILL.md",
+ "agents/interface.yaml",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "The source tree itself is the target artifact.",
+ "unsupported_native_features": []
+ },
+ "install_scope": "Agent Skills source root"
+ },
+ "degradation_strategy": "neutral-source",
+ "target_runtime": {
+ "adapter_mode": "neutral-agent-skills-source",
+ "generated_files": [
+ "SKILL.md",
+ "agents/interface.yaml"
+ ],
+ "metadata_mapping": {
+ "name": "SKILL.md::frontmatter.name",
+ "description": "SKILL.md::frontmatter.description",
+ "interface": "agents/interface.yaml",
+ "manifest": "manifest.json"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "native_surface": "Agent Skills standard source tree"
+ }
+ },
+ "permission_contract": {
+ "schema_version": "1.0",
+ "source": "reports/security_trust_report.json",
+ "source_available": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true,
+ "capabilities": {
+ "network": {
+ "required": true,
+ "script_count": 2,
+ "scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "review_reason": "Outbound hosts must match security/network_policy.json."
+ },
+ "file_write": {
+ "required": true,
+ "script_count": 47,
+ "scripts": [
+ "scripts/adjudicate_output_review.py",
+ "scripts/build_confusion_matrix.py",
+ "scripts/build_skill_atlas.py",
+ "scripts/check_update.py",
+ "scripts/ci_test.py",
+ "scripts/collect_feedback.py",
+ "scripts/compile_skill.py",
+ "scripts/create_iteration_snapshot.py",
+ "scripts/cross_packager.py",
+ "scripts/export_skill_ir.py",
+ "scripts/github_benchmark_scan.py",
+ "scripts/init_skill.py",
+ "scripts/probe_runtime_permissions.py",
+ "scripts/promotion_checker.py",
+ "scripts/registry_audit.py",
+ "scripts/render_adoption_drift_report.py",
+ "scripts/render_artifact_design_profile.py",
+ "scripts/render_baseline_compare.py",
+ "scripts/render_context_reports.py",
+ "scripts/render_description_drift_history.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/render_intent_confidence.py",
+ "scripts/render_intent_dialogue.py",
+ "scripts/render_iteration_directions.py",
+ "scripts/render_iteration_ledger.py",
+ "scripts/render_output_risk_profile.py",
+ "scripts/render_portability_report.py",
+ "scripts/render_prompt_quality_profile.py",
+ "scripts/render_reference_scan.py",
+ "scripts/render_reference_synthesis.py",
+ "scripts/render_regression_history.py",
+ "scripts/render_review_annotations.py",
+ "scripts/render_review_studio.py",
+ "scripts/render_review_viewer.py",
+ "scripts/render_review_waivers.py",
+ "scripts/render_skill_overview.py",
+ "scripts/render_social_preview.py",
+ "scripts/render_system_model.py",
+ "scripts/run_conformance_suite.py",
+ "scripts/run_description_optimization_suite.py",
+ "scripts/run_output_eval.py",
+ "scripts/run_output_execution.py",
+ "scripts/simulate_install.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/upgrade_check.py",
+ "scripts/verify_package.py"
+ ],
+ "review_reason": "Scripts write local files or generated artifacts."
+ },
+ "subprocess": {
+ "required": true,
+ "script_count": 7,
+ "scripts": [
+ "scripts/ci_test.py",
+ "scripts/render_eval_dashboard.py",
+ "scripts/run_eval_suite.py",
+ "scripts/run_output_execution.py",
+ "scripts/sync_local_install.py",
+ "scripts/trust_check.py",
+ "scripts/yao.py"
+ ],
+ "review_reason": "Scripts spawn local commands and need operator review."
+ },
+ "interactive": {
+ "required": false,
+ "script_count": 0,
+ "scripts": [],
+ "review_reason": ""
+ }
+ },
+ "network_policy": {
+ "source": "security/network_policy.json",
+ "covered_scripts": [
+ "scripts/check_update.py",
+ "scripts/github_benchmark_scan.py"
+ ],
+ "missing_scripts": [],
+ "mismatches": []
+ },
+ "help_smoke": {
+ "enabled": true,
+ "checked_count": 59,
+ "failed_count": 0,
+ "failed_scripts": []
+ },
+ "trust_summary": {
+ "secret_findings": 0,
+ "network_script_count": 2,
+ "file_write_script_count": 47,
+ "subprocess_script_count": 7,
+ "interactive_script_count": 0,
+ "help_smoke_failed_count": 0
+ }
+ },
+ "target_permission_contract": {
+ "schema_version": "1.0",
+ "target": "agent-skills-compatible",
+ "permission_model": "metadata-only",
+ "native_enforcement": false,
+ "representation": "adapter metadata",
+ "review_required": true,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "capability_counts": {
+ "network": 2,
+ "file_write": 47,
+ "subprocess": 7,
+ "interactive": 0
+ },
+ "evidence": "reports/security_trust_report.json",
+ "operator_note": "Permission semantics are preserved as metadata for reviewer visibility."
+ },
+ "target_native_contract": {
+ "schema_version": "1.0",
+ "target": "agent-skills-compatible",
+ "native_surface": "Agent Skills standard source tree",
+ "activation": {
+ "policy": "Use SKILL.md frontmatter name and description for progressive disclosure.",
+ "trigger_description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "manual_activation_supported": true,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation."
+ },
+ "resources": {
+ "strategy": "Keep optional directories as relative resources next to SKILL.md.",
+ "counts": {
+ "references": 32,
+ "scripts": 62,
+ "assets": 2,
+ "reports": 41
+ },
+ "generated_files": [
+ "SKILL.md",
+ "agents/interface.yaml"
+ ]
+ },
+ "scripts": {
+ "strategy": "Scripts remain local optional resources and should advertise --help when executable.",
+ "script_count": 62,
+ "help_smoke_failed_count": 0
+ },
+ "permissions": {
+ "enforcement": "consumer-enforced-or-metadata-only",
+ "native_enforcement": false,
+ "declared_capabilities": [
+ "network",
+ "file_write",
+ "subprocess"
+ ],
+ "review_required": true
+ },
+ "review": {
+ "artifacts": [
+ "SKILL.md",
+ "agents/interface.yaml",
+ "reports/review-studio.html"
+ ],
+ "fallback_behavior": "The source tree itself is the target artifact.",
+ "unsupported_native_features": []
+ },
+ "install_scope": "Agent Skills source root"
+ },
+ "target_transform": {
+ "target": "agent-skills-compatible",
+ "adapter_mode": "neutral-agent-skills-source",
+ "generated_files": [
+ "SKILL.md",
+ "agents/interface.yaml"
+ ],
+ "metadata_mapping": {
+ "name": "SKILL.md::frontmatter.name",
+ "description": "SKILL.md::frontmatter.description",
+ "interface": "agents/interface.yaml",
+ "manifest": "manifest.json"
+ },
+ "preserved_semantics": [
+ "trigger",
+ "workflow",
+ "resources",
+ "eval-plan",
+ "risk",
+ "governance",
+ "runtime",
+ "trust",
+ "permissions"
+ ],
+ "degradation_strategy": "neutral-source",
+ "permission_representation": "adapter metadata",
+ "native_surface": "Agent Skills standard source tree",
+ "activation_policy": "Use SKILL.md frontmatter name and description for progressive disclosure.",
+ "resource_strategy": "Keep optional directories as relative resources next to SKILL.md.",
+ "script_strategy": "Scripts remain local optional resources and should advertise --help when executable.",
+ "permission_enforcement": "consumer-enforced-or-metadata-only"
+ },
+ "unsupported_features": [],
+ "warnings": [],
+ "failures": []
+ }
+ ],
+ "failures": [],
+ "warnings": [],
+ "artifacts": {
+ "json": "reports/compiled_targets.json",
+ "markdown": "reports/compiled_targets.md"
+ }
+}
diff --git a/reports/compiled_targets.md b/reports/compiled_targets.md
new file mode 100644
index 0000000..ea2ddcb
--- /dev/null
+++ b/reports/compiled_targets.md
@@ -0,0 +1,63 @@
+# Compiled Targets
+
+- OK: `True`
+- Targets: `4`
+- Pass: `4`
+- Warn: `0`
+- Block: `0`
+
+## Target Transforms
+
+| Target | Status | Native Surface | Adapter Mode | Permissions | Degradation | Generated Files |
+| --- | --- | --- | --- | --- | --- | --- |
+| `openai` | `pass` | OpenAI-style interface metadata plus neutral Agent Skills source | `metadata-adapter` | `network, file_write, subprocess` | `metadata-adapter` | targets/openai/adapter.json, targets/openai/agents/openai.yaml |
+| `claude` | `pass` | Claude-compatible neutral source folder with adapter notes | `neutral-source-plus-adapter` | `network, file_write, subprocess` | `neutral-source-plus-adapter` | targets/claude/adapter.json, targets/claude/README.md |
+| `generic` | `pass` | Agent Skills compatible neutral package | `agent-skills-compatible` | `network, file_write, subprocess` | `neutral-source` | targets/generic/adapter.json |
+| `agent-skills-compatible` | `pass` | Agent Skills standard source tree | `neutral-agent-skills-source` | `network, file_write, subprocess` | `neutral-source` | SKILL.md, agents/interface.yaml |
+
+## Native Behavior Contracts
+
+### openai
+
+- Native surface: OpenAI-style interface metadata plus neutral Agent Skills source
+- Activation: Use frontmatter description for catalog routing and targets/openai/agents/openai.yaml for display name, default prompt, and compatibility metadata.
+- Resources: Ship the neutral source tree and expose OpenAI-facing interface metadata as a generated companion file.
+- Scripts: Keep scripts as local package resources; expose help-smoke and permission metadata for reviewer approval before execution.
+- Permission enforcement: `metadata-only`; native enforcement `False`
+- Review artifacts: targets/openai/agents/openai.yaml, targets/openai/adapter.json, reports/review-studio.html
+
+### claude
+
+- Native surface: Claude-compatible neutral source folder with adapter notes
+- Activation: Use SKILL.md frontmatter description as the primary activation contract and adapter.json for review metadata.
+- Resources: Preserve the source tree directly; write target notes in targets/claude/README.md.
+- Scripts: Scripts remain local package resources and must be reviewed through trust and permission reports before use.
+- Permission enforcement: `metadata-fallback`; native enforcement `False`
+- Review artifacts: targets/claude/README.md, targets/claude/adapter.json, reports/review-studio.html
+
+### generic
+
+- Native surface: Agent Skills compatible neutral package
+- Activation: Use SKILL.md name and description; consumers decide automatic or manual activation.
+- Resources: Preserve references, scripts, assets, evals, reports, and adapter metadata as relative package resources.
+- Scripts: Expose script and permission metadata for downstream clients or installers to enforce.
+- Permission enforcement: `consumer-enforced-or-metadata-only`; native enforcement `False`
+- Review artifacts: targets/generic/adapter.json, reports/review-studio.html
+
+### agent-skills-compatible
+
+- Native surface: Agent Skills standard source tree
+- Activation: Use SKILL.md frontmatter name and description for progressive disclosure.
+- Resources: Keep optional directories as relative resources next to SKILL.md.
+- Scripts: Scripts remain local optional resources and should advertise --help when executable.
+- Permission enforcement: `consumer-enforced-or-metadata-only`; native enforcement `False`
+- Review artifacts: SKILL.md, agents/interface.yaml, reports/review-studio.html
+
+
+## Failures
+
+- None
+
+## Warnings
+
+- None
diff --git a/reports/conformance_matrix.json b/reports/conformance_matrix.json
index b51addc..20e9bce 100644
--- a/reports/conformance_matrix.json
+++ b/reports/conformance_matrix.json
@@ -32,6 +32,7 @@
"Skill IR description matches frontmatter",
"references resource resolves: references/artifact-design-doctrine.md",
"references resource resolves: references/authoring-discipline.md",
+ "references resource resolves: references/distribution-registry-method.md",
"references resource resolves: references/eval-playbook.md",
"references resource resolves: references/gate-selection.md",
"references resource resolves: references/governance.md",
@@ -40,8 +41,7 @@
"references resource resolves: references/iteration-philosophy.md",
"references resource resolves: references/non-skill-decision-tree.md",
"references resource resolves: references/operating-modes.md",
- "references resource resolves: references/output-eval-method.md",
- "references resource resolves: references/output-quality-risk.md"
+ "references resource resolves: references/output-eval-method.md"
],
"failures": [],
"warnings": []
@@ -76,6 +76,7 @@
"Skill IR description matches frontmatter",
"references resource resolves: references/artifact-design-doctrine.md",
"references resource resolves: references/authoring-discipline.md",
+ "references resource resolves: references/distribution-registry-method.md",
"references resource resolves: references/eval-playbook.md",
"references resource resolves: references/gate-selection.md",
"references resource resolves: references/governance.md",
@@ -84,8 +85,7 @@
"references resource resolves: references/iteration-philosophy.md",
"references resource resolves: references/non-skill-decision-tree.md",
"references resource resolves: references/operating-modes.md",
- "references resource resolves: references/output-eval-method.md",
- "references resource resolves: references/output-quality-risk.md"
+ "references resource resolves: references/output-eval-method.md"
],
"failures": [],
"warnings": []
@@ -120,6 +120,7 @@
"Skill IR description matches frontmatter",
"references resource resolves: references/artifact-design-doctrine.md",
"references resource resolves: references/authoring-discipline.md",
+ "references resource resolves: references/distribution-registry-method.md",
"references resource resolves: references/eval-playbook.md",
"references resource resolves: references/gate-selection.md",
"references resource resolves: references/governance.md",
@@ -128,12 +129,11 @@
"references resource resolves: references/iteration-philosophy.md",
"references resource resolves: references/non-skill-decision-tree.md",
"references resource resolves: references/operating-modes.md",
- "references resource resolves: references/output-eval-method.md",
- "references resource resolves: references/output-quality-risk.md"
+ "references resource resolves: references/output-eval-method.md"
],
"failures": [],
"warnings": [
- "agent-skills uses canonical Agent Skills metadata; runtime-specific behavior transforms are not implemented in v0."
+ "agent-skills uses canonical Agent Skills metadata; provider-native execution transforms are not implemented in v0."
]
},
{
@@ -166,6 +166,7 @@
"Skill IR description matches frontmatter",
"references resource resolves: references/artifact-design-doctrine.md",
"references resource resolves: references/authoring-discipline.md",
+ "references resource resolves: references/distribution-registry-method.md",
"references resource resolves: references/eval-playbook.md",
"references resource resolves: references/gate-selection.md",
"references resource resolves: references/governance.md",
@@ -174,12 +175,11 @@
"references resource resolves: references/iteration-philosophy.md",
"references resource resolves: references/non-skill-decision-tree.md",
"references resource resolves: references/operating-modes.md",
- "references resource resolves: references/output-eval-method.md",
- "references resource resolves: references/output-quality-risk.md"
+ "references resource resolves: references/output-eval-method.md"
],
"failures": [],
"warnings": [
- "vscode uses canonical Agent Skills metadata; runtime-specific behavior transforms are not implemented in v0."
+ "vscode uses canonical Agent Skills metadata; provider-native execution transforms are not implemented in v0."
]
},
{
@@ -212,6 +212,7 @@
"Skill IR description matches frontmatter",
"references resource resolves: references/artifact-design-doctrine.md",
"references resource resolves: references/authoring-discipline.md",
+ "references resource resolves: references/distribution-registry-method.md",
"references resource resolves: references/eval-playbook.md",
"references resource resolves: references/gate-selection.md",
"references resource resolves: references/governance.md",
@@ -220,8 +221,7 @@
"references resource resolves: references/iteration-philosophy.md",
"references resource resolves: references/non-skill-decision-tree.md",
"references resource resolves: references/operating-modes.md",
- "references resource resolves: references/output-eval-method.md",
- "references resource resolves: references/output-quality-risk.md"
+ "references resource resolves: references/output-eval-method.md"
],
"failures": [],
"warnings": []
diff --git a/reports/conformance_matrix.md b/reports/conformance_matrix.md
index d62a084..243e9bd 100644
--- a/reports/conformance_matrix.md
+++ b/reports/conformance_matrix.md
@@ -9,8 +9,8 @@
| --- | --- | --- | --- |
| openai | pass | None | None |
| claude | pass | None | None |
-| agent-skills | pass | None | agent-skills uses canonical Agent Skills metadata; runtime-specific behavior transforms are not implemented in v0. |
-| vscode | pass | None | vscode uses canonical Agent Skills metadata; runtime-specific behavior transforms are not implemented in v0. |
+| agent-skills | pass | None | agent-skills uses canonical Agent Skills metadata; provider-native execution transforms are not implemented in v0. |
+| vscode | pass | None | vscode uses canonical Agent Skills metadata; provider-native execution transforms are not implemented in v0. |
| generic | pass | None | None |
## Reviewer Notes
diff --git a/reports/context_budget.json b/reports/context_budget.json
index 876de6e..4da126e 100644
--- a/reports/context_budget.json
+++ b/reports/context_budget.json
@@ -5,13 +5,13 @@
"stats": {
"context_budget_tier": "production",
"context_budget_limit": 1000,
- "skill_body_tokens": 734,
- "other_text_tokens": 606468,
- "estimated_initial_load_tokens": 910,
- "estimated_total_text_tokens": 607202,
- "relevant_file_count": 241,
+ "skill_body_tokens": 811,
+ "other_text_tokens": 864534,
+ "estimated_initial_load_tokens": 987,
+ "estimated_total_text_tokens": 865345,
+ "relevant_file_count": 316,
"unused_resource_dirs": [],
"quality_signal_points": 130,
- "quality_density": 142.9
+ "quality_density": 131.7
}
}
diff --git a/reports/context_budget.md b/reports/context_budget.md
index 1da7709..9d678e5 100644
--- a/reports/context_budget.md
+++ b/reports/context_budget.md
@@ -2,7 +2,7 @@
| Target | Path | Tier | Limit | Initial | SKILL | Quality Density | Unused Dirs | Status |
| --- | --- | --- | ---: | ---: | ---: | ---: | --- | --- |
-| root | `.` | `production` | 1000 | 910 | 734 | 142.9 | - | ok |
+| root | `.` | `production` | 1000 | 987 | 811 | 131.7 | - | ok |
| complex-release-orchestrator | `examples/complex-release-orchestrator/generated-skill` | `production` | 1000 | 790 | 718 | 164.6 | - | ok |
| governed-incident-command | `examples/governed-incident-command/generated-skill` | `production` | 1000 | 760 | 658 | 171.1 | - | ok |
diff --git a/reports/context_budget_summary.json b/reports/context_budget_summary.json
index efda026..ac17bd2 100644
--- a/reports/context_budget_summary.json
+++ b/reports/context_budget_summary.json
@@ -6,9 +6,9 @@
"path": ".",
"budget_tier": "production",
"budget_limit": 1000,
- "initial_tokens": 910,
- "skill_body_tokens": 734,
- "quality_density": 142.9,
+ "initial_tokens": 987,
+ "skill_body_tokens": 811,
+ "quality_density": 131.7,
"unused_resource_dirs": [],
"ok": true,
"warnings": []
diff --git a/reports/install_simulation.json b/reports/install_simulation.json
new file mode 100644
index 0000000..facee86
--- /dev/null
+++ b/reports/install_simulation.json
@@ -0,0 +1,121 @@
+{
+ "ok": true,
+ "schema_version": "2.0",
+ "generated_at": "2026-06-13",
+ "skill_dir": ".",
+ "package_dir": "dist",
+ "install_root": "dist/install-simulation/simulate-yao-meta-skill",
+ "installed_skill_dir": "dist/install-simulation/simulate-yao-meta-skill/yao-meta-skill",
+ "summary": {
+ "archive_present": true,
+ "archive_entry_count": 483,
+ "archive_extracted": true,
+ "entrypoint_loaded": true,
+ "manifest_loaded": true,
+ "interface_loaded": true,
+ "adapter_count": 3,
+ "install_root_is_temp": false,
+ "failure_count": 0,
+ "warning_count": 0
+ },
+ "checks": [
+ {
+ "id": "archive-present",
+ "status": "pass",
+ "detail": "Package archive exists: dist/yao-meta-skill.zip"
+ },
+ {
+ "id": "archive-safe-paths",
+ "status": "pass",
+ "detail": "Archive has no absolute or parent-traversal entries"
+ },
+ {
+ "id": "single-top-level",
+ "status": "pass",
+ "detail": "Archive top-level directory is yao-meta-skill"
+ },
+ {
+ "id": "entrypoint-load",
+ "status": "pass",
+ "detail": "Installed SKILL.md frontmatter is readable"
+ },
+ {
+ "id": "entrypoint-name",
+ "status": "pass",
+ "detail": "Installed SKILL.md name matches package directory"
+ },
+ {
+ "id": "entrypoint-description",
+ "status": "pass",
+ "detail": "Installed SKILL.md description is present"
+ },
+ {
+ "id": "manifest-load",
+ "status": "pass",
+ "detail": "Installed manifest.json is readable"
+ },
+ {
+ "id": "manifest-name",
+ "status": "pass",
+ "detail": "Installed manifest name matches package manifest"
+ },
+ {
+ "id": "manifest-version",
+ "status": "pass",
+ "detail": "Installed manifest version matches package manifest"
+ },
+ {
+ "id": "interface-load",
+ "status": "pass",
+ "detail": "Installed agents/interface.yaml is readable"
+ },
+ {
+ "id": "overview-report",
+ "status": "pass",
+ "detail": "Installed overview report is present"
+ },
+ {
+ "id": "review-studio-report",
+ "status": "pass",
+ "detail": "Installed Review Studio report is present"
+ },
+ {
+ "id": "adapter-claude",
+ "status": "pass",
+ "detail": "claude adapter is readable after package install simulation"
+ },
+ {
+ "id": "adapter-claude-name",
+ "status": "pass",
+ "detail": "claude adapter name matches package manifest"
+ },
+ {
+ "id": "adapter-generic",
+ "status": "pass",
+ "detail": "generic adapter is readable after package install simulation"
+ },
+ {
+ "id": "adapter-generic-name",
+ "status": "pass",
+ "detail": "generic adapter name matches package manifest"
+ },
+ {
+ "id": "adapter-openai",
+ "status": "pass",
+ "detail": "openai adapter is readable after package install simulation"
+ },
+ {
+ "id": "adapter-openai-name",
+ "status": "pass",
+ "detail": "openai adapter name matches package manifest"
+ }
+ ],
+ "failures": [],
+ "warnings": [],
+ "artifacts": {
+ "archive": "dist/yao-meta-skill.zip",
+ "package_manifest": "dist/manifest.json",
+ "json": "reports/install_simulation.json",
+ "markdown": "reports/install_simulation.md"
+ }
+}
diff --git a/reports/install_simulation.md b/reports/install_simulation.md
new file mode 100644
index 0000000..7a06607
--- /dev/null
+++ b/reports/install_simulation.md
@@ -0,0 +1,42 @@
+# Install Simulation
+
+- OK: `True`
+- Package directory: `dist`
+- Archive extracted: `True`
+- Entrypoint loaded: `True`
+- Manifest loaded: `True`
+- Interface loaded: `True`
+- Adapters readable: `3`
+- Failures: `0`
+- Warnings: `0`
+
+## Checks
+
+| Check | Status | Detail |
+| --- | --- | --- |
+| `archive-present` | `pass` | Package archive exists: dist/yao-meta-skill.zip |
+| `archive-safe-paths` | `pass` | Archive has no absolute or parent-traversal entries |
+| `single-top-level` | `pass` | Archive top-level directory is yao-meta-skill |
+| `entrypoint-load` | `pass` | Installed SKILL.md frontmatter is readable |
+| `entrypoint-name` | `pass` | Installed SKILL.md name matches package directory |
+| `entrypoint-description` | `pass` | Installed SKILL.md description is present |
+| `manifest-load` | `pass` | Installed manifest.json is readable |
+| `manifest-name` | `pass` | Installed manifest name matches package manifest |
+| `manifest-version` | `pass` | Installed manifest version matches package manifest |
+| `interface-load` | `pass` | Installed agents/interface.yaml is readable |
+| `overview-report` | `pass` | Installed overview report is present |
+| `review-studio-report` | `pass` | Installed Review Studio report is present |
+| `adapter-claude` | `pass` | claude adapter is readable after package install simulation |
+| `adapter-claude-name` | `pass` | claude adapter name matches package manifest |
+| `adapter-generic` | `pass` | generic adapter is readable after package install simulation |
+| `adapter-generic-name` | `pass` | generic adapter name matches package manifest |
+| `adapter-openai` | `pass` | openai adapter is readable after package install simulation |
+| `adapter-openai-name` | `pass` | openai adapter name matches package manifest |
+
+## Failures
+
+- None
+
+## Warnings
+
+- None
diff --git a/reports/intent-confidence.json b/reports/intent-confidence.json
index a6d252b..7401f59 100644
--- a/reports/intent-confidence.json
+++ b/reports/intent-confidence.json
@@ -1,79 +1,53 @@
{
- "score": 30,
- "band": "low",
- "gate_passed": false,
+ "score": 100,
+ "band": "high",
+ "gate_passed": true,
"strengths": [
- "The recurring job is concrete enough to anchor the package."
+ "The recurring job is concrete enough to anchor the package.",
+ "Real input shape is explicit.",
+ "The hand-back output is concrete.",
+ "Boundary exclusions are already explicit.",
+ "Operational constraints are visible."
],
- "gaps": [
- {
- "key": "real_inputs",
- "label": "Real inputs are missing",
- "reason": "Without real inputs, it is hard to choose assets, scripts, or examples.",
- "severity": "high"
- },
- {
- "key": "primary_output",
- "label": "Primary output is missing",
- "reason": "The package does not yet know what it must hand back.",
- "severity": "high"
- },
- {
- "key": "exclusions",
- "label": "Near-neighbor exclusions are missing",
- "reason": "The route may blur into nearby requests without an exclusion list.",
- "severity": "high"
- },
- {
- "key": "constraints",
- "label": "Constraints are missing",
- "reason": "The package does not yet know which tradeoffs matter most.",
- "severity": "high"
- },
- {
- "key": "standards",
- "label": "Quality bar is implied, not explicit",
- "reason": "The first evaluation target is still underspecified.",
- "severity": "medium"
- }
- ],
- "follow_up_questions": [
- {
- "slot": "real_inputs",
- "question": "What material will people actually hand to this skill in practice?",
- "why": "Real input shape decides whether references, scripts, or examples are needed.",
- "list": true,
- "label": "Real inputs are missing",
- "severity": "high"
- },
- {
- "slot": "primary_output",
- "question": "What finished hand-back should this skill return so the next person can keep moving?",
- "why": "The output is the anchor for package design and review.",
- "list": false,
- "label": "Primary output is missing",
- "severity": "high"
- },
- {
- "slot": "exclusions",
- "question": "What nearby requests should this skill clearly leave out so the boundary stays clean?",
- "why": "Exclusions are the fastest route to better trigger quality.",
- "list": true,
- "label": "Near-neighbor exclusions are missing",
- "severity": "high"
- }
- ],
- "anchor_sentence": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
- "recommended_action": "Pause before deep authoring and close the highest-leverage gaps first.",
+ "gaps": [],
+ "follow_up_questions": [],
+ "anchor_sentence": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse. Primary output: A working skill package with lean SKILL.md, aligned agents/interface.yaml, justified references, scripts only when useful, eval evidence, reports, packaging metadata, and clear next iteration recommendations.. Exclusions: one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill, general code review or debugging unless the user is packaging that workflow as a skill, raw private material that was not intentionally supplied as skill evidence, platform-specific plugin creation when the request is not about an agent skill package.",
+ "recommended_action": "Intent is clear enough to package the first routeable version.",
"context": {
- "job": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
- "real_inputs": [],
- "primary_output": "",
+ "job": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.",
+ "real_inputs": [
+ "rough workflow notes, SOPs, runbooks, prompts, transcripts, documents, or repeated task descriptions",
+ "an existing skill directory that needs refactor, evaluation, packaging, or governance hardening",
+ "target platform requirements such as OpenAI, Claude, generic Agent Skills, or team distribution",
+ "benchmark references, local constraints, desired maturity tier, and review standards"
+ ],
+ "primary_output": "A working skill package with lean SKILL.md, aligned agents/interface.yaml, justified references, scripts only when useful, eval evidence, reports, packaging metadata, and clear next iteration recommendations.",
"description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
- "exclusions": [],
- "constraints": [],
- "standards": [],
- "correction": "",
- "user_references": []
+ "exclusions": [
+ "one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill",
+ "general code review or debugging unless the user is packaging that workflow as a skill",
+ "raw private material that was not intentionally supplied as skill evidence",
+ "platform-specific plugin creation when the request is not about an agent skill package"
+ ],
+ "constraints": [
+ "keep SKILL.md lean and route primarily through frontmatter description",
+ "put durable guidance in references, executable logic in scripts, and evidence in reports",
+ "default to the lightest reliable mode before adding governance weight",
+ "preserve portability across OpenAI, Claude, generic, and Agent Skills compatible targets",
+ "avoid raw prompt, output, transcript, or private content in telemetry"
+ ],
+ "standards": [
+ "trigger boundaries must be tested with should-trigger and should-not-trigger cases",
+ "production and higher maturity work needs output eval, trust, runtime conformance, and Review Studio evidence",
+ "governed work needs owner, review cadence, permission approvals, registry metadata, package verification, and install simulation",
+ "generated reports should be bilingual or reviewer-friendly when they are user-facing",
+ "each new asset must earn its place by reducing ambiguity, risk, or repeated work"
+ ],
+ "correction": "The 2.0 direction reframes this package from a Meta Skill factory into a Skill OS with Skill IR, compiler contracts, output eval, runtime conformance, trust, registry, Review Studio, Skill Atlas, and telemetry loops.",
+ "user_references": [
+ "Yao Meta Skill 2.0 upgrade plan",
+ "Kami-style white report layout requirements for generated skill reports",
+ "local Waza engineering habits for review, design, diagnosis, and implementation discipline"
+ ]
}
}
diff --git a/reports/intent-confidence.md b/reports/intent-confidence.md
index 07c3a24..bab3942 100644
--- a/reports/intent-confidence.md
+++ b/reports/intent-confidence.md
@@ -1,31 +1,26 @@
# Intent Confidence
-- Confidence score: `30/100`
-- Confidence band: `low`
-- Gate passed: `False`
-- Recommended action: Pause before deep authoring and close the highest-leverage gaps first.
+- Confidence score: `100/100`
+- Confidence band: `high`
+- Gate passed: `True`
+- Recommended action: Intent is clear enough to package the first routeable version.
## Current Reading
-Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
+Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse. Primary output: A working skill package with lean SKILL.md, aligned agents/interface.yaml, justified references, scripts only when useful, eval evidence, reports, packaging metadata, and clear next iteration recommendations.. Exclusions: one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill, general code review or debugging unless the user is packaging that workflow as a skill, raw private material that was not intentionally supplied as skill evidence, platform-specific plugin creation when the request is not about an agent skill package.
## Strong Signals
- The recurring job is concrete enough to anchor the package.
+- Real input shape is explicit.
+- The hand-back output is concrete.
+- Boundary exclusions are already explicit.
+- Operational constraints are visible.
## Gaps To Close
-- **Real inputs are missing** (`high`): Without real inputs, it is hard to choose assets, scripts, or examples.
-- **Primary output is missing** (`high`): The package does not yet know what it must hand back.
-- **Near-neighbor exclusions are missing** (`high`): The route may blur into nearby requests without an exclusion list.
-- **Constraints are missing** (`high`): The package does not yet know which tradeoffs matter most.
-- **Quality bar is implied, not explicit** (`medium`): The first evaluation target is still underspecified.
+- No major intent gaps detected.
## Follow-Up Questions
-- **What material will people actually hand to this skill in practice?**
- - Why: Real input shape decides whether references, scripts, or examples are needed.
-- **What finished hand-back should this skill return so the next person can keep moving?**
- - Why: The output is the anchor for package design and review.
-- **What nearby requests should this skill clearly leave out so the boundary stays clean?**
- - Why: Exclusions are the fastest route to better trigger quality.
+- No extra follow-up questions required before the first package.
diff --git a/reports/intent-context.json b/reports/intent-context.json
index 8fc3e49..492b5ae 100644
--- a/reports/intent-context.json
+++ b/reports/intent-context.json
@@ -1,11 +1,37 @@
{
- "job": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
- "real_inputs": [],
- "primary_output": "",
+ "job": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.",
+ "real_inputs": [
+ "rough workflow notes, SOPs, runbooks, prompts, transcripts, documents, or repeated task descriptions",
+ "an existing skill directory that needs refactor, evaluation, packaging, or governance hardening",
+ "target platform requirements such as OpenAI, Claude, generic Agent Skills, or team distribution",
+ "benchmark references, local constraints, desired maturity tier, and review standards"
+ ],
+ "primary_output": "A working skill package with lean SKILL.md, aligned agents/interface.yaml, justified references, scripts only when useful, eval evidence, reports, packaging metadata, and clear next iteration recommendations.",
"description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
- "exclusions": [],
- "constraints": [],
- "standards": [],
- "correction": "",
- "user_references": []
+ "exclusions": [
+ "one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill",
+ "general code review or debugging unless the user is packaging that workflow as a skill",
+ "raw private material that was not intentionally supplied as skill evidence",
+ "platform-specific plugin creation when the request is not about an agent skill package"
+ ],
+ "constraints": [
+ "keep SKILL.md lean and route primarily through frontmatter description",
+ "put durable guidance in references, executable logic in scripts, and evidence in reports",
+ "default to the lightest reliable mode before adding governance weight",
+ "preserve portability across OpenAI, Claude, generic, and Agent Skills compatible targets",
+ "avoid raw prompt, output, transcript, or private content in telemetry"
+ ],
+ "standards": [
+ "trigger boundaries must be tested with should-trigger and should-not-trigger cases",
+ "production and higher maturity work needs output eval, trust, runtime conformance, and Review Studio evidence",
+ "governed work needs owner, review cadence, permission approvals, registry metadata, package verification, and install simulation",
+ "generated reports should be bilingual or reviewer-friendly when they are user-facing",
+ "each new asset must earn its place by reducing ambiguity, risk, or repeated work"
+ ],
+ "correction": "The 2.0 direction reframes this package from a Meta Skill factory into a Skill OS with Skill IR, compiler contracts, output eval, runtime conformance, trust, registry, Review Studio, Skill Atlas, and telemetry loops.",
+ "user_references": [
+ "Yao Meta Skill 2.0 upgrade plan",
+ "Kami-style white report layout requirements for generated skill reports",
+ "local Waza engineering habits for review, design, diagnosis, and implementation discipline"
+ ]
}
diff --git a/reports/output_blind_answer_key.json b/reports/output_blind_answer_key.json
new file mode 100644
index 0000000..9de710d
--- /dev/null
+++ b/reports/output_blind_answer_key.json
@@ -0,0 +1,56 @@
+{
+ "schema_version": "1.0",
+ "seed": "yao-output-eval-blind-v1",
+ "summary": {
+ "pair_count": 5,
+ "with_skill_expected_count": 5,
+ "baseline_expected_count": 0
+ },
+ "answers": [
+ {
+ "case_id": "skill-package-contract",
+ "variant_a_role": "with_skill",
+ "variant_b_role": "baseline",
+ "expected_winner_role": "with_skill",
+ "expected_winner_variant": "A",
+ "score_winner_role": "with_skill",
+ "delta": 100.0
+ },
+ {
+ "case_id": "output-eval-expectation",
+ "variant_a_role": "with_skill",
+ "variant_b_role": "baseline",
+ "expected_winner_role": "with_skill",
+ "expected_winner_variant": "A",
+ "score_winner_role": "with_skill",
+ "delta": 100.0
+ },
+ {
+ "case_id": "ir-before-packaging",
+ "variant_a_role": "baseline",
+ "variant_b_role": "with_skill",
+ "expected_winner_role": "with_skill",
+ "expected_winner_variant": "B",
+ "score_winner_role": "with_skill",
+ "delta": 100.0
+ },
+ {
+ "case_id": "near-neighbor-boundary",
+ "variant_a_role": "baseline",
+ "variant_b_role": "with_skill",
+ "expected_winner_role": "with_skill",
+ "expected_winner_variant": "B",
+ "score_winner_role": "with_skill",
+ "delta": 100.0
+ },
+ {
+ "case_id": "file-backed-governed-package",
+ "variant_a_role": "baseline",
+ "variant_b_role": "with_skill",
+ "expected_winner_role": "with_skill",
+ "expected_winner_variant": "B",
+ "score_winner_role": "with_skill",
+ "delta": 100.0
+ }
+ ]
+}
diff --git a/reports/output_blind_review_pack.json b/reports/output_blind_review_pack.json
new file mode 100644
index 0000000..27507ba
--- /dev/null
+++ b/reports/output_blind_review_pack.json
@@ -0,0 +1,204 @@
+{
+ "schema_version": "1.0",
+ "seed": "yao-output-eval-blind-v1",
+ "summary": {
+ "pair_count": 5,
+ "answer_key_separate": true,
+ "with_skill_hidden_count": 5
+ },
+ "pairs": [
+ {
+ "case_id": "skill-package-contract",
+ "prompt": "Turn this repeated workflow into a reusable team skill package.",
+ "input_files": [],
+ "metadata": {},
+ "review_instruction": "Pick A or B based only on the rubric. Do not infer which output came from the skill.",
+ "rubric": [
+ {
+ "id": "has-entrypoint",
+ "description": "Output names the routeable Skill entrypoint.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-interface",
+ "description": "Output includes neutral interface metadata.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-report",
+ "description": "Output points reviewer to generated overview report.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-resource-boundary",
+ "description": "Output preserves entrypoint/resource separation.",
+ "weight": 1.0
+ }
+ ],
+ "variant_a": {
+ "blind_id": "skill-package-contract:A",
+ "output": "Create a routeable SKILL.md, agents/interface.yaml, reports/skill-overview.html, and a focused eval plan. Keep the root entrypoint lean, move durable guidance into references/, scripts into scripts/, and evidence into reports/."
+ },
+ "variant_b": {
+ "blind_id": "skill-package-contract:B",
+ "output": "I can write a prompt for that workflow and include a short checklist."
+ }
+ },
+ {
+ "case_id": "output-eval-expectation",
+ "prompt": "Upgrade this production skill so we know whether the generated output is better than baseline.",
+ "input_files": [],
+ "metadata": {},
+ "review_instruction": "Pick A or B based only on the rubric. Do not infer which output came from the skill.",
+ "rubric": [
+ {
+ "id": "has-baseline-comparison",
+ "description": "Output explicitly compares with-skill and baseline outputs.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-assertion-grading",
+ "description": "Output includes objective assertion grading.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-scorecard",
+ "description": "Output produces a scorecard report path.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-failure-taxonomy",
+ "description": "Output records failure taxonomy.",
+ "weight": 1.0
+ }
+ ],
+ "variant_a": {
+ "blind_id": "output-eval-expectation:A",
+ "output": "Add Output Eval Lab cases with baseline_output and with_skill_output, run assertion grading, report with-skill vs baseline pass-rate delta, and record failure taxonomy plus next fixes in reports/output_quality_scorecard.md."
+ },
+ "variant_b": {
+ "blind_id": "output-eval-expectation:B",
+ "output": "Add more examples and run the trigger eval again."
+ }
+ },
+ {
+ "case_id": "ir-before-packaging",
+ "prompt": "Package this skill for OpenAI, Claude, Agent Skills, and generic targets.",
+ "input_files": [],
+ "metadata": {},
+ "review_instruction": "Pick A or B based only on the rubric. Do not infer which output came from the skill.",
+ "rubric": [
+ {
+ "id": "has-ir-first",
+ "description": "Output requires Skill IR before packaging.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-core-ir-fields",
+ "description": "Output lists core IR contract fields.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-targets",
+ "description": "Output names requested runtime targets.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-semantic-preservation",
+ "description": "Output says targets must preserve the capability contract.",
+ "weight": 1.0
+ }
+ ],
+ "variant_a": {
+ "blind_id": "ir-before-packaging:A",
+ "output": "Export folders for each platform and adjust files as needed."
+ },
+ "variant_b": {
+ "blind_id": "ir-before-packaging:B",
+ "output": "Export Skill IR first with job_to_be_done, trigger_surface, workflow, resources, eval_plan, risk, and governance. Then compile or package targets from the IR so OpenAI, Claude, Agent Skills, and generic packages preserve the same capability contract."
+ }
+ },
+ {
+ "case_id": "near-neighbor-boundary",
+ "prompt": "I only need a one-off summary of these notes, not a reusable process.",
+ "input_files": [],
+ "metadata": {
+ "case_type": "near_neighbor",
+ "tier": "production"
+ },
+ "review_instruction": "Pick A or B based only on the rubric. Do not infer which output came from the skill.",
+ "rubric": [
+ {
+ "id": "declines-skill",
+ "description": "Output refuses unnecessary skill creation for one-off work.",
+ "weight": 1.0
+ },
+ {
+ "id": "names-near-neighbor",
+ "description": "Output labels the request as near-neighbor instead of owned work.",
+ "weight": 1.0
+ },
+ {
+ "id": "requires-reuse-signal",
+ "description": "Output asks for repeat-use evidence before packaging.",
+ "weight": 1.0
+ }
+ ],
+ "variant_a": {
+ "blind_id": "near-neighbor-boundary:A",
+ "output": "Create a SKILL.md and a reusable workflow anyway so future notes can use it."
+ },
+ "variant_b": {
+ "blind_id": "near-neighbor-boundary:B",
+ "output": "Do not create a skill for this one-off request. Treat it as a near-neighbor: answer the summary directly unless the user confirms repeated use, shared ownership, or a reusable output contract."
+ }
+ },
+ {
+ "case_id": "file-backed-governed-package",
+ "prompt": "Turn the attached release brief source into a governed skill package.",
+ "input_files": [
+ "fixtures/release-brief-source.md"
+ ],
+ "metadata": {
+ "case_type": "boundary",
+ "tier": "governed"
+ },
+ "review_instruction": "Pick A or B based only on the rubric. Do not infer which output came from the skill.",
+ "rubric": [
+ {
+ "id": "uses-file-backed-evidence",
+ "description": "Output names file-backed source evidence.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-governance",
+ "description": "Output preserves governed ownership metadata.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-output-contract",
+ "description": "Output preserves output and rollback boundaries.",
+ "weight": 1.0
+ },
+ {
+ "id": "has-trust-and-scorecard",
+ "description": "Output requires trust and output scorecard artifacts.",
+ "weight": 1.0
+ },
+ {
+ "id": "does-not-invent-evidence",
+ "description": "Output forbids invented launch evidence.",
+ "weight": 1.0
+ }
+ ],
+ "variant_a": {
+ "blind_id": "file-backed-governed-package:A",
+ "output": "Draft a release announcement with the changelog, support notes, and owner name."
+ },
+ "variant_b": {
+ "blind_id": "file-backed-governed-package:B",
+ "output": "Use the file-backed fixture as source evidence, then create a governed skill package with SKILL.md, agents/interface.yaml, owner, review cadence, input_files, output contract, rollback boundary, trust report, and reports/output_quality_scorecard.md. Mark missing launch metrics as missing evidence instead of inventing them."
+ }
+ }
+ ]
+}
diff --git a/reports/output_blind_review_pack.md b/reports/output_blind_review_pack.md
new file mode 100644
index 0000000..ba78e24
--- /dev/null
+++ b/reports/output_blind_review_pack.md
@@ -0,0 +1,97 @@
+# Output Blind A/B Review Pack
+
+This packet hides whether each variant came from the baseline or the skill-guided output. Use the separate answer key only after review.
+
+- Pairs: `5`
+- Seed: `yao-output-eval-blind-v1`
+- Answer key separate: `True`
+
+## Case: skill-package-contract
+
+Prompt: Turn this repeated workflow into a reusable team skill package.
+
+Rubric:
+- `has-entrypoint` (1.0): Output names the routeable Skill entrypoint.
+- `has-interface` (1.0): Output includes neutral interface metadata.
+- `has-report` (1.0): Output points reviewer to generated overview report.
+- `has-resource-boundary` (1.0): Output preserves entrypoint/resource separation.
+
+### Variant A
+
+Create a routeable SKILL.md, agents/interface.yaml, reports/skill-overview.html, and a focused eval plan. Keep the root entrypoint lean, move durable guidance into references/, scripts into scripts/, and evidence into reports/.
+
+### Variant B
+
+I can write a prompt for that workflow and include a short checklist.
+
+## Case: output-eval-expectation
+
+Prompt: Upgrade this production skill so we know whether the generated output is better than baseline.
+
+Rubric:
+- `has-baseline-comparison` (1.0): Output explicitly compares with-skill and baseline outputs.
+- `has-assertion-grading` (1.0): Output includes objective assertion grading.
+- `has-scorecard` (1.0): Output produces a scorecard report path.
+- `has-failure-taxonomy` (1.0): Output records failure taxonomy.
+
+### Variant A
+
+Add Output Eval Lab cases with baseline_output and with_skill_output, run assertion grading, report with-skill vs baseline pass-rate delta, and record failure taxonomy plus next fixes in reports/output_quality_scorecard.md.
+
+### Variant B
+
+Add more examples and run the trigger eval again.
+
+## Case: ir-before-packaging
+
+Prompt: Package this skill for OpenAI, Claude, Agent Skills, and generic targets.
+
+Rubric:
+- `has-ir-first` (1.0): Output requires Skill IR before packaging.
+- `has-core-ir-fields` (1.0): Output lists core IR contract fields.
+- `has-targets` (1.0): Output names requested runtime targets.
+- `has-semantic-preservation` (1.0): Output says targets must preserve the capability contract.
+
+### Variant A
+
+Export folders for each platform and adjust files as needed.
+
+### Variant B
+
+Export Skill IR first with job_to_be_done, trigger_surface, workflow, resources, eval_plan, risk, and governance. Then compile or package targets from the IR so OpenAI, Claude, Agent Skills, and generic packages preserve the same capability contract.
+
+## Case: near-neighbor-boundary
+
+Prompt: I only need a one-off summary of these notes, not a reusable process.
+
+Rubric:
+- `declines-skill` (1.0): Output refuses unnecessary skill creation for one-off work.
+- `names-near-neighbor` (1.0): Output labels the request as near-neighbor instead of owned work.
+- `requires-reuse-signal` (1.0): Output asks for repeat-use evidence before packaging.
+
+### Variant A
+
+Create a SKILL.md and a reusable workflow anyway so future notes can use it.
+
+### Variant B
+
+Do not create a skill for this one-off request. Treat it as a near-neighbor: answer the summary directly unless the user confirms repeated use, shared ownership, or a reusable output contract.
+
+## Case: file-backed-governed-package
+
+Prompt: Turn the attached release brief source into a governed skill package.
+
+Rubric:
+- `uses-file-backed-evidence` (1.0): Output names file-backed source evidence.
+- `has-governance` (1.0): Output preserves governed ownership metadata.
+- `has-output-contract` (1.0): Output preserves output and rollback boundaries.
+- `has-trust-and-scorecard` (1.0): Output requires trust and output scorecard artifacts.
+- `does-not-invent-evidence` (1.0): Output forbids invented launch evidence.
+
+### Variant A
+
+Draft a release announcement with the changelog, support notes, and owner name.
+
+### Variant B
+
+Use the file-backed fixture as source evidence, then create a governed skill package with SKILL.md, agents/interface.yaml, owner, review cadence, input_files, output contract, rollback boundary, trust report, and reports/output_quality_scorecard.md. Mark missing launch metrics as missing evidence instead of inventing them.
diff --git a/reports/output_execution_runs.json b/reports/output_execution_runs.json
new file mode 100644
index 0000000..32b0660
--- /dev/null
+++ b/reports/output_execution_runs.json
@@ -0,0 +1,291 @@
+{
+ "schema_version": "1.0",
+ "ok": true,
+ "cases": "evals/output/cases.jsonl",
+ "runner": {
+ "mode": "command",
+ "command": [
+ "python3",
+ "scripts/local_output_eval_runner.py"
+ ],
+ "timeout_seconds": 30.0
+ },
+ "summary": {
+ "case_count": 5,
+ "variant_run_count": 10,
+ "command_executed_count": 10,
+ "model_executed_count": 0,
+ "recorded_fixture_count": 0,
+ "timing_observed_count": 10,
+ "token_observed_count": 0,
+ "token_estimated_count": 10,
+ "baseline_pass_rate": 0.0,
+ "with_skill_pass_rate": 100.0,
+ "delta": 100.0,
+ "regression_count": 0,
+ "failure_count": 0,
+ "gate_pass": true
+ },
+ "runs": [
+ {
+ "case_id": "skill-package-contract",
+ "variant": "baseline",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 27.22,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 16,
+ "output_tokens": 17,
+ "total_tokens": 33,
+ "estimated": true
+ },
+ "score": 0.0,
+ "passed_count": 0,
+ "failed_count": 4,
+ "failed_assertions": [
+ "has-entrypoint",
+ "has-interface",
+ "has-report",
+ "has-resource-boundary"
+ ],
+ "output_sha256": "ece26a6edbbbea86a93faaf9f0eadf88efbae12f1c3ad81da9376cf2a889d101",
+ "failure": ""
+ },
+ {
+ "case_id": "skill-package-contract",
+ "variant": "with_skill",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 27.12,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 16,
+ "output_tokens": 57,
+ "total_tokens": 73,
+ "estimated": true
+ },
+ "score": 100.0,
+ "passed_count": 4,
+ "failed_count": 0,
+ "failed_assertions": [],
+ "output_sha256": "8bee0131e17fdbe87e48457130ac6aeaa55ea30c919a45e77109852609f33eba",
+ "failure": ""
+ },
+ {
+ "case_id": "output-eval-expectation",
+ "variant": "baseline",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 27.12,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 24,
+ "output_tokens": 12,
+ "total_tokens": 36,
+ "estimated": true
+ },
+ "score": 0.0,
+ "passed_count": 0,
+ "failed_count": 4,
+ "failed_assertions": [
+ "has-baseline-comparison",
+ "has-assertion-grading",
+ "has-scorecard",
+ "has-failure-taxonomy"
+ ],
+ "output_sha256": "98fa332fb493b5dc14656a9d65a6c0a9c25ff61a14b71b647aad89cbdbd3ab35",
+ "failure": ""
+ },
+ {
+ "case_id": "output-eval-expectation",
+ "variant": "with_skill",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 30.03,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 24,
+ "output_tokens": 56,
+ "total_tokens": 80,
+ "estimated": true
+ },
+ "score": 100.0,
+ "passed_count": 4,
+ "failed_count": 0,
+ "failed_assertions": [],
+ "output_sha256": "8efdbfefa6a36603682b7063b1753f9f939b3810c082d29686e297906d9f51c8",
+ "failure": ""
+ },
+ {
+ "case_id": "ir-before-packaging",
+ "variant": "baseline",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 27.11,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 18,
+ "output_tokens": 15,
+ "total_tokens": 33,
+ "estimated": true
+ },
+ "score": 0.0,
+ "passed_count": 0,
+ "failed_count": 4,
+ "failed_assertions": [
+ "has-ir-first",
+ "has-core-ir-fields",
+ "has-targets",
+ "has-semantic-preservation"
+ ],
+ "output_sha256": "07a4aa9ee9e48341d4b84d5cb9b6414901aa2c8841340d67447e187240c6c4c2",
+ "failure": ""
+ },
+ {
+ "case_id": "ir-before-packaging",
+ "variant": "with_skill",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 26.68,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 18,
+ "output_tokens": 62,
+ "total_tokens": 80,
+ "estimated": true
+ },
+ "score": 100.0,
+ "passed_count": 4,
+ "failed_count": 0,
+ "failed_assertions": [],
+ "output_sha256": "707fde419b3d61e921561b1c4a8523e1f7b53b1acd5758a47ce21d9ed711fde0",
+ "failure": ""
+ },
+ {
+ "case_id": "near-neighbor-boundary",
+ "variant": "baseline",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 27.07,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 17,
+ "output_tokens": 19,
+ "total_tokens": 36,
+ "estimated": true
+ },
+ "score": 0.0,
+ "passed_count": 0,
+ "failed_count": 3,
+ "failed_assertions": [
+ "declines-skill",
+ "names-near-neighbor",
+ "requires-reuse-signal"
+ ],
+ "output_sha256": "648ebaa6e09486d05f33fa6639dc973b029d115158588fd192efbe15ccaaeac4",
+ "failure": ""
+ },
+ {
+ "case_id": "near-neighbor-boundary",
+ "variant": "with_skill",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 27.57,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 17,
+ "output_tokens": 48,
+ "total_tokens": 65,
+ "estimated": true
+ },
+ "score": 100.0,
+ "passed_count": 3,
+ "failed_count": 0,
+ "failed_assertions": [],
+ "output_sha256": "17a3a5286ad573dea86e51f82c04b596babaecb92cde8879f09e7c519205e2e1",
+ "failure": ""
+ },
+ {
+ "case_id": "file-backed-governed-package",
+ "variant": "baseline",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 29.2,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 17,
+ "output_tokens": 20,
+ "total_tokens": 37,
+ "estimated": true
+ },
+ "score": 0.0,
+ "passed_count": 0,
+ "failed_count": 5,
+ "failed_assertions": [
+ "uses-file-backed-evidence",
+ "has-governance",
+ "has-output-contract",
+ "has-trust-and-scorecard",
+ "does-not-invent-evidence"
+ ],
+ "output_sha256": "6e5827219459dee34143e4f11663415db80c3111291f75fb6c2115c7bda4cf30",
+ "failure": ""
+ },
+ {
+ "case_id": "file-backed-governed-package",
+ "variant": "with_skill",
+ "status": "pass",
+ "execution_mode": "command",
+ "model_executed": false,
+ "command_executed": true,
+ "duration_ms": 26.94,
+ "provider": "local-output-eval-runner",
+ "model": "",
+ "usage": {
+ "input_tokens": 17,
+ "output_tokens": 81,
+ "total_tokens": 98,
+ "estimated": true
+ },
+ "score": 100.0,
+ "passed_count": 5,
+ "failed_count": 0,
+ "failed_assertions": [],
+ "output_sha256": "bcfdf036666d406abbc945fc42b93eb74d7074118893e540253c7d8715baad73",
+ "failure": ""
+ }
+ ],
+ "failures": [],
+ "artifacts": {
+ "json": "reports/output_execution_runs.json",
+ "markdown": "reports/output_execution_runs.md"
+ }
+}
diff --git a/reports/output_execution_runs.md b/reports/output_execution_runs.md
new file mode 100644
index 0000000..ac9d4c6
--- /dev/null
+++ b/reports/output_execution_runs.md
@@ -0,0 +1,41 @@
+# Output Execution Runs
+
+This report records how output-eval variants were produced and whether timing or token evidence is observed or estimated.
+
+- Cases: `5`
+- Variant runs: `10`
+- Command executed: `10`
+- Model executed: `0`
+- Recorded fixtures: `0`
+- Timing observed: `10`
+- Token observed: `0`
+- Token estimated: `10`
+- Delta: `100.0`
+- Gate pass: `True`
+
+No model-executed runs are recorded yet.
+
+Use `--runner-command` with a provider-backed runner to replace recorded fixtures with real model output evidence.
+
+Command runner evidence is present. This proves the eval harness executed an external command, but it is not provider-backed model evidence unless the runner reports model metadata.
+
+## Runs
+
+| Case | Variant | Mode | Model | Duration ms | Tokens | Score | Status |
+| --- | --- | --- | --- | ---: | ---: | ---: | --- |
+| skill-package-contract | baseline | command | local-output-eval-runner | 27.22 | 33 | 0.0 | pass |
+| skill-package-contract | with_skill | command | local-output-eval-runner | 27.12 | 73 | 100.0 | pass |
+| output-eval-expectation | baseline | command | local-output-eval-runner | 27.12 | 36 | 0.0 | pass |
+| output-eval-expectation | with_skill | command | local-output-eval-runner | 30.03 | 80 | 100.0 | pass |
+| ir-before-packaging | baseline | command | local-output-eval-runner | 27.11 | 33 | 0.0 | pass |
+| ir-before-packaging | with_skill | command | local-output-eval-runner | 26.68 | 80 | 100.0 | pass |
+| near-neighbor-boundary | baseline | command | local-output-eval-runner | 27.07 | 36 | 0.0 | pass |
+| near-neighbor-boundary | with_skill | command | local-output-eval-runner | 27.57 | 65 | 100.0 | pass |
+| file-backed-governed-package | baseline | command | local-output-eval-runner | 29.2 | 37 | 0.0 | pass |
+| file-backed-governed-package | with_skill | command | local-output-eval-runner | 26.94 | 98 | 100.0 | pass |
+
+## Next Fixes
+
+- Keep recorded fixtures as reproducible baselines, but do not describe them as model-executed evidence.
+- Add provider-backed command runners for holdout cases when release confidence depends on real generation behavior.
+- Compare timing, token cost, and assertion deltas before promoting a skill to governed reuse.
diff --git a/reports/output_quality_scorecard.json b/reports/output_quality_scorecard.json
index bc47077..db0957e 100644
--- a/reports/output_quality_scorecard.json
+++ b/reports/output_quality_scorecard.json
@@ -11,7 +11,8 @@
"delta": 100.0,
"regression_count": 0,
"gate_pass": true,
- "failure_taxonomy": []
+ "failure_taxonomy": [],
+ "blind_pair_count": 5
},
"results": [
{
@@ -800,8 +801,16 @@
}
],
"failures": [],
+ "blind_review": {
+ "pack": "reports/output_blind_review_pack.json",
+ "answer_key": "reports/output_blind_answer_key.json",
+ "pair_count": 5
+ },
"artifacts": {
"json": "reports/output_quality_scorecard.json",
- "markdown": "reports/output_quality_scorecard.md"
+ "markdown": "reports/output_quality_scorecard.md",
+ "blind_review_pack_json": "reports/output_blind_review_pack.json",
+ "blind_review_pack_md": "reports/output_blind_review_pack.md",
+ "blind_answer_key_json": "reports/output_blind_answer_key.json"
}
}
diff --git a/reports/output_quality_scorecard.md b/reports/output_quality_scorecard.md
index aa1cc12..20a32ad 100644
--- a/reports/output_quality_scorecard.md
+++ b/reports/output_quality_scorecard.md
@@ -7,8 +7,12 @@ This v0 scorecard compares static without-skill and with-skill outputs using ass
- With-skill pass rate: `100.0`
- Delta: `100.0`
- Regressions: `0`
+- Blind A/B pairs: `5`
- Gate pass: `True`
+Blind review artifacts are generated separately so reviewers can inspect A/B outputs without seeing the answer key.
+Run output review adjudication after reviewer decisions are recorded; pending cases should stay pending rather than being counted as human agreement.
+
## Case Results
| Case | Baseline | With Skill | Delta | Winner | Failed With-Skill Assertions |
diff --git a/reports/output_review_adjudication.json b/reports/output_review_adjudication.json
new file mode 100644
index 0000000..0d58d32
--- /dev/null
+++ b/reports/output_review_adjudication.json
@@ -0,0 +1,73 @@
+{
+ "schema_version": "1.0",
+ "ok": true,
+ "summary": {
+ "pair_count": 5,
+ "judgment_count": 0,
+ "pending_count": 5,
+ "agreement_count": 0,
+ "disagreement_count": 0,
+ "invalid_decision_count": 0,
+ "agreement_rate": null,
+ "needs_review": true,
+ "failure_count": 0
+ },
+ "reviewer": "",
+ "reviewed_at": "",
+ "artifacts": {
+ "blind_pack": "reports/output_blind_review_pack.json",
+ "answer_key": "reports/output_blind_answer_key.json",
+ "decisions": "reports/output_review_decisions.json",
+ "json": "reports/output_review_adjudication.json",
+ "markdown": "reports/output_review_adjudication.md"
+ },
+ "template_written": false,
+ "pairs": [
+ {
+ "case_id": "skill-package-contract",
+ "status": "pending",
+ "expected_winner_variant": "A",
+ "reviewer_winner_variant": "",
+ "confidence": null,
+ "reason": "",
+ "prompt": "Turn this repeated workflow into a reusable team skill package."
+ },
+ {
+ "case_id": "output-eval-expectation",
+ "status": "pending",
+ "expected_winner_variant": "A",
+ "reviewer_winner_variant": "",
+ "confidence": null,
+ "reason": "",
+ "prompt": "Upgrade this production skill so we know whether the generated output is better than baseline."
+ },
+ {
+ "case_id": "ir-before-packaging",
+ "status": "pending",
+ "expected_winner_variant": "B",
+ "reviewer_winner_variant": "",
+ "confidence": null,
+ "reason": "",
+ "prompt": "Package this skill for OpenAI, Claude, Agent Skills, and generic targets."
+ },
+ {
+ "case_id": "near-neighbor-boundary",
+ "status": "pending",
+ "expected_winner_variant": "B",
+ "reviewer_winner_variant": "",
+ "confidence": null,
+ "reason": "",
+ "prompt": "I only need a one-off summary of these notes, not a reusable process."
+ },
+ {
+ "case_id": "file-backed-governed-package",
+ "status": "pending",
+ "expected_winner_variant": "B",
+ "reviewer_winner_variant": "",
+ "confidence": null,
+ "reason": "",
+ "prompt": "Turn the attached release brief source into a governed skill package."
+ }
+ ],
+ "failures": []
+}
diff --git a/reports/output_review_adjudication.md b/reports/output_review_adjudication.md
new file mode 100644
index 0000000..6c12de4
--- /dev/null
+++ b/reports/output_review_adjudication.md
@@ -0,0 +1,29 @@
+# Output Review Adjudication
+
+This report adjudicates reviewer choices from the blind A/B output review pack against the separate answer key.
+
+- Pairs: `5`
+- Judgments: `0`
+- Pending: `5`
+- Agreement rate: `n/a`
+- Invalid decisions: `0`
+
+No reviewer decisions recorded yet.
+
+Generate a template with `--write-template`, fill `winner_variant` with `A` or `B`, then rerun adjudication.
+
+## Case Adjudication
+
+| Case | Reviewer | Expected | Status | Confidence | Reason |
+| --- | --- | --- | --- | ---: | --- |
+| skill-package-contract | pending | A | pending | | |
+| output-eval-expectation | pending | A | pending | | |
+| ir-before-packaging | pending | B | pending | | |
+| near-neighbor-boundary | pending | B | pending | | |
+| file-backed-governed-package | pending | B | pending | | |
+
+## Next Fixes
+
+- Keep the blind review pack separate from the answer key until decisions are recorded.
+- Treat disagreement cases as prompts for rubric tuning or output improvement.
+- Add model-executed holdout runs after this human adjudication harness is stable.
diff --git a/reports/package_verification.json b/reports/package_verification.json
new file mode 100644
index 0000000..17be2de
--- /dev/null
+++ b/reports/package_verification.json
@@ -0,0 +1,516 @@
+{
+ "ok": true,
+ "schema_version": "2.0",
+ "generated_at": "2026-06-13",
+ "skill_dir": ".",
+ "package_dir": "dist",
+ "summary": {
+ "target_count": 3,
+ "adapter_count": 3,
+ "archive_present": true,
+ "archive_sha256": "4d1227dc0996a97aa4987761d46081391fe15b36362e19765e1e7aa8e5d41c06",
+ "archive_entry_count": 483,
+ "failure_count": 0,
+ "warning_count": 0
+ },
+ "checks": [
+ {
+ "id": "package-manifest",
+ "status": "pass",
+ "detail": "Package manifest exists: dist/manifest.json"
+ },
+ {
+ "id": "openai-adapter",
+ "status": "pass",
+ "detail": "Adapter exists for target: openai"
+ },
+ {
+ "id": "openai-field-name",
+ "status": "pass",
+ "detail": "openai adapter includes field: name"
+ },
+ {
+ "id": "openai-field-description",
+ "status": "pass",
+ "detail": "openai adapter includes field: description"
+ },
+ {
+ "id": "openai-field-version",
+ "status": "pass",
+ "detail": "openai adapter includes field: version"
+ },
+ {
+ "id": "openai-field-display_name",
+ "status": "pass",
+ "detail": "openai adapter includes field: display_name"
+ },
+ {
+ "id": "openai-field-short_description",
+ "status": "pass",
+ "detail": "openai adapter includes field: short_description"
+ },
+ {
+ "id": "openai-field-default_prompt",
+ "status": "pass",
+ "detail": "openai adapter includes field: default_prompt"
+ },
+ {
+ "id": "openai-field-job_to_be_done",
+ "status": "pass",
+ "detail": "openai adapter includes field: job_to_be_done"
+ },
+ {
+ "id": "openai-field-ir_source",
+ "status": "pass",
+ "detail": "openai adapter includes field: ir_source"
+ },
+ {
+ "id": "openai-field-ir_schema_version",
+ "status": "pass",
+ "detail": "openai adapter includes field: ir_schema_version"
+ },
+ {
+ "id": "openai-field-semantic_contract",
+ "status": "pass",
+ "detail": "openai adapter includes field: semantic_contract"
+ },
+ {
+ "id": "openai-field-semantic_parity",
+ "status": "pass",
+ "detail": "openai adapter includes field: semantic_parity"
+ },
+ {
+ "id": "openai-field-compiler",
+ "status": "pass",
+ "detail": "openai adapter includes field: compiler"
+ },
+ {
+ "id": "openai-field-compiled_contract",
+ "status": "pass",
+ "detail": "openai adapter includes field: compiled_contract"
+ },
+ {
+ "id": "openai-field-permission_contract",
+ "status": "pass",
+ "detail": "openai adapter includes field: permission_contract"
+ },
+ {
+ "id": "openai-field-target_permission_contract",
+ "status": "pass",
+ "detail": "openai adapter includes field: target_permission_contract"
+ },
+ {
+ "id": "openai-field-target_native_contract",
+ "status": "pass",
+ "detail": "openai adapter includes field: target_native_contract"
+ },
+ {
+ "id": "openai-field-target_transform",
+ "status": "pass",
+ "detail": "openai adapter includes field: target_transform"
+ },
+ {
+ "id": "openai-field-canonical_metadata",
+ "status": "pass",
+ "detail": "openai adapter includes field: canonical_metadata"
+ },
+ {
+ "id": "openai-field-canonical_format",
+ "status": "pass",
+ "detail": "openai adapter includes field: canonical_format"
+ },
+ {
+ "id": "openai-field-activation_mode",
+ "status": "pass",
+ "detail": "openai adapter includes field: activation_mode"
+ },
+ {
+ "id": "openai-field-execution_context",
+ "status": "pass",
+ "detail": "openai adapter includes field: execution_context"
+ },
+ {
+ "id": "openai-field-shell",
+ "status": "pass",
+ "detail": "openai adapter includes field: shell"
+ },
+ {
+ "id": "openai-field-trust_level",
+ "status": "pass",
+ "detail": "openai adapter includes field: trust_level"
+ },
+ {
+ "id": "openai-field-remote_inline_execution",
+ "status": "pass",
+ "detail": "openai adapter includes field: remote_inline_execution"
+ },
+ {
+ "id": "openai-field-degradation_strategy",
+ "status": "pass",
+ "detail": "openai adapter includes field: degradation_strategy"
+ },
+ {
+ "id": "openai-field-portability_profile",
+ "status": "pass",
+ "detail": "openai adapter includes field: portability_profile"
+ },
+ {
+ "id": "claude-adapter",
+ "status": "pass",
+ "detail": "Adapter exists for target: claude"
+ },
+ {
+ "id": "claude-field-name",
+ "status": "pass",
+ "detail": "claude adapter includes field: name"
+ },
+ {
+ "id": "claude-field-description",
+ "status": "pass",
+ "detail": "claude adapter includes field: description"
+ },
+ {
+ "id": "claude-field-version",
+ "status": "pass",
+ "detail": "claude adapter includes field: version"
+ },
+ {
+ "id": "claude-field-display_name",
+ "status": "pass",
+ "detail": "claude adapter includes field: display_name"
+ },
+ {
+ "id": "claude-field-short_description",
+ "status": "pass",
+ "detail": "claude adapter includes field: short_description"
+ },
+ {
+ "id": "claude-field-default_prompt",
+ "status": "pass",
+ "detail": "claude adapter includes field: default_prompt"
+ },
+ {
+ "id": "claude-field-job_to_be_done",
+ "status": "pass",
+ "detail": "claude adapter includes field: job_to_be_done"
+ },
+ {
+ "id": "claude-field-ir_source",
+ "status": "pass",
+ "detail": "claude adapter includes field: ir_source"
+ },
+ {
+ "id": "claude-field-ir_schema_version",
+ "status": "pass",
+ "detail": "claude adapter includes field: ir_schema_version"
+ },
+ {
+ "id": "claude-field-semantic_contract",
+ "status": "pass",
+ "detail": "claude adapter includes field: semantic_contract"
+ },
+ {
+ "id": "claude-field-semantic_parity",
+ "status": "pass",
+ "detail": "claude adapter includes field: semantic_parity"
+ },
+ {
+ "id": "claude-field-compiler",
+ "status": "pass",
+ "detail": "claude adapter includes field: compiler"
+ },
+ {
+ "id": "claude-field-compiled_contract",
+ "status": "pass",
+ "detail": "claude adapter includes field: compiled_contract"
+ },
+ {
+ "id": "claude-field-permission_contract",
+ "status": "pass",
+ "detail": "claude adapter includes field: permission_contract"
+ },
+ {
+ "id": "claude-field-target_permission_contract",
+ "status": "pass",
+ "detail": "claude adapter includes field: target_permission_contract"
+ },
+ {
+ "id": "claude-field-target_native_contract",
+ "status": "pass",
+ "detail": "claude adapter includes field: target_native_contract"
+ },
+ {
+ "id": "claude-field-target_transform",
+ "status": "pass",
+ "detail": "claude adapter includes field: target_transform"
+ },
+ {
+ "id": "claude-field-canonical_metadata",
+ "status": "pass",
+ "detail": "claude adapter includes field: canonical_metadata"
+ },
+ {
+ "id": "claude-field-canonical_format",
+ "status": "pass",
+ "detail": "claude adapter includes field: canonical_format"
+ },
+ {
+ "id": "claude-field-activation_mode",
+ "status": "pass",
+ "detail": "claude adapter includes field: activation_mode"
+ },
+ {
+ "id": "claude-field-execution_context",
+ "status": "pass",
+ "detail": "claude adapter includes field: execution_context"
+ },
+ {
+ "id": "claude-field-shell",
+ "status": "pass",
+ "detail": "claude adapter includes field: shell"
+ },
+ {
+ "id": "claude-field-trust_level",
+ "status": "pass",
+ "detail": "claude adapter includes field: trust_level"
+ },
+ {
+ "id": "claude-field-remote_inline_execution",
+ "status": "pass",
+ "detail": "claude adapter includes field: remote_inline_execution"
+ },
+ {
+ "id": "claude-field-degradation_strategy",
+ "status": "pass",
+ "detail": "claude adapter includes field: degradation_strategy"
+ },
+ {
+ "id": "claude-field-portability_profile",
+ "status": "pass",
+ "detail": "claude adapter includes field: portability_profile"
+ },
+ {
+ "id": "generic-adapter",
+ "status": "pass",
+ "detail": "Adapter exists for target: generic"
+ },
+ {
+ "id": "generic-field-name",
+ "status": "pass",
+ "detail": "generic adapter includes field: name"
+ },
+ {
+ "id": "generic-field-description",
+ "status": "pass",
+ "detail": "generic adapter includes field: description"
+ },
+ {
+ "id": "generic-field-version",
+ "status": "pass",
+ "detail": "generic adapter includes field: version"
+ },
+ {
+ "id": "generic-field-display_name",
+ "status": "pass",
+ "detail": "generic adapter includes field: display_name"
+ },
+ {
+ "id": "generic-field-short_description",
+ "status": "pass",
+ "detail": "generic adapter includes field: short_description"
+ },
+ {
+ "id": "generic-field-default_prompt",
+ "status": "pass",
+ "detail": "generic adapter includes field: default_prompt"
+ },
+ {
+ "id": "generic-field-job_to_be_done",
+ "status": "pass",
+ "detail": "generic adapter includes field: job_to_be_done"
+ },
+ {
+ "id": "generic-field-ir_source",
+ "status": "pass",
+ "detail": "generic adapter includes field: ir_source"
+ },
+ {
+ "id": "generic-field-ir_schema_version",
+ "status": "pass",
+ "detail": "generic adapter includes field: ir_schema_version"
+ },
+ {
+ "id": "generic-field-semantic_contract",
+ "status": "pass",
+ "detail": "generic adapter includes field: semantic_contract"
+ },
+ {
+ "id": "generic-field-semantic_parity",
+ "status": "pass",
+ "detail": "generic adapter includes field: semantic_parity"
+ },
+ {
+ "id": "generic-field-compiler",
+ "status": "pass",
+ "detail": "generic adapter includes field: compiler"
+ },
+ {
+ "id": "generic-field-compiled_contract",
+ "status": "pass",
+ "detail": "generic adapter includes field: compiled_contract"
+ },
+ {
+ "id": "generic-field-permission_contract",
+ "status": "pass",
+ "detail": "generic adapter includes field: permission_contract"
+ },
+ {
+ "id": "generic-field-target_permission_contract",
+ "status": "pass",
+ "detail": "generic adapter includes field: target_permission_contract"
+ },
+ {
+ "id": "generic-field-target_native_contract",
+ "status": "pass",
+ "detail": "generic adapter includes field: target_native_contract"
+ },
+ {
+ "id": "generic-field-target_transform",
+ "status": "pass",
+ "detail": "generic adapter includes field: target_transform"
+ },
+ {
+ "id": "generic-field-canonical_metadata",
+ "status": "pass",
+ "detail": "generic adapter includes field: canonical_metadata"
+ },
+ {
+ "id": "generic-field-canonical_format",
+ "status": "pass",
+ "detail": "generic adapter includes field: canonical_format"
+ },
+ {
+ "id": "generic-field-activation_mode",
+ "status": "pass",
+ "detail": "generic adapter includes field: activation_mode"
+ },
+ {
+ "id": "generic-field-execution_context",
+ "status": "pass",
+ "detail": "generic adapter includes field: execution_context"
+ },
+ {
+ "id": "generic-field-shell",
+ "status": "pass",
+ "detail": "generic adapter includes field: shell"
+ },
+ {
+ "id": "generic-field-trust_level",
+ "status": "pass",
+ "detail": "generic adapter includes field: trust_level"
+ },
+ {
+ "id": "generic-field-remote_inline_execution",
+ "status": "pass",
+ "detail": "generic adapter includes field: remote_inline_execution"
+ },
+ {
+ "id": "generic-field-degradation_strategy",
+ "status": "pass",
+ "detail": "generic adapter includes field: degradation_strategy"
+ },
+ {
+ "id": "generic-field-portability_profile",
+ "status": "pass",
+ "detail": "generic adapter includes field: portability_profile"
+ },
+ {
+ "id": "openai-file-targets/openai/adapter.json",
+ "status": "pass",
+ "detail": "Package contains targets/openai/adapter.json"
+ },
+ {
+ "id": "openai-file-targets/openai/agents/openai.yaml",
+ "status": "pass",
+ "detail": "Package contains targets/openai/agents/openai.yaml"
+ },
+ {
+ "id": "claude-file-targets/claude/adapter.json",
+ "status": "pass",
+ "detail": "Package contains targets/claude/adapter.json"
+ },
+ {
+ "id": "claude-file-targets/claude/README.md",
+ "status": "pass",
+ "detail": "Package contains targets/claude/README.md"
+ },
+ {
+ "id": "generic-file-targets/generic/adapter.json",
+ "status": "pass",
+ "detail": "Package contains targets/generic/adapter.json"
+ },
+ {
+ "id": "archive-safe-paths",
+ "status": "pass",
+ "detail": "Archive has no absolute or parent-traversal entries"
+ },
+ {
+ "id": "archive-entry-yao-meta-skill/SKILL.md",
+ "status": "pass",
+ "detail": "Archive contains yao-meta-skill/SKILL.md"
+ },
+ {
+ "id": "archive-entry-yao-meta-skill/manifest.json",
+ "status": "pass",
+ "detail": "Archive contains yao-meta-skill/manifest.json"
+ },
+ {
+ "id": "archive-entry-yao-meta-skill/agents/interface.yaml",
+ "status": "pass",
+ "detail": "Archive contains yao-meta-skill/agents/interface.yaml"
+ },
+ {
+ "id": "archive-excludes-generated",
+ "status": "pass",
+ "detail": "Archive excludes generated dist/ and tests/tmp* contents"
+ },
+ {
+ "id": "registry-ok",
+ "status": "pass",
+ "detail": "Registry audit is OK"
+ },
+ {
+ "id": "registry-name-match",
+ "status": "pass",
+ "detail": "Registry package name matches package manifest"
+ },
+ {
+ "id": "registry-version-match",
+ "status": "pass",
+ "detail": "Registry package version matches package manifest"
+ },
+ {
+ "id": "registry-compat-openai",
+ "status": "pass",
+ "detail": "Registry compatibility is reviewable for target: openai"
+ },
+ {
+ "id": "registry-compat-claude",
+ "status": "pass",
+ "detail": "Registry compatibility is reviewable for target: claude"
+ },
+ {
+ "id": "registry-compat-generic",
+ "status": "pass",
+ "detail": "Registry compatibility is reviewable for target: generic"
+ }
+ ],
+ "failures": [],
+ "warnings": [],
+ "artifacts": {
+ "manifest": "dist/manifest.json",
+ "archive": "dist/yao-meta-skill.zip",
+ "json": "reports/package_verification.json",
+ "markdown": "reports/package_verification.md"
+ }
+}
diff --git a/reports/package_verification.md b/reports/package_verification.md
new file mode 100644
index 0000000..c17f69c
--- /dev/null
+++ b/reports/package_verification.md
@@ -0,0 +1,120 @@
+# Package Verification
+
+- OK: `True`
+- Package directory: `dist`
+- Targets: `3 / 3` adapters present
+- Archive present: `True`
+- Archive SHA256: `4d1227dc0996a97aa4987761d46081391fe15b36362e19765e1e7aa8e5d41c06`
+- Failures: `0`
+- Warnings: `0`
+
+## Checks
+
+| Check | Status | Detail |
+| --- | --- | --- |
+| `package-manifest` | `pass` | Package manifest exists: dist/manifest.json |
+| `openai-adapter` | `pass` | Adapter exists for target: openai |
+| `openai-field-name` | `pass` | openai adapter includes field: name |
+| `openai-field-description` | `pass` | openai adapter includes field: description |
+| `openai-field-version` | `pass` | openai adapter includes field: version |
+| `openai-field-display_name` | `pass` | openai adapter includes field: display_name |
+| `openai-field-short_description` | `pass` | openai adapter includes field: short_description |
+| `openai-field-default_prompt` | `pass` | openai adapter includes field: default_prompt |
+| `openai-field-job_to_be_done` | `pass` | openai adapter includes field: job_to_be_done |
+| `openai-field-ir_source` | `pass` | openai adapter includes field: ir_source |
+| `openai-field-ir_schema_version` | `pass` | openai adapter includes field: ir_schema_version |
+| `openai-field-semantic_contract` | `pass` | openai adapter includes field: semantic_contract |
+| `openai-field-semantic_parity` | `pass` | openai adapter includes field: semantic_parity |
+| `openai-field-compiler` | `pass` | openai adapter includes field: compiler |
+| `openai-field-compiled_contract` | `pass` | openai adapter includes field: compiled_contract |
+| `openai-field-permission_contract` | `pass` | openai adapter includes field: permission_contract |
+| `openai-field-target_permission_contract` | `pass` | openai adapter includes field: target_permission_contract |
+| `openai-field-target_native_contract` | `pass` | openai adapter includes field: target_native_contract |
+| `openai-field-target_transform` | `pass` | openai adapter includes field: target_transform |
+| `openai-field-canonical_metadata` | `pass` | openai adapter includes field: canonical_metadata |
+| `openai-field-canonical_format` | `pass` | openai adapter includes field: canonical_format |
+| `openai-field-activation_mode` | `pass` | openai adapter includes field: activation_mode |
+| `openai-field-execution_context` | `pass` | openai adapter includes field: execution_context |
+| `openai-field-shell` | `pass` | openai adapter includes field: shell |
+| `openai-field-trust_level` | `pass` | openai adapter includes field: trust_level |
+| `openai-field-remote_inline_execution` | `pass` | openai adapter includes field: remote_inline_execution |
+| `openai-field-degradation_strategy` | `pass` | openai adapter includes field: degradation_strategy |
+| `openai-field-portability_profile` | `pass` | openai adapter includes field: portability_profile |
+| `claude-adapter` | `pass` | Adapter exists for target: claude |
+| `claude-field-name` | `pass` | claude adapter includes field: name |
+| `claude-field-description` | `pass` | claude adapter includes field: description |
+| `claude-field-version` | `pass` | claude adapter includes field: version |
+| `claude-field-display_name` | `pass` | claude adapter includes field: display_name |
+| `claude-field-short_description` | `pass` | claude adapter includes field: short_description |
+| `claude-field-default_prompt` | `pass` | claude adapter includes field: default_prompt |
+| `claude-field-job_to_be_done` | `pass` | claude adapter includes field: job_to_be_done |
+| `claude-field-ir_source` | `pass` | claude adapter includes field: ir_source |
+| `claude-field-ir_schema_version` | `pass` | claude adapter includes field: ir_schema_version |
+| `claude-field-semantic_contract` | `pass` | claude adapter includes field: semantic_contract |
+| `claude-field-semantic_parity` | `pass` | claude adapter includes field: semantic_parity |
+| `claude-field-compiler` | `pass` | claude adapter includes field: compiler |
+| `claude-field-compiled_contract` | `pass` | claude adapter includes field: compiled_contract |
+| `claude-field-permission_contract` | `pass` | claude adapter includes field: permission_contract |
+| `claude-field-target_permission_contract` | `pass` | claude adapter includes field: target_permission_contract |
+| `claude-field-target_native_contract` | `pass` | claude adapter includes field: target_native_contract |
+| `claude-field-target_transform` | `pass` | claude adapter includes field: target_transform |
+| `claude-field-canonical_metadata` | `pass` | claude adapter includes field: canonical_metadata |
+| `claude-field-canonical_format` | `pass` | claude adapter includes field: canonical_format |
+| `claude-field-activation_mode` | `pass` | claude adapter includes field: activation_mode |
+| `claude-field-execution_context` | `pass` | claude adapter includes field: execution_context |
+| `claude-field-shell` | `pass` | claude adapter includes field: shell |
+| `claude-field-trust_level` | `pass` | claude adapter includes field: trust_level |
+| `claude-field-remote_inline_execution` | `pass` | claude adapter includes field: remote_inline_execution |
+| `claude-field-degradation_strategy` | `pass` | claude adapter includes field: degradation_strategy |
+| `claude-field-portability_profile` | `pass` | claude adapter includes field: portability_profile |
+| `generic-adapter` | `pass` | Adapter exists for target: generic |
+| `generic-field-name` | `pass` | generic adapter includes field: name |
+| `generic-field-description` | `pass` | generic adapter includes field: description |
+| `generic-field-version` | `pass` | generic adapter includes field: version |
+| `generic-field-display_name` | `pass` | generic adapter includes field: display_name |
+| `generic-field-short_description` | `pass` | generic adapter includes field: short_description |
+| `generic-field-default_prompt` | `pass` | generic adapter includes field: default_prompt |
+| `generic-field-job_to_be_done` | `pass` | generic adapter includes field: job_to_be_done |
+| `generic-field-ir_source` | `pass` | generic adapter includes field: ir_source |
+| `generic-field-ir_schema_version` | `pass` | generic adapter includes field: ir_schema_version |
+| `generic-field-semantic_contract` | `pass` | generic adapter includes field: semantic_contract |
+| `generic-field-semantic_parity` | `pass` | generic adapter includes field: semantic_parity |
+| `generic-field-compiler` | `pass` | generic adapter includes field: compiler |
+| `generic-field-compiled_contract` | `pass` | generic adapter includes field: compiled_contract |
+| `generic-field-permission_contract` | `pass` | generic adapter includes field: permission_contract |
+| `generic-field-target_permission_contract` | `pass` | generic adapter includes field: target_permission_contract |
+| `generic-field-target_native_contract` | `pass` | generic adapter includes field: target_native_contract |
+| `generic-field-target_transform` | `pass` | generic adapter includes field: target_transform |
+| `generic-field-canonical_metadata` | `pass` | generic adapter includes field: canonical_metadata |
+| `generic-field-canonical_format` | `pass` | generic adapter includes field: canonical_format |
+| `generic-field-activation_mode` | `pass` | generic adapter includes field: activation_mode |
+| `generic-field-execution_context` | `pass` | generic adapter includes field: execution_context |
+| `generic-field-shell` | `pass` | generic adapter includes field: shell |
+| `generic-field-trust_level` | `pass` | generic adapter includes field: trust_level |
+| `generic-field-remote_inline_execution` | `pass` | generic adapter includes field: remote_inline_execution |
+| `generic-field-degradation_strategy` | `pass` | generic adapter includes field: degradation_strategy |
+| `generic-field-portability_profile` | `pass` | generic adapter includes field: portability_profile |
+| `openai-file-targets/openai/adapter.json` | `pass` | Package contains targets/openai/adapter.json |
+| `openai-file-targets/openai/agents/openai.yaml` | `pass` | Package contains targets/openai/agents/openai.yaml |
+| `claude-file-targets/claude/adapter.json` | `pass` | Package contains targets/claude/adapter.json |
+| `claude-file-targets/claude/README.md` | `pass` | Package contains targets/claude/README.md |
+| `generic-file-targets/generic/adapter.json` | `pass` | Package contains targets/generic/adapter.json |
+| `archive-safe-paths` | `pass` | Archive has no absolute or parent-traversal entries |
+| `archive-entry-yao-meta-skill/SKILL.md` | `pass` | Archive contains yao-meta-skill/SKILL.md |
+| `archive-entry-yao-meta-skill/manifest.json` | `pass` | Archive contains yao-meta-skill/manifest.json |
+| `archive-entry-yao-meta-skill/agents/interface.yaml` | `pass` | Archive contains yao-meta-skill/agents/interface.yaml |
+| `archive-excludes-generated` | `pass` | Archive excludes generated dist/ and tests/tmp* contents |
+| `registry-ok` | `pass` | Registry audit is OK |
+| `registry-name-match` | `pass` | Registry package name matches package manifest |
+| `registry-version-match` | `pass` | Registry package version matches package manifest |
+| `registry-compat-openai` | `pass` | Registry compatibility is reviewable for target: openai |
+| `registry-compat-claude` | `pass` | Registry compatibility is reviewable for target: claude |
+| `registry-compat-generic` | `pass` | Registry compatibility is reviewable for target: generic |
+
+## Failures
+
+- None
+
+## Warnings
+
+- None
diff --git a/reports/prompt-quality-profile.json b/reports/prompt-quality-profile.json
index 3c84c0d..8af0544 100644
--- a/reports/prompt-quality-profile.json
+++ b/reports/prompt-quality-profile.json
@@ -2,14 +2,26 @@
"skill_name": "yao-meta-skill",
"relevance": "prompt-heavy",
"primary_task_family": {
- "key": "dialogue_interaction",
- "label": "Dialogue interaction",
+ "key": "execution_operation",
+ "label": "Execution operation",
"matched_keywords": [
- "dialogue",
- "conversation"
+ "workflow",
+ "runbook"
]
},
"task_families": [
+ {
+ "key": "execution_operation",
+ "label": "Execution operation",
+ "score": 2,
+ "matched_keywords": [
+ "workflow",
+ "runbook"
+ ],
+ "role_guidance": "Use an operator role with explicit boundaries, inputs, outputs, and failure handling.",
+ "task_guidance": "Convert the job into ordered steps with validation checks and stop conditions.",
+ "format_guidance": "Return a runbook-like handoff with commands, checks, owners, and next actions when relevant."
+ },
{
"key": "dialogue_interaction",
"label": "Dialogue interaction",
@@ -23,15 +35,15 @@
"format_guidance": "Return concise prompts, decision points, and reviewer-visible assumptions."
},
{
- "key": "execution_operation",
- "label": "Execution operation",
+ "key": "creative_generation",
+ "label": "Creative generation",
"score": 1,
"matched_keywords": [
- "workflow"
+ "content"
],
- "role_guidance": "Use an operator role with explicit boundaries, inputs, outputs, and failure handling.",
- "task_guidance": "Convert the job into ordered steps with validation checks and stop conditions.",
- "format_guidance": "Return a runbook-like handoff with commands, checks, owners, and next actions when relevant."
+ "role_guidance": "Use a taste-aware creator role with clear audience, tone, and originality boundaries.",
+ "task_guidance": "Generate variants, explain selection logic, and preserve the user's distinctive constraints.",
+ "format_guidance": "Return options with rationale, selection criteria, and refinement paths."
},
{
"key": "prompt_engineering",
@@ -46,27 +58,27 @@
}
],
"complexity": {
- "band": "complex",
- "score": 5,
- "reason": "multiple inputs, constraints, or task families require tradeoff handling"
+ "band": "expert",
+ "score": 27,
+ "reason": "multiple task families plus governance, evaluation, or expert-level constraints"
},
"need_model": {
- "explicit_need": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "explicit_need": "Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.",
"implicit_need": "The reusable skill needs a stable role, task, and output contract rather than a one-off prompt.",
- "scenario": "not yet explicit",
+ "scenario": "rough workflow notes, SOPs, runbooks, prompts, transcripts, documents, or repeated task descriptions, an existing skill directory that needs refactor, evaluation, packaging, or governance hardening, target platform requirements such as OpenAI, Claude, generic Agent Skills, or team distribution, benchmark references, local constraints, desired maturity tier, and review standards",
"user_level": "infer from examples and standards; ask only if it changes output depth",
- "success_standard": "usable output with clear validation cues"
+ "success_standard": "trigger boundaries must be tested with should-trigger and should-not-trigger cases, production and higher maturity work needs output eval, trust, runtime conformance, and Review Studio evidence, governed work needs owner, review cadence, permission approvals, registry metadata, package verification, and install simulation, generated reports should be bilingual or reviewer-friendly when they are user-facing, each new asset must earn its place by reducing ambiguity, risk, or repeated work"
},
"rtf_to_skill": {
- "role": "Use a conversational role that asks only high-leverage questions and remembers the user's goal.",
- "task": "Clarify intent, resolve uncertainty, and converge toward a recommendation instead of a long option list.",
- "format": "Return concise prompts, decision points, and reviewer-visible assumptions."
+ "role": "Use an operator role with explicit boundaries, inputs, outputs, and failure handling.",
+ "task": "Convert the job into ordered steps with validation checks and stop conditions.",
+ "format": "Return a runbook-like handoff with commands, checks, owners, and next actions when relevant."
},
"quality_matrix": [
{
"key": "completeness",
"label": "Completeness",
- "score": 80,
+ "score": 100,
"matched_signals": [
"output",
"constraint",
@@ -77,8 +89,10 @@
{
"key": "clarity",
"label": "Clarity",
- "score": 80,
- "matched_signals": [],
+ "score": 85,
+ "matched_signals": [
+ "clear"
+ ],
"repair": "Replace broad verbs with observable actions and define what done means."
},
{
@@ -104,12 +118,12 @@
{
"key": "specificity",
"label": "Specificity",
- "score": 70,
+ "score": 80,
"matched_signals": [],
"repair": "Anchor wording in the user's audience, domain nouns, and target outcome."
}
],
- "overall_quality_score": 82.0,
+ "overall_quality_score": 89.0,
"self_repair_checks": [
"Check explicit need, implicit need, scenario, user level, and success standard before deepening.",
"Map Role, Task, and Format into skill behavior, not decorative prompt labels.",
diff --git a/reports/prompt-quality-profile.md b/reports/prompt-quality-profile.md
index 1e9579b..a061130 100644
--- a/reports/prompt-quality-profile.md
+++ b/reports/prompt-quality-profile.md
@@ -2,41 +2,41 @@
Skill: `yao-meta-skill`
Relevance: `prompt-heavy`
-Overall quality score: `82.0/100`
+Overall quality score: `89.0/100`
## Primary Task Family
-**Dialogue interaction**
-- Matched keywords: dialogue, conversation
+**Execution operation**
+- Matched keywords: workflow, runbook
## Complexity
-- Band: `complex`
-- Score: `5`
-- Reason: multiple inputs, constraints, or task families require tradeoff handling
+- Band: `expert`
+- Score: `27`
+- Reason: multiple task families plus governance, evaluation, or expert-level constraints
## Need Model
-- Explicit Need: Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
+- Explicit Need: Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse.
- Implicit Need: The reusable skill needs a stable role, task, and output contract rather than a one-off prompt.
-- Scenario: not yet explicit
+- Scenario: rough workflow notes, SOPs, runbooks, prompts, transcripts, documents, or repeated task descriptions, an existing skill directory that needs refactor, evaluation, packaging, or governance hardening, target platform requirements such as OpenAI, Claude, generic Agent Skills, or team distribution, benchmark references, local constraints, desired maturity tier, and review standards
- User Level: infer from examples and standards; ask only if it changes output depth
-- Success Standard: usable output with clear validation cues
+- Success Standard: trigger boundaries must be tested with should-trigger and should-not-trigger cases, production and higher maturity work needs output eval, trust, runtime conformance, and Review Studio evidence, governed work needs owner, review cadence, permission approvals, registry metadata, package verification, and install simulation, generated reports should be bilingual or reviewer-friendly when they are user-facing, each new asset must earn its place by reducing ambiguity, risk, or repeated work
## RTF To Skill Mapping
-- Role: Use a conversational role that asks only high-leverage questions and remembers the user's goal.
-- Task: Clarify intent, resolve uncertainty, and converge toward a recommendation instead of a long option list.
-- Format: Return concise prompts, decision points, and reviewer-visible assumptions.
+- Role: Use an operator role with explicit boundaries, inputs, outputs, and failure handling.
+- Task: Convert the job into ordered steps with validation checks and stop conditions.
+- Format: Return a runbook-like handoff with commands, checks, owners, and next actions when relevant.
## Quality Matrix
-### Completeness — 80/100
+### Completeness — 100/100
- Matched signals: output, constraint, standard
- Repair: Name missing inputs, outputs, constraints, or success standards before deepening the package.
-### Clarity — 80/100
-- Matched signals: none
+### Clarity — 85/100
+- Matched signals: clear
- Repair: Replace broad verbs with observable actions and define what done means.
### Consistency — 90/100
@@ -47,12 +47,19 @@ Overall quality score: `82.0/100`
- Matched signals: use, workflow
- Repair: Add runnable steps, examples, or verification cues instead of abstract advice.
-### Specificity — 70/100
+### Specificity — 80/100
- Matched signals: none
- Repair: Anchor wording in the user's audience, domain nouns, and target outcome.
## Matched Task Families
+### Execution operation
+- Score: `2`
+- Keywords: workflow, runbook
+- Role: Use an operator role with explicit boundaries, inputs, outputs, and failure handling.
+- Task: Convert the job into ordered steps with validation checks and stop conditions.
+- Format: Return a runbook-like handoff with commands, checks, owners, and next actions when relevant.
+
### Dialogue interaction
- Score: `2`
- Keywords: dialogue, conversation
@@ -60,12 +67,12 @@ Overall quality score: `82.0/100`
- Task: Clarify intent, resolve uncertainty, and converge toward a recommendation instead of a long option list.
- Format: Return concise prompts, decision points, and reviewer-visible assumptions.
-### Execution operation
+### Creative generation
- Score: `1`
-- Keywords: workflow
-- Role: Use an operator role with explicit boundaries, inputs, outputs, and failure handling.
-- Task: Convert the job into ordered steps with validation checks and stop conditions.
-- Format: Return a runbook-like handoff with commands, checks, owners, and next actions when relevant.
+- Keywords: content
+- Role: Use a taste-aware creator role with clear audience, tone, and originality boundaries.
+- Task: Generate variants, explain selection logic, and preserve the user's distinctive constraints.
+- Format: Return options with rationale, selection criteria, and refinement paths.
### Prompt engineering
- Score: `1`
diff --git a/reports/reference-synthesis.json b/reports/reference-synthesis.json
index 03d6dad..a6141d2 100644
--- a/reports/reference-synthesis.json
+++ b/reports/reference-synthesis.json
@@ -2,9 +2,9 @@
"skill_name": "yao-meta-skill",
"description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
"intent_confidence": {
- "score": 30,
- "band": "low",
- "gate_passed": false
+ "score": 100,
+ "band": "high",
+ "gate_passed": true
},
"github_benchmarks": [
{
@@ -38,49 +38,51 @@
"source_tracks": [
{
"source_type": "official",
- "name": "Official workflow product ergonomics",
+ "name": "Official skill anatomy and context discipline",
"evidence_mode": "curated-pattern-track",
"matched_keywords": [
- "workflow"
+ "metadata",
+ "references"
],
- "borrow": "Borrow a first-time operator flow that explains itself before it asks for more structure.",
- "avoid": "Do not mimic product polish that adds UI bulk without improving clarity.",
- "why_relevant": "This track matches: workflow."
+ "borrow": "Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts.",
+ "avoid": "Do not let packaging or platform concerns swallow the core job boundary.",
+ "why_relevant": "This track matches: metadata, references."
},
{
"source_type": "research",
- "name": "Hypothesis-test-learn loop",
+ "name": "Human-in-the-loop verification",
"evidence_mode": "curated-pattern-track",
"matched_keywords": [
- "general fit"
+ "review",
+ "govern"
],
- "borrow": "Borrow a small hypothesis-test-learn loop so the first revision is evidence-backed.",
- "avoid": "Do not create experimental overhead that exceeds the skill's real risk tier.",
- "why_relevant": "This track matches: general fit."
+ "borrow": "Borrow a review checkpoint wherever trust matters more than raw speed.",
+ "avoid": "Do not force every skill through heavyweight review when the risk is low.",
+ "why_relevant": "This track matches: review, govern."
},
{
"source_type": "principles",
"name": "Boundary-first design",
"evidence_mode": "curated-pattern-track",
"matched_keywords": [
- "general fit"
+ "route"
],
"borrow": "Borrow the discipline of defining what the skill should not own before growing the package.",
"avoid": "Do not expand execution assets until route boundaries stay clean.",
- "why_relevant": "This track matches: general fit."
+ "why_relevant": "This track matches: route."
}
],
"synthesis": {
"borrow_now": [
- "Borrow a first-time operator flow that explains itself before it asks for more structure.",
- "Borrow a small hypothesis-test-learn loop so the first revision is evidence-backed.",
+ "Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts.",
+ "Borrow a review checkpoint wherever trust matters more than raw speed.",
"Borrow the discipline of defining what the skill should not own before growing the package.",
"Borrow the way it turns a messy workflow into a repeatable operating path.",
"Borrow the clear execution entrypoints and command structure."
],
"avoid_now": [
- "Do not mimic product polish that adds UI bulk without improving clarity.",
- "Do not create experimental overhead that exceeds the skill's real risk tier.",
+ "Do not let packaging or platform concerns swallow the core job boundary.",
+ "Do not force every skill through heavyweight review when the risk is low.",
"Do not expand execution assets until route boundaries stay clean.",
"Do not import process overhead that only exists for that project's scale.",
"Do not copy repo-specific commands or environment assumptions verbatim."
@@ -96,10 +98,50 @@
"source_count": 6,
"accepted": [
{
- "name": "Official workflow product ergonomics",
+ "name": "Official skill anatomy and context discipline",
"source_type": "official",
- "borrow": "Borrow a first-time operator flow that explains itself before it asks for more structure.",
- "avoid": "Do not mimic product polish that adds UI bulk without improving clarity.",
+ "borrow": "Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts.",
+ "avoid": "Do not let packaging or platform concerns swallow the core job boundary.",
+ "gates": {
+ "recurrence": true,
+ "generativity": true,
+ "distinctiveness": true,
+ "boundary": true
+ },
+ "passed": [
+ "recurrence",
+ "generativity",
+ "distinctiveness",
+ "boundary"
+ ],
+ "missing": [],
+ "score": 4
+ },
+ {
+ "name": "Human-in-the-loop verification",
+ "source_type": "research",
+ "borrow": "Borrow a review checkpoint wherever trust matters more than raw speed.",
+ "avoid": "Do not force every skill through heavyweight review when the risk is low.",
+ "gates": {
+ "recurrence": true,
+ "generativity": true,
+ "distinctiveness": true,
+ "boundary": true
+ },
+ "passed": [
+ "recurrence",
+ "generativity",
+ "distinctiveness",
+ "boundary"
+ ],
+ "missing": [],
+ "score": 4
+ },
+ {
+ "name": "Boundary-first design",
+ "source_type": "principles",
+ "borrow": "Borrow the discipline of defining what the skill should not own before growing the package.",
+ "avoid": "Do not expand execution assets until route boundaries stay clean.",
"gates": {
"recurrence": true,
"generativity": true,
@@ -157,48 +199,6 @@
}
],
"deferred": [
- {
- "name": "Hypothesis-test-learn loop",
- "source_type": "research",
- "borrow": "Borrow a small hypothesis-test-learn loop so the first revision is evidence-backed.",
- "avoid": "Do not create experimental overhead that exceeds the skill's real risk tier.",
- "gates": {
- "recurrence": true,
- "generativity": true,
- "distinctiveness": false,
- "boundary": true
- },
- "passed": [
- "recurrence",
- "generativity",
- "boundary"
- ],
- "missing": [
- "distinctiveness"
- ],
- "score": 3
- },
- {
- "name": "Boundary-first design",
- "source_type": "principles",
- "borrow": "Borrow the discipline of defining what the skill should not own before growing the package.",
- "avoid": "Do not expand execution assets until route boundaries stay clean.",
- "gates": {
- "recurrence": true,
- "generativity": true,
- "distinctiveness": false,
- "boundary": true
- },
- "passed": [
- "recurrence",
- "generativity",
- "boundary"
- ],
- "missing": [
- "distinctiveness"
- ],
- "score": 3
- },
{
"name": "multica-ai/andrej-karpathy-skills",
"source_type": "github",
@@ -221,27 +221,34 @@
"score": 3
}
],
- "summary": "3 accepted, 3 deferred using threshold 4/4."
+ "summary": "5 accepted, 1 deferred using threshold 4/4."
},
- "conflicts": [],
+ "conflicts": [
+ {
+ "key": "lightweight_vs_governance",
+ "summary": "The stated preference leans lightweight or speed-first, while the benchmark mix leans toward governance, review, or heavier evaluation structure.",
+ "user_preference": "lightweight or speed-first",
+ "benchmark_pressure": "governance or evaluation-heavy patterns"
+ }
+ ],
"recommendation": {
- "summary": "Start by borrowing this pattern: Borrow a first-time operator flow that explains itself before it asks for more structure. Avoid this for the first pass: Do not mimic product polish that adds UI bulk without improving clarity.",
+ "summary": "Start by borrowing this pattern: Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts. Avoid this for the first pass: Do not let packaging or platform concerns swallow the core job boundary.",
"borrow_now": [
- "Borrow a first-time operator flow that explains itself before it asks for more structure.",
- "Borrow a small hypothesis-test-learn loop so the first revision is evidence-backed."
+ "Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts.",
+ "Borrow a review checkpoint wherever trust matters more than raw speed."
],
"avoid_for_now": [
- "Do not mimic product polish that adds UI bulk without improving clarity.",
- "Do not create experimental overhead that exceeds the skill's real risk tier."
+ "Do not let packaging or platform concerns swallow the core job boundary.",
+ "Do not force every skill through heavyweight review when the risk is low."
],
- "why": "Intent still has gaps, so the system should surface the recommendation and ask for correction before deepening the package.",
+ "why": "There is a real design conflict to resolve: The stated preference leans lightweight or speed-first, while the benchmark mix leans toward governance, review, or heavier evaluation structure.",
"user_decision_required": true
},
"visibility": {
"mode": "explicit",
"user_decision_required": true,
"reasons": [
- "intent_uncertain"
+ "design_conflict"
],
"user_note": "Surface the recommendation because intent is still settling or there is a real design conflict that needs a user call.",
"reviewer_note": "Keep the full benchmark and synthesis evidence visible for authors and reviewers."
diff --git a/reports/reference-synthesis.md b/reports/reference-synthesis.md
index 8ade5ff..77adb18 100644
--- a/reports/reference-synthesis.md
+++ b/reports/reference-synthesis.md
@@ -2,7 +2,7 @@
Skill: `yao-meta-skill`
- Description: Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
-- Intent confidence: `30/100` (`low`)
+- Intent confidence: `100/100` (`high`)
## Live GitHub Benchmarks
@@ -26,72 +26,72 @@ Skill: `yao-meta-skill`
## Curated World-Class Pattern Tracks
-### Official workflow product ergonomics
+### Official skill anatomy and context discipline
- Type: `official`
- Evidence mode: `curated-pattern-track`
-- Why relevant: This track matches: workflow.
-- Borrow: Borrow a first-time operator flow that explains itself before it asks for more structure.
-- Avoid: Do not mimic product polish that adds UI bulk without improving clarity.
+- Why relevant: This track matches: metadata, references.
+- Borrow: Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts.
+- Avoid: Do not let packaging or platform concerns swallow the core job boundary.
-### Hypothesis-test-learn loop
+### Human-in-the-loop verification
- Type: `research`
- Evidence mode: `curated-pattern-track`
-- Why relevant: This track matches: general fit.
-- Borrow: Borrow a small hypothesis-test-learn loop so the first revision is evidence-backed.
-- Avoid: Do not create experimental overhead that exceeds the skill's real risk tier.
+- Why relevant: This track matches: review, govern.
+- Borrow: Borrow a review checkpoint wherever trust matters more than raw speed.
+- Avoid: Do not force every skill through heavyweight review when the risk is low.
### Boundary-first design
- Type: `principles`
- Evidence mode: `curated-pattern-track`
-- Why relevant: This track matches: general fit.
+- Why relevant: This track matches: route.
- Borrow: Borrow the discipline of defining what the skill should not own before growing the package.
- Avoid: Do not expand execution assets until route boundaries stay clean.
## Borrow Now
-- Borrow a first-time operator flow that explains itself before it asks for more structure.
-- Borrow a small hypothesis-test-learn loop so the first revision is evidence-backed.
+- Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts.
+- Borrow a review checkpoint wherever trust matters more than raw speed.
- Borrow the discipline of defining what the skill should not own before growing the package.
- Borrow the way it turns a messy workflow into a repeatable operating path.
- Borrow the clear execution entrypoints and command structure.
## Avoid Now
-- Do not mimic product polish that adds UI bulk without improving clarity.
-- Do not create experimental overhead that exceeds the skill's real risk tier.
+- Do not let packaging or platform concerns swallow the core job boundary.
+- Do not force every skill through heavyweight review when the risk is low.
- Do not expand execution assets until route boundaries stay clean.
- Do not import process overhead that only exists for that project's scale.
- Do not copy repo-specific commands or environment assumptions verbatim.
## Pattern Gate
-- Summary: 3 accepted, 3 deferred using threshold 4/4.
+- Summary: 5 accepted, 1 deferred using threshold 4/4.
- Acceptance threshold: `4/4`
- Accepted patterns:
- - **Official workflow product ergonomics**: 4/4 (recurrence, generativity, distinctiveness, boundary)
+ - **Official skill anatomy and context discipline**: 4/4 (recurrence, generativity, distinctiveness, boundary)
+ - **Human-in-the-loop verification**: 4/4 (recurrence, generativity, distinctiveness, boundary)
+ - **Boundary-first design**: 4/4 (recurrence, generativity, distinctiveness, boundary)
- **obra/superpowers**: 4/4 (recurrence, generativity, distinctiveness, boundary)
- **affaan-m/ECC**: 4/4 (recurrence, generativity, distinctiveness, boundary)
- Deferred patterns:
- - **Hypothesis-test-learn loop**: missing distinctiveness
- - **Boundary-first design**: missing distinctiveness
- **multica-ai/andrej-karpathy-skills**: missing generativity
## Default Recommendation
-- Summary: Start by borrowing this pattern: Borrow a first-time operator flow that explains itself before it asks for more structure. Avoid this for the first pass: Do not mimic product polish that adds UI bulk without improving clarity.
-- Why: Intent still has gaps, so the system should surface the recommendation and ask for correction before deepening the package.
+- Summary: Start by borrowing this pattern: Borrow progressive disclosure: keep the entrypoint lean and move depth into references or scripts. Avoid this for the first pass: Do not let packaging or platform concerns swallow the core job boundary.
+- Why: There is a real design conflict to resolve: The stated preference leans lightweight or speed-first, while the benchmark mix leans toward governance, review, or heavier evaluation structure.
- User decision required: `True`
## Visibility Mode
- Mode: `explicit`
-- Reasons: intent_uncertain
+- Reasons: design_conflict
- User note: Surface the recommendation because intent is still settling or there is a real design conflict that needs a user call.
- Reviewer note: Keep the full benchmark and synthesis evidence visible for authors and reviewers.
## Conflict Check
-- No material design conflict detected. Keep the synthesis silent for the user.
+- **lightweight_vs_governance**: The stated preference leans lightweight or speed-first, while the benchmark mix leans toward governance, review, or heavier evaluation structure.
## Quality Lift Thesis
diff --git a/reports/registry_audit.json b/reports/registry_audit.json
new file mode 100644
index 0000000..6f6525d
--- /dev/null
+++ b/reports/registry_audit.json
@@ -0,0 +1,91 @@
+{
+ "ok": true,
+ "schema_version": "2.0",
+ "skill_dir": ".",
+ "registry_dir": "registry",
+ "package": {
+ "schema_version": "2.0",
+ "name": "yao-meta-skill",
+ "version": "1.1.0",
+ "description": "Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.",
+ "targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ],
+ "maturity": "governed",
+ "owner": "Yao Team",
+ "review_cadence": "quarterly",
+ "trust_level": "local",
+ "license": "MIT",
+ "checksums": {
+ "package_sha256": "9f1d53dbaeb1c90c80d7ffbbc1d10473e50b8032acda68332fbae551bb246abe",
+ "archive_sha256": "4d1227dc0996a97aa4987761d46081391fe15b36362e19765e1e7aa8e5d41c06"
+ },
+ "compatibility": {
+ "openai": "pass",
+ "claude": "pass",
+ "agent-skills": "pass",
+ "vscode": "pass",
+ "generic": "pass",
+ "agent-skills-compatible": "pass"
+ },
+ "source": {
+ "skill_dir": ".",
+ "skill_ir": "skill-ir/examples/yao-meta-skill.json",
+ "ir_schema_version": "2.0.0",
+ "canonical_metadata": "agents/interface.yaml"
+ },
+ "artifacts": {
+ "overview_html": "reports/skill-overview.html",
+ "review_studio_html": "reports/review-studio.html",
+ "trust_report": "reports/security_trust_report.md",
+ "conformance_matrix": "reports/conformance_matrix.md",
+ "compiled_targets": "reports/compiled_targets.md",
+ "package_verification": "reports/package_verification.md",
+ "install_simulation": "reports/install_simulation.md",
+ "adoption_drift": "reports/adoption_drift_report.md",
+ "review_waivers": "reports/review_waivers.md",
+ "review_annotations": "reports/review_annotations.md",
+ "package_metadata": "registry/packages/yao-meta-skill.json"
+ },
+ "distribution": {
+ "archive_verified": true,
+ "archive_sha256": "4d1227dc0996a97aa4987761d46081391fe15b36362e19765e1e7aa8e5d41c06",
+ "package_verification": "reports/package_verification.json",
+ "install_simulated": true,
+ "install_simulation": "reports/install_simulation.json"
+ },
+ "generated_at": "2026-06-13"
+ },
+ "index": {
+ "schema_version": "2.0",
+ "generated_at": "2026-06-13",
+ "package_count": 1,
+ "packages": [
+ {
+ "name": "yao-meta-skill",
+ "version": "1.1.0",
+ "maturity": "governed",
+ "owner": "Yao Team",
+ "targets": [
+ "openai",
+ "claude",
+ "generic",
+ "agent-skills-compatible"
+ ],
+ "package_metadata": "registry/packages/yao-meta-skill.json",
+ "package_sha256": "9f1d53dbaeb1c90c80d7ffbbc1d10473e50b8032acda68332fbae551bb246abe"
+ }
+ ]
+ },
+ "failures": [],
+ "warnings": [],
+ "artifacts": {
+ "index": "registry/index.json",
+ "package": "registry/packages/yao-meta-skill.json",
+ "json": "reports/registry_audit.json",
+ "markdown": "reports/registry_audit.md"
+ }
+}
diff --git a/reports/registry_audit.md b/reports/registry_audit.md
new file mode 100644
index 0000000..6468aa9
--- /dev/null
+++ b/reports/registry_audit.md
@@ -0,0 +1,37 @@
+# Registry Audit
+
+- OK: `True`
+- Package: `yao-meta-skill`
+- Version: `1.1.0`
+- Maturity: `governed`
+- Owner: `Yao Team`
+- License: `MIT`
+- Package SHA256: `9f1d53dbaeb1c90c80d7ffbbc1d10473e50b8032acda68332fbae551bb246abe`
+- Archive SHA256: `4d1227dc0996a97aa4987761d46081391fe15b36362e19765e1e7aa8e5d41c06`
+- Install simulated: `True`
+
+## Compatibility
+
+| Target | Status |
+| --- | --- |
+| `openai` | `pass` |
+| `claude` | `pass` |
+| `agent-skills` | `pass` |
+| `vscode` | `pass` |
+| `generic` | `pass` |
+| `agent-skills-compatible` | `pass` |
+
+## Failures
+
+- None
+
+## Warnings
+
+- None
+
+## Artifacts
+
+- index: `registry/index.json`
+- package: `registry/packages/yao-meta-skill.json`
+- json: `reports/registry_audit.json`
+- markdown: `reports/registry_audit.md`
diff --git a/reports/review-studio.html b/reports/review-studio.html
index 20c8194..15be5d2 100644
--- a/reports/review-studio.html
+++ b/reports/review-studio.html
@@ -116,8 +116,89 @@
gap: 3px;
}
.muted { color: var(--muted); }
+ .actions-grid {
+ display: grid;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 16px;
+ }
+ .annotations-grid {
+ display: grid;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ gap: 16px;
+ }
+ .action-card {
+ border: 1px solid var(--line);
+ border-radius: 8px;
+ padding: 18px;
+ background: #fff;
+ display: grid;
+ gap: 10px;
+ min-width: 0;
+ }
+ .action-card.warn { border-left: 4px solid var(--warn); }
+ .action-card.block { border-left: 4px solid var(--block); }
+ .annotation-card {
+ border: 1px solid var(--line);
+ border-radius: 8px;
+ padding: 18px;
+ background: #fff;
+ display: grid;
+ gap: 10px;
+ min-width: 0;
+ }
+ .annotation-card.warning { border-left: 4px solid var(--warn); }
+ .annotation-card.blocker { border-left: 4px solid var(--block); }
+ .annotation-card.resolved { opacity: .72; }
+ .action-card span,
+ .annotation-card span,
+ .action-card small,
+ .annotation-card small,
+ .action-card footer,
+ .annotation-card footer,
+ .action-card dd {
+ color: var(--muted);
+ font-size: 14px;
+ overflow-wrap: anywhere;
+ }
+ .annotation-card dd { color: var(--muted); font-size: 14px; overflow-wrap: anywhere; }
+ .action-card dl, .annotation-card dl {
+ display: grid;
+ grid-template-columns: 80px minmax(0, 1fr);
+ gap: 6px 10px;
+ margin: 0;
+ }
+ .action-card dt, .annotation-card dt { color: var(--ink); font-size: 14px; }
+ .action-card dd, .annotation-card dd { margin: 0; }
+ .source-ref-list {
+ list-style: none;
+ padding: 0;
+ margin: 0;
+ display: grid;
+ gap: 6px;
+ }
+ .source-ref-list li {
+ display: grid;
+ gap: 2px;
+ min-width: 0;
+ padding: 8px 0 0;
+ border-top: 1px solid var(--line);
+ }
+ .source-ref-list a,
+ .source-ref-list span {
+ overflow-wrap: anywhere;
+ font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+ font-size: 13px;
+ }
+ .source-ref-list small {
+ font-size: 12px;
+ color: var(--muted);
+ }
+ code {
+ font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+ font-size: 13px;
+ }
@media (max-width: 980px) {
- .metrics, .gates, .twocol { grid-template-columns: 1fr; }
+ .metrics, .gates, .twocol, .actions-grid, .annotations-grid { grid-template-columns: 1fr; }
main { padding: 32px 18px 60px; }
nav { justify-content: flex-start; overflow-x: auto; flex-wrap: nowrap; }
nav a { flex: 0 0 auto; }
@@ -125,7 +206,7 @@
-
+
Review Studio 2.0
@@ -133,65 +214,121 @@
Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
组合治理12 skills; 5 route collisions; 9 owner gaps; 10 stale
+
关注事项
无。
+
+
修复动作
+
当前没有 blocker 或 warning。保持现有证据链即可。
+
+
+
+
审查批注
+
当前批注:0 条批注;开放 0;阻断 0
+
当前没有 reviewer 批注。
+
+
意图画布
-
Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
+
Turn repeated workflows, prompts, transcripts, runbooks, documents, or existing skill packages into routeable, evaluable, packageable, and governable agent skills for personal, team, library, or governed reuse. Primary output: A working skill package with lean SKILL.md, aligned agents/interface.yaml, justified references, scripts only when useful, eval evidence, reports, packaging metadata, and clear next iteration recommendations.. Exclusions: one-off writing, translation, explanation, or brainstorming requests that do not need a reusable skill, general code review or debugging unless the user is packaging that workflow as a skill, raw private material that was not intentionally supplied as skill evidence, platform-specific plugin creation when the request is not about an agent skill package.
从工作流、提示词、对话记录、文档或笔记中创建、重构、评估和打包 agent skill;适用于新建 Skill、沉淀重复流程、改进现有 Skill、补充 eval 或团队复用打包。Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
从工作流、提示词、对话记录、文档或笔记中创建、重构、评估和打包 agent skill;适用于新建 Skill、沉淀重复流程、改进现有 Skill、补充 eval 或团队复用打包。Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
先看雷达图判断能力短板,再看下方每项分数的证据原因。分数不是装饰数字,必须和本地文件、reports 证据或证据不足提示对应。Read the radar first for weak spots, then inspect each score with its evidence. Scores must map to local files, reports, or explicit evidence gaps.
该 Skill 的触发描述来自 SKILL.md frontmatter;默认中文报告先呈现能力边界,原始英文描述可切换到英文查看。Create, refactor, evaluate, and package agent skills from workflows, prompts, transcripts, docs, or notes. Use when asked to create a skill, turn a repeated process into a reusable skill, improve an existing skill, add evals, or package a skill for team reuse.
原始说明可切换到英文查看;默认中文报告保留结论与结构说明。A working skill package with lean SKILL.md, aligned agents/interface.yaml, justified references, scripts only when useful, eval evidence, reports, packaging metadata, and clear next iteration recommendations.
All scanned skills remain visible: {summary['route_collision_count']} total route collisions, {summary['owner_gap_count']} total owner gaps, and {summary['stale_count']} total stale signals.
+
Catalog
-
Name
Path
Owner
Maturity
Review
+
Name
Path
Owner
Maturity
Review
Scope
{''.join(rows)}
@@ -366,20 +453,32 @@ def render_html(payload: dict[str, Any]) -> str:
def build_atlas(workspace_root: Path, output_dir: Path, report_html: Path, report_json: Path, threshold: float, today: date) -> dict[str, Any]:
workspace_root = workspace_root.resolve()
+ scope_policy = load_scope_policy(workspace_root)
skill_dirs = find_skill_dirs(workspace_root)
- skills = [collect_skill(workspace_root, skill_dir) for skill_dir in skill_dirs]
+ skills = [collect_skill(workspace_root, skill_dir, scope_policy) for skill_dir in skill_dirs]
overlap_rows, collisions = route_overlap(skills, threshold)
graph = dependency_graph(skills)
stale = stale_skills(skills, today)
owner_gaps = owner_review_gaps(skills)
opportunities = no_route_opportunities(workspace_root)
+ actionable_skills = [skill for skill in skills if skill.get("actionable")]
+ actionable_collisions = [item for item in collisions if item.get("actionable")]
+ actionable_stale = [item for item in stale if item.get("actionable")]
+ actionable_owner_gaps = [item for item in owner_gaps if item.get("actionable")]
summary = {
"skill_count": len(skills),
+ "actionable_skill_count": len(actionable_skills),
"route_collision_count": len(collisions),
+ "actionable_route_collision_count": len(actionable_collisions),
"owner_gap_count": len(owner_gaps),
+ "actionable_owner_gap_count": len(actionable_owner_gaps),
"stale_count": len(stale),
+ "actionable_stale_count": len(actionable_stale),
"shared_resource_count": len(graph["shared_resources"]),
"no_route_opportunity_count": len(opportunities),
+ "non_actionable_issue_count": (len(collisions) - len(actionable_collisions))
+ + (len(owner_gaps) - len(actionable_owner_gaps))
+ + (len(stale) - len(actionable_stale)),
}
catalog = {
"workspace_root": display_path(workspace_root),
@@ -391,11 +490,15 @@ def build_atlas(workspace_root: Path, output_dir: Path, report_html: Path, repor
"ok": True,
"workspace_root": display_path(workspace_root),
"summary": summary,
+ "scope_policy": scope_policy,
"catalog": catalog,
"route_collisions": collisions,
+ "actionable_route_collisions": actionable_collisions,
"dependency_graph": graph,
"stale_skills": stale,
+ "actionable_stale_skills": actionable_stale,
"owner_review_gaps": owner_gaps,
+ "actionable_owner_review_gaps": actionable_owner_gaps,
"no_route_opportunities": opportunities,
"artifacts": {
"catalog": display_path(output_dir / "catalog.json"),
diff --git a/scripts/ci_test.py b/scripts/ci_test.py
index d01e1cf..fda84fe 100644
--- a/scripts/ci_test.py
+++ b/scripts/ci_test.py
@@ -34,13 +34,24 @@ DEFAULT_TARGETS = [
"skill-report-metrics-check",
"skill-report-charts-check",
"skill-ir-check",
+ "compiler-check",
"output-eval-check",
+ "output-execution-check",
+ "output-review-adjudication-check",
"runtime-conformance-check",
+ "runtime-permission-check",
"trust-check",
"skill-atlas-check",
+ "registry-audit-check",
+ "package-verify-check",
+ "install-simulation-check",
+ "upgrade-check",
"review-viewer-check",
"review-studio-check",
"feedback-check",
+ "adoption-drift-check",
+ "review-waivers-check",
+ "review-annotations-check",
"baseline-compare-check",
"reference-scan-check",
"github-benchmark-scan-check",
diff --git a/scripts/compile_skill.py b/scripts/compile_skill.py
new file mode 100644
index 0000000..62c5993
--- /dev/null
+++ b/scripts/compile_skill.py
@@ -0,0 +1,726 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+try:
+ import yaml
+except ImportError: # pragma: no cover
+ yaml = None
+
+
+ROOT = Path(__file__).resolve().parent.parent
+COMPILER_SCHEMA_VERSION = "1.0"
+COMPILER_NAME = "yao-skill-ir-compiler"
+
+
+TARGET_TRANSFORMS: dict[str, dict[str, Any]] = {
+ "openai": {
+ "adapter_mode": "metadata-adapter",
+ "generated_files": ["targets/openai/adapter.json", "targets/openai/agents/openai.yaml"],
+ "metadata_mapping": {
+ "display_name": "targets/openai/agents/openai.yaml::interface.display_name",
+ "default_prompt": "targets/openai/agents/openai.yaml::interface.default_prompt",
+ "activation": "targets/openai/agents/openai.yaml::compatibility.activation_mode",
+ "execution": "targets/openai/agents/openai.yaml::compatibility.execution_context",
+ "trust": "targets/openai/agents/openai.yaml::compatibility.trust_level",
+ "permissions": "targets/openai/agents/openai.yaml::compatibility.permission_contract",
+ "degradation": "targets/openai/agents/openai.yaml::compatibility.degradation_strategy",
+ },
+ "preserved_semantics": ["trigger", "workflow-counts", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
+ "unsupported_features": ["client-native script permission prompts are represented as permission contract metadata"],
+ },
+ "claude": {
+ "adapter_mode": "neutral-source-plus-adapter",
+ "generated_files": ["targets/claude/adapter.json", "targets/claude/README.md"],
+ "metadata_mapping": {
+ "display_name": "targets/claude/adapter.json::display_name",
+ "default_prompt": "targets/claude/adapter.json::default_prompt",
+ "activation": "targets/claude/adapter.json::activation_mode",
+ "execution": "targets/claude/adapter.json::execution_context",
+ "trust": "targets/claude/adapter.json::trust_level",
+ "permissions": "targets/claude/adapter.json::target_permission_contract",
+ "degradation": "targets/claude/adapter.json::degradation_strategy",
+ },
+ "preserved_semantics": ["trigger", "workflow-counts", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
+ "unsupported_features": ["vendor-native metadata fields are carried as adapter JSON and README notes"],
+ },
+ "generic": {
+ "adapter_mode": "agent-skills-compatible",
+ "generated_files": ["targets/generic/adapter.json"],
+ "metadata_mapping": {
+ "display_name": "targets/generic/adapter.json::display_name",
+ "default_prompt": "targets/generic/adapter.json::default_prompt",
+ "activation": "targets/generic/adapter.json::activation_mode",
+ "execution": "targets/generic/adapter.json::execution_context",
+ "trust": "targets/generic/adapter.json::trust_level",
+ "permissions": "targets/generic/adapter.json::target_permission_contract",
+ "degradation": "targets/generic/adapter.json::degradation_strategy",
+ },
+ "preserved_semantics": ["trigger", "workflow-counts", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
+ "unsupported_features": [],
+ },
+ "agent-skills-compatible": {
+ "adapter_mode": "neutral-agent-skills-source",
+ "generated_files": ["SKILL.md", "agents/interface.yaml"],
+ "metadata_mapping": {
+ "name": "SKILL.md::frontmatter.name",
+ "description": "SKILL.md::frontmatter.description",
+ "interface": "agents/interface.yaml",
+ "manifest": "manifest.json",
+ },
+ "preserved_semantics": ["trigger", "workflow", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
+ "unsupported_features": [],
+ },
+ "agent-skills": {
+ "adapter_mode": "neutral-agent-skills-source",
+ "generated_files": ["SKILL.md", "agents/interface.yaml"],
+ "metadata_mapping": {
+ "name": "SKILL.md::frontmatter.name",
+ "description": "SKILL.md::frontmatter.description",
+ "interface": "agents/interface.yaml",
+ "manifest": "manifest.json",
+ },
+ "preserved_semantics": ["trigger", "workflow", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
+ "unsupported_features": [],
+ },
+ "vscode": {
+ "adapter_mode": "agent-skills-compatible-project-or-user-scope",
+ "generated_files": ["SKILL.md", "agents/interface.yaml"],
+ "metadata_mapping": {
+ "name": "folder-name-and-SKILL.md::frontmatter.name",
+ "description": "SKILL.md::frontmatter.description",
+ "interface": "agents/interface.yaml",
+ },
+ "preserved_semantics": ["trigger", "workflow", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
+ "unsupported_features": ["VS Code installation scope is documented but not installed by this compiler"],
+ },
+}
+
+
+def display_path(path: Path, root: Path = ROOT) -> str:
+ try:
+ return str(path.resolve().relative_to(root.resolve()))
+ except ValueError:
+ return str(path.resolve())
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ if not path.exists():
+ return {}
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except json.JSONDecodeError:
+ return {}
+ return payload if isinstance(payload, dict) else {}
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+ if not path.exists() or yaml is None:
+ return {}
+ payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+ return payload if isinstance(payload, dict) else {}
+
+
+def read_frontmatter(path: Path) -> dict[str, Any]:
+ if not path.exists():
+ return {}
+ text = path.read_text(encoding="utf-8", errors="replace")
+ if not text.startswith("---"):
+ return {}
+ parts = text.split("---", 2)
+ if len(parts) < 3:
+ return {}
+ if yaml is not None:
+ payload = yaml.safe_load(parts[1]) or {}
+ return payload if isinstance(payload, dict) else {}
+ data: dict[str, Any] = {}
+ for line in parts[1].splitlines():
+ if ":" not in line:
+ continue
+ key, value = line.split(":", 1)
+ data[key.strip()] = value.strip().strip('"')
+ return data
+
+
+def find_skill_ir(skill_dir: Path, name: str) -> tuple[dict[str, Any], str]:
+ candidates = [
+ skill_dir / "reports" / "skill-ir.json",
+ skill_dir / "skill-ir" / "examples" / f"{name}.json",
+ skill_dir / "skill-ir" / "examples" / f"{skill_dir.name}.json",
+ ]
+ seen: set[Path] = set()
+ for path in candidates:
+ if path in seen:
+ continue
+ seen.add(path)
+ payload = load_json(path)
+ if payload:
+ return payload, display_path(path, skill_dir)
+ return {}, "frontmatter-fallback"
+
+
+def count_list(payload: dict[str, Any], key: str) -> int:
+ value = payload.get(key, [])
+ return len(value) if isinstance(value, list) else 0
+
+
+def list_or_empty(payload: dict[str, Any], key: str) -> list[str]:
+ value = payload.get(key, [])
+ return [str(item) for item in value] if isinstance(value, list) else []
+
+
+def resource_counts(resources: dict[str, Any]) -> dict[str, int]:
+ return {key: count_list(resources, key) for key in ("references", "scripts", "assets", "reports")}
+
+
+def eval_counts(eval_plan: dict[str, Any]) -> dict[str, int]:
+ return {
+ "trigger": count_list(eval_plan, "trigger"),
+ "output": count_list(eval_plan, "output"),
+ "adversarial": count_list(eval_plan, "adversarial"),
+ "baseline": 1 if eval_plan.get("baseline") else 0,
+ }
+
+
+def scripts_with_flag(scripts: list[dict[str, Any]], flag: str) -> list[str]:
+ return [str(item.get("path")) for item in scripts if item.get(flag)]
+
+
+def capability(name: str, scripts: list[str], review_reason: str) -> dict[str, Any]:
+ return {
+ "required": bool(scripts),
+ "script_count": len(scripts),
+ "scripts": scripts,
+ "review_reason": review_reason if scripts else "",
+ }
+
+
+def permission_contract(skill_dir: Path) -> dict[str, Any]:
+ trust_path = skill_dir / "reports" / "security_trust_report.json"
+ trust = load_json(trust_path)
+ scripts = trust.get("scripts", []) if isinstance(trust.get("scripts"), list) else []
+ network_scripts = scripts_with_flag(scripts, "uses_network")
+ file_write_scripts = scripts_with_flag(scripts, "uses_file_write")
+ subprocess_scripts = scripts_with_flag(scripts, "uses_subprocess")
+ interactive_scripts = scripts_with_flag(scripts, "uses_input")
+ capabilities = {
+ "network": capability("network", network_scripts, "Outbound hosts must match security/network_policy.json."),
+ "file_write": capability("file_write", file_write_scripts, "Scripts write local files or generated artifacts."),
+ "subprocess": capability("subprocess", subprocess_scripts, "Scripts spawn local commands and need operator review."),
+ "interactive": capability("interactive", interactive_scripts, "Scripts prompt for user input or credentials."),
+ }
+ declared = [name for name, item in capabilities.items() if item["required"]]
+ help_smoke = trust.get("help_smoke", {}) if isinstance(trust.get("help_smoke"), dict) else {}
+ network_policy = trust.get("network_policy", {}) if isinstance(trust.get("network_policy"), dict) else {}
+ summary = trust.get("summary", {}) if isinstance(trust.get("summary"), dict) else {}
+ return {
+ "schema_version": "1.0",
+ "source": display_path(trust_path, skill_dir) if trust else "missing-security-trust-report",
+ "source_available": bool(trust),
+ "declared_capabilities": declared,
+ "review_required": bool(declared),
+ "capabilities": capabilities,
+ "network_policy": {
+ "source": network_policy.get("path", "security/network_policy.json"),
+ "covered_scripts": network_policy.get("covered_scripts", []),
+ "missing_scripts": network_policy.get("missing_scripts", []),
+ "mismatches": network_policy.get("mismatches", []),
+ },
+ "help_smoke": {
+ "enabled": bool(help_smoke.get("enabled")),
+ "checked_count": int(help_smoke.get("checked_count", 0) or 0),
+ "failed_count": int(help_smoke.get("failed_count", 0) or 0),
+ "failed_scripts": help_smoke.get("failed_scripts", []),
+ },
+ "trust_summary": {
+ "secret_findings": int(summary.get("secret_findings", 0) or 0),
+ "network_script_count": int(summary.get("network_script_count", len(network_scripts)) or 0),
+ "file_write_script_count": int(summary.get("file_write_script_count", len(file_write_scripts)) or 0),
+ "subprocess_script_count": len(subprocess_scripts),
+ "interactive_script_count": int(summary.get("interactive_script_count", len(interactive_scripts)) or 0),
+ "help_smoke_failed_count": int(summary.get("help_smoke_failed_count", 0) or 0),
+ },
+ }
+
+
+TARGET_PERMISSION_MODELS = {
+ "openai": {
+ "model": "metadata-only",
+ "native_enforcement": False,
+ "representation": "targets/openai/agents/openai.yaml::compatibility.permission_contract plus adapter.json",
+ "operator_note": "OpenAI target carries permission metadata for reviewer visibility; host enforcement remains outside the package.",
+ },
+ "claude": {
+ "model": "neutral-source-plus-adapter",
+ "native_enforcement": False,
+ "representation": "targets/claude/adapter.json::target_permission_contract and README notes",
+ "operator_note": "Claude-compatible package keeps permission intent in adapter metadata for install review.",
+ },
+ "generic": {
+ "model": "agent-skills-compatible-metadata",
+ "native_enforcement": False,
+ "representation": "targets/generic/adapter.json::target_permission_contract",
+ "operator_note": "Generic target exposes permission metadata for downstream clients to enforce or review.",
+ },
+}
+
+
+TARGET_NATIVE_MODELS = {
+ "openai": {
+ "native_surface": "OpenAI-style interface metadata plus neutral Agent Skills source",
+ "activation_policy": "Use frontmatter description for catalog routing and targets/openai/agents/openai.yaml for display name, default prompt, and compatibility metadata.",
+ "resource_strategy": "Ship the neutral source tree and expose OpenAI-facing interface metadata as a generated companion file.",
+ "script_strategy": "Keep scripts as local package resources; expose help-smoke and permission metadata for reviewer approval before execution.",
+ "permission_enforcement": "metadata-only",
+ "install_scope": "plugin or skill package consumer",
+ "review_artifacts": ["targets/openai/agents/openai.yaml", "targets/openai/adapter.json", "reports/review-studio.html"],
+ "fallback_behavior": "If OpenAI-native metadata is ignored, the package remains readable as neutral Agent Skills source.",
+ "unsupported_native_features": [
+ "client-native permission prompts",
+ "provider-executed scripts",
+ ],
+ },
+ "claude": {
+ "native_surface": "Claude-compatible neutral source folder with adapter notes",
+ "activation_policy": "Use SKILL.md frontmatter description as the primary activation contract and adapter.json for review metadata.",
+ "resource_strategy": "Preserve the source tree directly; write target notes in targets/claude/README.md.",
+ "script_strategy": "Scripts remain local package resources and must be reviewed through trust and permission reports before use.",
+ "permission_enforcement": "metadata-fallback",
+ "install_scope": "user or project skill directory",
+ "review_artifacts": ["targets/claude/README.md", "targets/claude/adapter.json", "reports/review-studio.html"],
+ "fallback_behavior": "If Claude-specific metadata is not consumed, SKILL.md and references remain the source of truth.",
+ "unsupported_native_features": [
+ "vendor-native permission enforcement",
+ "provider-specific execution transforms",
+ ],
+ },
+ "generic": {
+ "native_surface": "Agent Skills compatible neutral package",
+ "activation_policy": "Use SKILL.md name and description; consumers decide automatic or manual activation.",
+ "resource_strategy": "Preserve references, scripts, assets, evals, reports, and adapter metadata as relative package resources.",
+ "script_strategy": "Expose script and permission metadata for downstream clients or installers to enforce.",
+ "permission_enforcement": "consumer-enforced-or-metadata-only",
+ "install_scope": "generic Agent Skills compatible root",
+ "review_artifacts": ["targets/generic/adapter.json", "reports/review-studio.html"],
+ "fallback_behavior": "Neutral source is the runtime fallback.",
+ "unsupported_native_features": [],
+ },
+ "agent-skills-compatible": {
+ "native_surface": "Agent Skills standard source tree",
+ "activation_policy": "Use SKILL.md frontmatter name and description for progressive disclosure.",
+ "resource_strategy": "Keep optional directories as relative resources next to SKILL.md.",
+ "script_strategy": "Scripts remain local optional resources and should advertise --help when executable.",
+ "permission_enforcement": "consumer-enforced-or-metadata-only",
+ "install_scope": "Agent Skills source root",
+ "review_artifacts": ["SKILL.md", "agents/interface.yaml", "reports/review-studio.html"],
+ "fallback_behavior": "The source tree itself is the target artifact.",
+ "unsupported_native_features": [],
+ },
+ "agent-skills": {
+ "native_surface": "Agent Skills standard source tree",
+ "activation_policy": "Use SKILL.md frontmatter name and description for progressive disclosure.",
+ "resource_strategy": "Keep optional directories as relative resources next to SKILL.md.",
+ "script_strategy": "Scripts remain local optional resources and should advertise --help when executable.",
+ "permission_enforcement": "consumer-enforced-or-metadata-only",
+ "install_scope": "Agent Skills source root",
+ "review_artifacts": ["SKILL.md", "agents/interface.yaml", "reports/review-studio.html"],
+ "fallback_behavior": "The source tree itself is the target artifact.",
+ "unsupported_native_features": [],
+ },
+ "vscode": {
+ "native_surface": "VS Code/Copilot Agent Skills project or user scope",
+ "activation_policy": "Use folder name plus SKILL.md name/description; keep description under platform limits.",
+ "resource_strategy": "Install as project or user scoped skill source, preserving relative references and scripts.",
+ "script_strategy": "Scripts require workspace trust and operator/client approval outside this compiler.",
+ "permission_enforcement": "client-or-workspace-trust",
+ "install_scope": "VS Code user or project skills directory",
+ "review_artifacts": ["SKILL.md", "agents/interface.yaml", "reports/review-studio.html"],
+ "fallback_behavior": "If VS Code scope is not installed, use the neutral Agent Skills source.",
+ "unsupported_native_features": [
+ "automatic VS Code installation",
+ ],
+ },
+}
+
+
+def target_permission_contract(target: str, permissions: dict[str, Any]) -> dict[str, Any]:
+ model = TARGET_PERMISSION_MODELS.get(
+ target,
+ {
+ "model": "metadata-only",
+ "native_enforcement": False,
+ "representation": "adapter metadata",
+ "operator_note": "Permission semantics are preserved as metadata for reviewer visibility.",
+ },
+ )
+ return {
+ "schema_version": "1.0",
+ "target": target,
+ "permission_model": model["model"],
+ "native_enforcement": model["native_enforcement"],
+ "representation": model["representation"],
+ "review_required": bool(permissions.get("review_required")),
+ "declared_capabilities": permissions.get("declared_capabilities", []),
+ "capability_counts": {
+ name: item.get("script_count", 0)
+ for name, item in permissions.get("capabilities", {}).items()
+ },
+ "evidence": permissions.get("source", ""),
+ "operator_note": model["operator_note"],
+ }
+
+
+def target_native_contract(
+ target: str,
+ profile: dict[str, Any],
+ contract: dict[str, Any],
+ target_permissions: dict[str, Any],
+) -> dict[str, Any]:
+ model = TARGET_NATIVE_MODELS.get(
+ target,
+ {
+ "native_surface": "adapter metadata",
+ "activation_policy": "Carry activation semantics as metadata for the target consumer.",
+ "resource_strategy": "Preserve neutral package resources.",
+ "script_strategy": "Expose script metadata for reviewer visibility.",
+ "permission_enforcement": "metadata-only",
+ "install_scope": "target consumer",
+ "review_artifacts": ["adapter.json", "reports/review-studio.html"],
+ "fallback_behavior": "Use neutral source package.",
+ "unsupported_native_features": [],
+ },
+ )
+ return {
+ "schema_version": "1.0",
+ "target": target,
+ "native_surface": model["native_surface"],
+ "activation": {
+ "policy": model["activation_policy"],
+ "trigger_description": contract.get("trigger", {}).get("description", ""),
+ "manual_activation_supported": True,
+ "automatic_activation_note": "Depends on the target client route/catalog implementation.",
+ },
+ "resources": {
+ "strategy": model["resource_strategy"],
+ "counts": contract.get("resources", {}).get("counts", {}),
+ "generated_files": profile.get("generated_files", []),
+ },
+ "scripts": {
+ "strategy": model["script_strategy"],
+ "script_count": contract.get("resources", {}).get("counts", {}).get("scripts", 0),
+ "help_smoke_failed_count": contract.get("permissions", {}).get("help_smoke", {}).get("failed_count", 0),
+ },
+ "permissions": {
+ "enforcement": model["permission_enforcement"],
+ "native_enforcement": bool(target_permissions.get("native_enforcement")),
+ "declared_capabilities": target_permissions.get("declared_capabilities", []),
+ "review_required": bool(target_permissions.get("review_required")),
+ },
+ "review": {
+ "artifacts": model["review_artifacts"],
+ "fallback_behavior": model["fallback_behavior"],
+ "unsupported_native_features": [
+ *model.get("unsupported_native_features", []),
+ *profile.get("unsupported_features", []),
+ ],
+ },
+ "install_scope": model["install_scope"],
+ }
+
+
+def load_sources(skill_dir: Path) -> dict[str, Any]:
+ skill_dir = skill_dir.resolve()
+ frontmatter = read_frontmatter(skill_dir / "SKILL.md")
+ manifest = load_json(skill_dir / "manifest.json")
+ interface_doc = load_yaml(skill_dir / "agents" / "interface.yaml")
+ name = str(frontmatter.get("name") or manifest.get("name") or skill_dir.name)
+ ir, ir_source = find_skill_ir(skill_dir, name)
+ return {
+ "skill_dir": skill_dir,
+ "frontmatter": frontmatter,
+ "manifest": manifest,
+ "interface_doc": interface_doc,
+ "interface": interface_doc.get("interface", {}),
+ "compatibility": interface_doc.get("compatibility", {}),
+ "ir": ir,
+ "ir_source": ir_source,
+ }
+
+
+def declared_targets(sources: dict[str, Any]) -> list[str]:
+ ir = sources["ir"]
+ compatibility = sources["compatibility"]
+ manifest = sources["manifest"]
+ candidates = (
+ ir.get("targets")
+ if isinstance(ir.get("targets"), list)
+ else manifest.get("target_platforms")
+ or compatibility.get("adapter_targets")
+ or []
+ )
+ targets = []
+ for item in candidates:
+ value = str(item).strip()
+ if value and value not in targets:
+ targets.append(value)
+ return targets or ["generic"]
+
+
+def semantic_source(sources: dict[str, Any]) -> dict[str, Any]:
+ skill_dir = sources["skill_dir"]
+ frontmatter = sources["frontmatter"]
+ manifest = sources["manifest"]
+ interface = sources["interface"]
+ compatibility = sources["compatibility"]
+ ir = sources["ir"]
+ trigger = ir.get("trigger_surface", {}) if isinstance(ir.get("trigger_surface"), dict) else {}
+ workflow = ir.get("workflow", {}) if isinstance(ir.get("workflow"), dict) else {}
+ resources = ir.get("resources", {}) if isinstance(ir.get("resources"), dict) else {}
+ eval_plan = ir.get("eval_plan", {}) if isinstance(ir.get("eval_plan"), dict) else {}
+ description = str(trigger.get("description") or frontmatter.get("description") or "")
+ name = str(ir.get("name") or frontmatter.get("name") or manifest.get("name") or skill_dir.name)
+ permissions = permission_contract(skill_dir)
+ return {
+ "name": name,
+ "title": str(ir.get("title") or interface.get("display_name") or name),
+ "version": str(manifest.get("version") or frontmatter.get("version") or "1.0.0"),
+ "description": description,
+ "job_to_be_done": str(ir.get("job_to_be_done") or description),
+ "trigger": {
+ "description": description,
+ "should_trigger": list_or_empty(trigger, "should_trigger"),
+ "should_not_trigger": list_or_empty(trigger, "should_not_trigger"),
+ "edge_cases": list_or_empty(trigger, "edge_cases"),
+ },
+ "workflow": {
+ "steps": list_or_empty(workflow, "steps"),
+ "decision_points": list_or_empty(workflow, "decision_points"),
+ "failure_modes": list_or_empty(workflow, "failure_modes"),
+ },
+ "resources": {
+ "references": list_or_empty(resources, "references"),
+ "scripts": list_or_empty(resources, "scripts"),
+ "assets": list_or_empty(resources, "assets"),
+ "reports": list_or_empty(resources, "reports"),
+ "counts": resource_counts(resources),
+ },
+ "eval_plan": {
+ "trigger": list_or_empty(eval_plan, "trigger"),
+ "output": list_or_empty(eval_plan, "output"),
+ "adversarial": list_or_empty(eval_plan, "adversarial"),
+ "baseline": str(eval_plan.get("baseline") or ""),
+ "counts": eval_counts(eval_plan),
+ },
+ "risk": ir.get("risk", {}) if isinstance(ir.get("risk"), dict) else {},
+ "governance": ir.get("governance", {}) if isinstance(ir.get("governance"), dict) else {},
+ "runtime": {
+ "activation": compatibility.get("activation", {}) if isinstance(compatibility.get("activation"), dict) else {},
+ "execution": compatibility.get("execution", {}) if isinstance(compatibility.get("execution"), dict) else {},
+ "trust": compatibility.get("trust", {}) if isinstance(compatibility.get("trust"), dict) else {},
+ "adapter_targets": compatibility.get("adapter_targets", []),
+ "canonical_format": compatibility.get("canonical_format", "agent-skills"),
+ },
+ "permissions": permissions,
+ "source_files_count": count_list(ir, "source_files") if ir else 0,
+ }
+
+
+def compile_target_contract(skill_dir: Path, target: str) -> dict[str, Any]:
+ sources = load_sources(skill_dir)
+ compatibility = sources["compatibility"]
+ degradation = compatibility.get("degradation", {}) if isinstance(compatibility.get("degradation"), dict) else {}
+ declared = declared_targets(sources)
+ failures: list[str] = []
+ warnings: list[str] = []
+ profile = TARGET_TRANSFORMS.get(target)
+ if profile is None:
+ failures.append(f"Unsupported compiler target: {target}")
+ profile = {
+ "adapter_mode": "unsupported",
+ "generated_files": [],
+ "metadata_mapping": {},
+ "preserved_semantics": [],
+ "unsupported_features": [],
+ }
+ if target not in declared and not (target == "agent-skills" and "agent-skills-compatible" in declared):
+ warnings.append(f"Target is not declared in Skill IR or interface metadata: {target}")
+ if not sources["ir"]:
+ warnings.append("Skill IR is missing; compiler used frontmatter fallback")
+
+ contract = semantic_source(sources)
+ permissions = contract["permissions"]
+ target_permissions = target_permission_contract(target, permissions)
+ target_native = target_native_contract(target, profile, contract, target_permissions)
+ contract["target"] = target
+ contract["target_permission_contract"] = target_permissions
+ contract["target_native_contract"] = target_native
+ contract["degradation_strategy"] = degradation.get(target, degradation.get("generic", "neutral-source"))
+ contract["target_runtime"] = {
+ "adapter_mode": profile["adapter_mode"],
+ "generated_files": profile["generated_files"],
+ "metadata_mapping": profile["metadata_mapping"],
+ "preserved_semantics": profile["preserved_semantics"],
+ "native_surface": target_native["native_surface"],
+ }
+
+ return {
+ "schema_version": COMPILER_SCHEMA_VERSION,
+ "target": target,
+ "status": "block" if failures else ("warn" if warnings else "pass"),
+ "compiler": {
+ "name": COMPILER_NAME,
+ "schema_version": COMPILER_SCHEMA_VERSION,
+ "source": "skill-ir" if sources["ir"] else "frontmatter-fallback",
+ "ir_source": sources["ir_source"],
+ "ir_schema_version": str(sources["ir"].get("schema_version") or "none"),
+ },
+ "source": {
+ "skill_dir": display_path(sources["skill_dir"]),
+ "canonical_metadata": "agents/interface.yaml" if (sources["skill_dir"] / "agents" / "interface.yaml").exists() else "missing",
+ "declared_targets": declared,
+ },
+ "compiled_contract": contract,
+ "permission_contract": permissions,
+ "target_permission_contract": target_permissions,
+ "target_native_contract": target_native,
+ "target_transform": {
+ "target": target,
+ "adapter_mode": profile["adapter_mode"],
+ "generated_files": profile["generated_files"],
+ "metadata_mapping": profile["metadata_mapping"],
+ "preserved_semantics": profile["preserved_semantics"],
+ "degradation_strategy": contract["degradation_strategy"],
+ "permission_representation": target_permissions["representation"],
+ "native_surface": target_native["native_surface"],
+ "activation_policy": target_native["activation"]["policy"],
+ "resource_strategy": target_native["resources"]["strategy"],
+ "script_strategy": target_native["scripts"]["strategy"],
+ "permission_enforcement": target_native["permissions"]["enforcement"],
+ },
+ "unsupported_features": list(profile.get("unsupported_features", [])),
+ "warnings": warnings,
+ "failures": failures,
+ }
+
+
+def compile_targets(skill_dir: Path, targets: list[str] | None = None, generated_at: str | None = None) -> dict[str, Any]:
+ sources = load_sources(skill_dir)
+ selected = targets or declared_targets(sources)
+ compiled = [compile_target_contract(skill_dir, target) for target in selected]
+ failures = [failure for item in compiled for failure in item["failures"]]
+ warnings = [warning for item in compiled for warning in item["warnings"]]
+ return {
+ "schema_version": COMPILER_SCHEMA_VERSION,
+ "ok": not failures,
+ "generated_at": generated_at or str(date.today()),
+ "skill_dir": display_path(Path(skill_dir).resolve()),
+ "summary": {
+ "target_count": len(compiled),
+ "pass_count": sum(1 for item in compiled if item["status"] == "pass"),
+ "warn_count": sum(1 for item in compiled if item["status"] == "warn"),
+ "block_count": sum(1 for item in compiled if item["status"] == "block"),
+ "failure_count": len(failures),
+ "warning_count": len(warnings),
+ },
+ "targets": compiled,
+ "failures": failures,
+ "warnings": warnings,
+ }
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+ summary = report["summary"]
+ lines = [
+ "# Compiled Targets",
+ "",
+ f"- OK: `{report['ok']}`",
+ f"- Targets: `{summary['target_count']}`",
+ f"- Pass: `{summary['pass_count']}`",
+ f"- Warn: `{summary['warn_count']}`",
+ f"- Block: `{summary['block_count']}`",
+ "",
+ "## Target Transforms",
+ "",
+ "| Target | Status | Native Surface | Adapter Mode | Permissions | Degradation | Generated Files |",
+ "| --- | --- | --- | --- | --- | --- | --- |",
+ ]
+ for item in report["targets"]:
+ transform = item["target_transform"]
+ files = ", ".join(transform.get("generated_files", [])) or "none"
+ permissions = ", ".join(item.get("target_permission_contract", {}).get("declared_capabilities", [])) or "none"
+ lines.append(
+ f"| `{item['target']}` | `{item['status']}` | {transform.get('native_surface', '')} | `{transform.get('adapter_mode', '')}` | `{permissions}` | `{transform.get('degradation_strategy', '')}` | {files} |"
+ )
+ lines.extend(["", "## Native Behavior Contracts", ""])
+ for item in report["targets"]:
+ native = item.get("target_native_contract", {})
+ permissions = native.get("permissions", {})
+ review = native.get("review", {})
+ lines.extend(
+ [
+ f"### {item['target']}",
+ "",
+ f"- Native surface: {native.get('native_surface', '')}",
+ f"- Activation: {native.get('activation', {}).get('policy', '')}",
+ f"- Resources: {native.get('resources', {}).get('strategy', '')}",
+ f"- Scripts: {native.get('scripts', {}).get('strategy', '')}",
+ f"- Permission enforcement: `{permissions.get('enforcement', '')}`; native enforcement `{permissions.get('native_enforcement')}`",
+ f"- Review artifacts: {', '.join(review.get('artifacts', [])) or 'none'}",
+ "",
+ ]
+ )
+ lines.extend(["", "## Failures", ""])
+ lines.extend([f"- {item}" for item in report["failures"]] or ["- None"])
+ lines.extend(["", "## Warnings", ""])
+ lines.extend([f"- {item}" for item in report["warnings"]] or ["- None"])
+ return "\n".join(lines).strip() + "\n"
+
+
+def render_compile_report(
+ skill_dir: Path,
+ targets: list[str] | None = None,
+ output_json: Path | None = None,
+ output_md: Path | None = None,
+ generated_at: str | None = None,
+) -> dict[str, Any]:
+ skill_dir = skill_dir.resolve()
+ reports = skill_dir / "reports"
+ reports.mkdir(parents=True, exist_ok=True)
+ output_json = output_json or reports / "compiled_targets.json"
+ output_md = output_md or reports / "compiled_targets.md"
+ report = compile_targets(skill_dir, targets=targets, generated_at=generated_at)
+ report["artifacts"] = {
+ "json": display_path(output_json),
+ "markdown": display_path(output_md),
+ }
+ output_json.parent.mkdir(parents=True, exist_ok=True)
+ output_json.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ output_md.write_text(render_markdown(report), encoding="utf-8")
+ return report
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Compile Skill IR into target-specific semantic contracts.")
+ parser.add_argument("skill_dir", nargs="?", default=".")
+ parser.add_argument("--target", action="append", default=[])
+ parser.add_argument("--output-json")
+ parser.add_argument("--output-md")
+ parser.add_argument("--generated-at")
+ args = parser.parse_args()
+
+ payload = render_compile_report(
+ Path(args.skill_dir),
+ targets=args.target or None,
+ output_json=Path(args.output_json).resolve() if args.output_json else None,
+ output_md=Path(args.output_md).resolve() if args.output_md else None,
+ generated_at=args.generated_at,
+ )
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+ raise SystemExit(0 if payload["ok"] else 2)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/cross_packager.py b/scripts/cross_packager.py
index ae81216..6799afe 100644
--- a/scripts/cross_packager.py
+++ b/scripts/cross_packager.py
@@ -6,6 +6,8 @@ import zipfile
from pathlib import Path
import yaml
+from compile_skill import compile_target_contract
+
def display_path(path: Path, root: Path) -> str:
try:
@@ -199,10 +201,13 @@ def build_manifest(skill_dir: Path, platform: str) -> dict:
ir=ir,
ir_source=ir_source,
)
+ compiled = compile_target_contract(skill_dir, platform)
+ if compiled.get("failures"):
+ raise ValueError(f"Compiler failed for {platform}: {'; '.join(compiled['failures'])}")
return {
"name": semantic["name"],
"description": semantic["description"],
- "version": frontmatter.get("version", "1.0.0"),
+ "version": manifest.get("version") or frontmatter.get("version", "1.0.0"),
"platform": platform,
"skill_root": skill_dir.name,
"job_to_be_done": semantic["job_to_be_done"],
@@ -210,6 +215,14 @@ def build_manifest(skill_dir: Path, platform: str) -> dict:
"ir_schema_version": semantic["ir_schema_version"],
"semantic_contract": semantic["semantic_contract"],
"semantic_parity": semantic["semantic_parity"],
+ "compiler": compiled["compiler"],
+ "compiled_contract": compiled["compiled_contract"],
+ "permission_contract": compiled["permission_contract"],
+ "target_permission_contract": compiled["target_permission_contract"],
+ "target_native_contract": compiled["target_native_contract"],
+ "target_transform": compiled["target_transform"],
+ "unsupported_features": compiled["unsupported_features"],
+ "compiler_warnings": compiled["warnings"],
"display_name": interface.get("display_name", skill_dir.name),
"short_description": interface.get("short_description", ""),
"default_prompt": interface.get("default_prompt", ""),
@@ -260,6 +273,9 @@ PLATFORM_CONTRACTS = {
"remote_inline_execution",
"degradation_strategy",
"portability_profile",
+ "permission_contract",
+ "target_permission_contract",
+ "target_native_contract",
],
"required_files": ["targets/openai/adapter.json", "targets/openai/agents/openai.yaml"],
"field_mapping": {
@@ -292,6 +308,9 @@ PLATFORM_CONTRACTS = {
"remote_inline_execution",
"degradation_strategy",
"portability_profile",
+ "permission_contract",
+ "target_permission_contract",
+ "target_native_contract",
],
"required_files": ["targets/claude/adapter.json", "targets/claude/README.md"],
"field_mapping": {
@@ -324,6 +343,9 @@ PLATFORM_CONTRACTS = {
"remote_inline_execution",
"degradation_strategy",
"portability_profile",
+ "permission_contract",
+ "target_permission_contract",
+ "target_native_contract",
],
"required_files": ["targets/generic/adapter.json"],
"field_mapping": {
@@ -336,6 +358,19 @@ PLATFORM_CONTRACTS = {
},
}
+EXCLUDED_ARCHIVE_PARTS = {".git", "__pycache__", ".venv", "venv", "node_modules", "dist"}
+
+
+def should_skip_archive_path(rel_path: Path) -> bool:
+ parts = rel_path.parts
+ if any(part in EXCLUDED_ARCHIVE_PARTS for part in parts):
+ return True
+ if parts == ("reports", "telemetry_events.jsonl"):
+ return True
+ if parts and parts[0] == "tests" and any(part.startswith("tmp") for part in parts[1:]):
+ return True
+ return False
+
def is_relative_to(path: Path, parent: Path) -> bool:
try:
@@ -397,6 +432,19 @@ def write_adapter(skill_dir: Path, out_dir: Path, platform: str) -> Path:
"shell": payload["shell"],
"trust_level": payload["trust_level"],
"remote_inline_execution": payload["remote_inline_execution"],
+ "permission_contract": {
+ "review_required": payload["target_permission_contract"]["review_required"],
+ "declared_capabilities": payload["target_permission_contract"]["declared_capabilities"],
+ "native_enforcement": payload["target_permission_contract"]["native_enforcement"],
+ "representation": payload["target_permission_contract"]["representation"],
+ },
+ "native_contract": {
+ "native_surface": payload["target_native_contract"]["native_surface"],
+ "activation_policy": payload["target_native_contract"]["activation"]["policy"],
+ "resource_strategy": payload["target_native_contract"]["resources"]["strategy"],
+ "permission_enforcement": payload["target_native_contract"]["permissions"]["enforcement"],
+ "review_artifacts": payload["target_native_contract"]["review"]["artifacts"],
+ },
"degradation_strategy": payload["degradation_strategy"],
},
},
@@ -404,8 +452,14 @@ def write_adapter(skill_dir: Path, out_dir: Path, platform: str) -> Path:
payload["install_hint"] = f"Use the packaged skill and include targets/openai/agents/openai.yaml when the client expects OpenAI-style interface metadata."
elif platform == "claude":
notes = target_dir / "README.md"
+ native = payload["target_native_contract"]
notes.write_text(
- f"# Claude-Compatible Package\n\nUse `{skill_dir.name}` with its neutral source files. This target does not require vendor metadata by default.\n",
+ f"# Claude-Compatible Package\n\nUse `{skill_dir.name}` with its neutral source files. This target does not require vendor metadata by default.\n\n"
+ f"Native surface: {native['native_surface']}.\n\n"
+ f"Activation: {native['activation']['policy']}\n\n"
+ f"Resources: {native['resources']['strategy']}\n\n"
+ f"Scripts: {native['scripts']['strategy']}\n\n"
+ f"Permission metadata is preserved in `adapter.json` under `target_permission_contract` and `target_native_contract` for reviewer visibility.\n",
encoding="utf-8",
)
payload["install_hint"] = f"Use the packaged skill directly; this target relies on SKILL.md and optional neutral metadata."
@@ -430,6 +484,9 @@ def make_zip(skill_dir: Path, out_dir: Path) -> Path:
continue
if is_relative_to(resolved, out_root):
continue
+ rel_path = path.relative_to(skill_dir)
+ if should_skip_archive_path(rel_path):
+ continue
zf.write(path, arcname=str(path.relative_to(skill_dir.parent)))
return zip_path
diff --git a/scripts/export_skill_ir.py b/scripts/export_skill_ir.py
index 2f7870e..08386a6 100644
--- a/scripts/export_skill_ir.py
+++ b/scripts/export_skill_ir.py
@@ -36,10 +36,21 @@ KEY_REPORTS = [
"reports/skill-overview.html",
"reports/output_quality_scorecard.json",
"reports/output_quality_scorecard.md",
+ "reports/output_execution_runs.json",
+ "reports/output_execution_runs.md",
+ "reports/output_blind_review_pack.json",
+ "reports/output_blind_review_pack.md",
+ "reports/output_blind_answer_key.json",
+ "reports/output_review_adjudication.json",
+ "reports/output_review_adjudication.md",
+ "reports/review_annotations.json",
+ "reports/review_annotations.md",
"reports/conformance_matrix.json",
"reports/conformance_matrix.md",
"reports/security_trust_report.json",
"reports/security_trust_report.md",
+ "reports/runtime_permission_probes.json",
+ "reports/runtime_permission_probes.md",
"reports/skill_atlas.json",
"reports/skill_atlas.html",
"reports/skill-os-2-review.md",
diff --git a/scripts/init_skill.py b/scripts/init_skill.py
index 0f59add..be9b33e 100644
--- a/scripts/init_skill.py
+++ b/scripts/init_skill.py
@@ -5,11 +5,15 @@ import re
from datetime import date
from pathlib import Path
+from compile_skill import render_compile_report
from export_skill_ir import build_skill_ir, validate_ir
from github_benchmark_scan import run_github_benchmark_scan
from render_intent_confidence import render_intent_confidence
from render_intent_dialogue import render_intent_dialogue
from render_iteration_directions import render_iteration_directions
+from render_adoption_drift_report import render_report as render_adoption_drift_report
+from render_review_annotations import render_report as render_review_annotations
+from render_review_waivers import render_report as render_review_waivers
from render_artifact_design_profile import render_artifact_design_profile
from render_output_risk_profile import render_output_risk_profile
from render_prompt_quality_profile import render_prompt_quality_profile
@@ -71,13 +75,17 @@ README_TEMPLATE = """# {title}
6. Follow the workflow steps in `SKILL.md`.
7. Check `reports/skill-overview.html` for the generated bilingual HTML skill audit report: overview, metrics, capability profile, principle, contract, quality, risk, assets, and iteration roadmap. It defaults to Simplified Chinese and includes an English switch in the top right.
8. Open `reports/review-studio.html` for the one-page Review Studio 2.0 gate view.
-9. Open `reports/review-viewer.html` for a compact visual review of the package.
-10. Check `reports/output-risk-profile.md` to see likely output mistakes and self-repair checks.
-11. Check `reports/artifact-design-profile.md` to see the intended artifact direction, layout patterns, visual quality gates, and anti-patterns.
-12. Check `reports/prompt-quality-profile.md` to see the need model, RTF-to-skill mapping, complexity, and prompt-facing quality matrix.
-13. Review `reports/skill-ir.json` for the platform-neutral Skill IR contract before platform-specific packaging.
-14. Review `reports/iteration-directions.md` for the three most valuable next moves.
-15. Review `reports/system-model.md` to understand the boundary, feedback loops, drift watch, failure map, and highest-leverage next changes.
+9. Record source-line reviewer comments in `reports/review_annotations.md` when review needs follow-up.
+10. Open `reports/review-viewer.html` for a compact visual review of the package.
+11. Check `reports/output-risk-profile.md` to see likely output mistakes and self-repair checks.
+12. Check `reports/artifact-design-profile.md` to see the intended artifact direction, layout patterns, visual quality gates, and anti-patterns.
+13. Check `reports/prompt-quality-profile.md` to see the need model, RTF-to-skill mapping, complexity, and prompt-facing quality matrix.
+14. Review `reports/skill-ir.json` for the platform-neutral Skill IR contract before platform-specific packaging.
+15. Review `reports/compiled_targets.md` to see how Skill IR compiles into OpenAI, Claude, generic, and Agent Skills compatible target contracts.
+16. Review `reports/iteration-directions.md` for the three most valuable next moves.
+17. Review `reports/system-model.md` to understand the boundary, feedback loops, drift watch, failure map, and highest-leverage next changes.
+18. Review `reports/adoption_drift_report.md` to see local-first metadata-only adoption and drift signals.
+19. Review `reports/review_waivers.md` to see human reviewer risk approvals and expiry dates.
## Honest Boundaries
@@ -100,10 +108,14 @@ README_TEMPLATE = """# {title}
- `reports/prompt-quality-profile.md`: prompt-facing need model, RTF mapping, complexity, and quality matrix
- `reports/system-model.md`: systems-thinking model for boundary, feedback loops, drift, failure patterns, and leverage points
- `reports/skill-ir.json`: platform-neutral 2.0 Skill IR contract for trigger, workflow, resources, evals, risk, and governance
+- `reports/compiled_targets.md`: target compiler report showing generated contracts, adapter modes, preserved semantics, warnings, and unsupported features
- `reports/skill-overview.html`: white-background bilingual HTML skill audit report with sticky four-character Chinese navigation, a top-right language switch, metrics, SVG charts, contract boundary, quality review, risk governance, assets, and iteration roadmap
- `reports/review-studio.html`: Review Studio 2.0 gate page for intent, trigger, output eval, context, runtime conformance, trust, atlas, and release readiness
- `reports/review-viewer.html`: compact review page for architecture, usage, feedback, and next steps
- `reports/iteration-directions.md`: the top three next iteration directions
+- `reports/adoption_drift_report.md`: local-first metadata-only telemetry summary for adoption, missed triggers, bad outputs, script errors, and review drift
+- `reports/review_waivers.md`: human reviewer risk approval ledger for warning acceptance and expiry
+- `reports/review_annotations.md`: source-line reviewer comments linked to Review Studio gates
"""
@@ -223,8 +235,10 @@ def build_report_view(artifacts: dict) -> dict:
"review_studio": review_studio,
"message": (
f"Skill 已创建完成。建议先打开总结报告:{html_report}。"
- "它会展示这个 Skill 的概述、指标、原理、触发边界、输入输出、质量评估、风险治理、包体资产和升级路线;"
+ "它会展示这个 Skill 的概述、指标、原理、触发边界、输入输出、目标编译、质量评估、风险治理、包体资产和升级路线;"
f"然后打开 Review Studio 2.0:{review_studio},检查意图、触发、输出评测、运行一致性、信任和发布闸门。"
+ "后续 reviewer 的文件级或行级意见可以记录到 reports/review_annotations.md。"
+ "如需审查平台适配细节,请打开 reports/compiled_targets.md。"
"报告默认使用中文简体,右上角可以切换英文版。"
),
"next_action": "Open reports/skill-overview.html before editing more files.",
@@ -336,7 +350,11 @@ def initialize_skill(
prompt_quality_profile = render_prompt_quality_profile(root)
system_model = render_system_model(root)
skill_ir = render_skill_ir(root)
+ compiled_targets = render_compile_report(root)
iteration_directions = render_iteration_directions(root)
+ adoption_drift = render_adoption_drift_report(root)
+ review_waivers = render_review_waivers(root)
+ review_annotations = render_review_annotations(root)
overview = render_skill_overview(root)
review_viewer = render_review_viewer(root)
review_studio = render_review_studio(root)
@@ -363,8 +381,16 @@ def initialize_skill(
"system_model_md": system_model["artifacts"]["markdown"],
"system_model_json": system_model["artifacts"]["json"],
"skill_ir_json": skill_ir["artifacts"]["json"],
+ "compiled_targets_md": compiled_targets["artifacts"]["markdown"],
+ "compiled_targets_json": compiled_targets["artifacts"]["json"],
"iteration_directions_md": iteration_directions["artifacts"]["markdown"],
"iteration_directions_json": iteration_directions["artifacts"]["json"],
+ "adoption_drift_md": adoption_drift["artifacts"]["markdown"],
+ "adoption_drift_json": adoption_drift["artifacts"]["json"],
+ "review_waivers_md": review_waivers["artifacts"]["markdown"],
+ "review_waivers_json": review_waivers["artifacts"]["json"],
+ "review_annotations_md": review_annotations["artifacts"]["markdown"],
+ "review_annotations_json": review_annotations["artifacts"]["json"],
"review_viewer_html": review_viewer["artifacts"]["html"],
"review_viewer_json": review_viewer["artifacts"]["json"],
"review_studio_html": absolute_skill_artifact(root, review_studio["artifacts"]["html"]),
@@ -384,6 +410,7 @@ def initialize_skill(
"reference_synthesis": reference_synthesis["summary"],
"system_model": system_model["summary"],
"skill_ir": skill_ir["summary"],
+ "compiled_targets": compiled_targets["summary"],
"artifacts": artifacts,
"report_view": report_view,
}
diff --git a/scripts/local_output_eval_runner.py b/scripts/local_output_eval_runner.py
new file mode 100644
index 0000000..b87b0b2
--- /dev/null
+++ b/scripts/local_output_eval_runner.py
@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import sys
+from typing import Any
+
+
+def estimate_tokens(text: str) -> int:
+ if not text:
+ return 0
+ return max(1, round(len(text) / 4))
+
+
+def build_response(request: dict[str, Any], execution_kind: str, provider: str, model: str) -> dict[str, Any]:
+ output = str(request.get("fixture_output", ""))
+ prompt = str(request.get("prompt", ""))
+ input_tokens = estimate_tokens(prompt)
+ output_tokens = estimate_tokens(output)
+ response: dict[str, Any] = {
+ "output": output,
+ "execution_kind": execution_kind,
+ "provider": provider,
+ "usage": {
+ "input_tokens": input_tokens,
+ "output_tokens": output_tokens,
+ "total_tokens": input_tokens + output_tokens,
+ "estimated": True,
+ },
+ }
+ if model:
+ response["model"] = model
+ return response
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(
+ description=(
+ "Local deterministic output-eval runner. It executes the runner contract "
+ "without claiming provider-backed model generation."
+ )
+ )
+ parser.add_argument("--execution-kind", choices=["command", "model"], default="command")
+ parser.add_argument("--provider", default="local-output-eval-runner")
+ parser.add_argument("--model", default="")
+ args = parser.parse_args()
+
+ raw = sys.stdin.read()
+ if not raw.strip():
+ print("runner requires a JSON request on stdin", file=sys.stderr)
+ raise SystemExit(2)
+ try:
+ request = json.loads(raw)
+ except json.JSONDecodeError as exc:
+ print(f"invalid JSON request: {exc}", file=sys.stderr)
+ raise SystemExit(2)
+ if not isinstance(request, dict):
+ print("runner request must be a JSON object", file=sys.stderr)
+ raise SystemExit(2)
+
+ response = build_response(request, args.execution_kind, args.provider, args.model)
+ print(json.dumps(response, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/probe_runtime_permissions.py b/scripts/probe_runtime_permissions.py
new file mode 100644
index 0000000..6ea2504
--- /dev/null
+++ b/scripts/probe_runtime_permissions.py
@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+ import yaml
+except ImportError: # pragma: no cover
+ yaml = None
+
+
+DEFAULT_TARGETS = ["openai", "claude", "generic"]
+
+
+def display_path(path: Path, root: Path) -> str:
+ try:
+ return str(path.resolve().relative_to(root.resolve()))
+ except ValueError:
+ return str(path.resolve())
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ if not path.exists():
+ return {}
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except json.JSONDecodeError:
+ return {}
+ return payload if isinstance(payload, dict) else {}
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+ if not path.exists() or yaml is None:
+ return {}
+ try:
+ payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+ except yaml.YAMLError:
+ return {}
+ return payload if isinstance(payload, dict) else {}
+
+
+def expected_capabilities(skill_dir: Path) -> list[str]:
+ trust = load_json(skill_dir / "reports" / "security_trust_report.json")
+ governance = trust.get("permission_governance", {}) if isinstance(trust.get("permission_governance"), dict) else {}
+ required = governance.get("required_capabilities", [])
+ if isinstance(required, list) and required:
+ return sorted(str(item) for item in required)
+ summary = trust.get("summary", {}) if isinstance(trust.get("summary"), dict) else {}
+ candidates = []
+ if int(summary.get("network_script_count", 0) or 0):
+ candidates.append("network")
+ if int(summary.get("file_write_script_count", 0) or 0):
+ candidates.append("file_write")
+ if any(item.get("uses_subprocess") for item in trust.get("scripts", []) if isinstance(item, dict)):
+ candidates.append("subprocess")
+ if int(summary.get("interactive_script_count", 0) or 0):
+ candidates.append("interactive")
+ return sorted(candidates)
+
+
+def add_check(checks: list[dict[str, Any]], failures: list[str], key: str, condition: bool, detail: str) -> None:
+ checks.append({"key": key, "passed": condition, "detail": detail})
+ if not condition:
+ failures.append(detail)
+
+
+def sorted_strings(value: Any) -> list[str]:
+ return sorted(str(item) for item in value) if isinstance(value, list) else []
+
+
+def probe_openai_yaml(package_dir: Path, expected: list[str]) -> tuple[list[dict[str, Any]], list[str]]:
+ checks: list[dict[str, Any]] = []
+ failures: list[str] = []
+ path = package_dir / "targets" / "openai" / "agents" / "openai.yaml"
+ payload = load_yaml(path)
+ permission_contract = payload.get("compatibility", {}).get("permission_contract", {}) if payload else {}
+ add_check(checks, failures, "openai-yaml-present", bool(payload), "OpenAI permission metadata YAML is readable")
+ add_check(
+ checks,
+ failures,
+ "openai-yaml-permissions",
+ sorted_strings(permission_contract.get("declared_capabilities")) == expected,
+ "OpenAI YAML permission contract mirrors expected capabilities",
+ )
+ add_check(
+ checks,
+ failures,
+ "openai-yaml-native-flag",
+ isinstance(permission_contract.get("native_enforcement"), bool),
+ "OpenAI YAML declares native_enforcement as a boolean",
+ )
+ return checks, failures
+
+
+def probe_target(skill_dir: Path, package_dir: Path, target: str, expected: list[str]) -> dict[str, Any]:
+ adapter_path = package_dir / "targets" / target / "adapter.json"
+ checks: list[dict[str, Any]] = []
+ failures: list[str] = []
+ adapter = load_json(adapter_path)
+ add_check(checks, failures, "adapter-present", bool(adapter), f"{target} adapter.json is readable")
+
+ permission_contract = adapter.get("permission_contract", {}) if adapter else {}
+ target_contract = adapter.get("target_permission_contract", {}) if adapter else {}
+ add_check(checks, failures, "permission-contract-present", bool(permission_contract), f"{target} adapter includes permission_contract")
+ add_check(checks, failures, "target-contract-present", bool(target_contract), f"{target} adapter includes target_permission_contract")
+ add_check(
+ checks,
+ failures,
+ "source-available",
+ permission_contract.get("source_available") is True,
+ f"{target} permission_contract links to an available trust report",
+ )
+ add_check(
+ checks,
+ failures,
+ "declared-capabilities-match",
+ sorted_strings(target_contract.get("declared_capabilities")) == expected,
+ f"{target} target_permission_contract mirrors expected capabilities",
+ )
+ add_check(
+ checks,
+ failures,
+ "capability-counts-present",
+ isinstance(target_contract.get("capability_counts"), dict),
+ f"{target} target_permission_contract includes capability_counts",
+ )
+ add_check(
+ checks,
+ failures,
+ "native-enforcement-boolean",
+ isinstance(target_contract.get("native_enforcement"), bool),
+ f"{target} target_permission_contract declares native_enforcement as a boolean",
+ )
+ add_check(
+ checks,
+ failures,
+ "representation-present",
+ bool(str(target_contract.get("representation", "")).strip()),
+ f"{target} target_permission_contract declares where permission metadata is represented",
+ )
+ add_check(
+ checks,
+ failures,
+ "operator-note-present",
+ bool(str(target_contract.get("operator_note", "")).strip()),
+ f"{target} target_permission_contract includes an operator_note",
+ )
+ add_check(
+ checks,
+ failures,
+ "review-required-matches",
+ bool(target_contract.get("review_required")) == bool(expected),
+ f"{target} review_required matches whether capabilities are required",
+ )
+
+ yaml_checks: list[dict[str, Any]] = []
+ yaml_failures: list[str] = []
+ if target == "openai":
+ yaml_checks, yaml_failures = probe_openai_yaml(package_dir, expected)
+ checks.extend(yaml_checks)
+ failures.extend(yaml_failures)
+
+ native = target_contract.get("native_enforcement")
+ metadata_fallback = native is False and bool(target_contract.get("representation")) and bool(target_contract.get("operator_note"))
+ assurance = "native-enforced" if native is True else ("metadata-fallback-explicit" if metadata_fallback else "missing")
+ residual_risks = []
+ if native is False:
+ residual_risks.append("Client-native permission enforcement is not provided by this target; installer or operator must honor metadata.")
+ return {
+ "target": target,
+ "status": "pass" if not failures else "fail",
+ "adapter": display_path(adapter_path, skill_dir),
+ "permission_model": str(target_contract.get("permission_model", "")),
+ "native_enforcement": bool(native) if isinstance(native, bool) else None,
+ "metadata_fallback_explicit": metadata_fallback,
+ "assurance": assurance,
+ "declared_capabilities": sorted_strings(target_contract.get("declared_capabilities")),
+ "checks": checks,
+ "failures": failures,
+ "residual_risks": residual_risks,
+ }
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+ summary = report["summary"]
+ lines = [
+ "# Runtime Permission Probes",
+ "",
+ "Runtime permission probes verify that generated target adapters expose high-permission capabilities and make native-enforcement limits explicit.",
+ "",
+ "## Summary",
+ "",
+ f"- OK: `{report['ok']}`",
+ f"- Targets probed: `{summary['target_count']}`",
+ f"- Passed: `{summary['pass_count']}`",
+ f"- Failed: `{summary['fail_count']}`",
+ f"- Native enforcement targets: `{summary['native_enforcement_count']}`",
+ f"- Explicit metadata fallbacks: `{summary['metadata_fallback_count']}`",
+ f"- Required capabilities: `{', '.join(report['expected_capabilities']) or 'none'}`",
+ "",
+ "| Target | Status | Assurance | Native Enforcement | Metadata Fallback | Residual Risk |",
+ "| --- | --- | --- | --- | --- | --- |",
+ ]
+ for target in report["targets"]:
+ residual = " ".join(target["residual_risks"]) if target["residual_risks"] else "None"
+ lines.append(
+ f"| `{target['target']}` | `{target['status']}` | `{target['assurance']}` | "
+ f"`{target['native_enforcement']}` | `{target['metadata_fallback_explicit']}` | {residual} |"
+ )
+ lines.extend(["", "## Failures", ""])
+ lines.extend([f"- {item}" for item in report["failures"]] or ["- None"])
+ lines.extend(
+ [
+ "",
+ "## Reviewer Note",
+ "",
+ "A passing probe means the target contract is explicit and auditable. It does not claim that a host client enforces permissions natively.",
+ ]
+ )
+ return "\n".join(lines).strip() + "\n"
+
+
+def probe_runtime_permissions(
+ skill_dir: Path,
+ package_dir: Path,
+ targets: list[str],
+ output_json: Path,
+ output_md: Path,
+) -> dict[str, Any]:
+ skill_dir = skill_dir.resolve()
+ package_dir = package_dir.resolve()
+ expected = expected_capabilities(skill_dir)
+ target_results = [probe_target(skill_dir, package_dir, target, expected) for target in targets]
+ failures = [failure for target in target_results for failure in target["failures"]]
+ summary = {
+ "target_count": len(target_results),
+ "pass_count": sum(1 for item in target_results if item["status"] == "pass"),
+ "fail_count": sum(1 for item in target_results if item["status"] == "fail"),
+ "native_enforcement_count": sum(1 for item in target_results if item["native_enforcement"] is True),
+ "metadata_fallback_count": sum(1 for item in target_results if item["metadata_fallback_explicit"]),
+ "residual_risk_count": sum(len(item["residual_risks"]) for item in target_results),
+ "required_capability_count": len(expected),
+ "failure_count": len(failures),
+ }
+ report = {
+ "schema_version": "1.0",
+ "ok": not failures,
+ "skill_dir": display_path(skill_dir, skill_dir),
+ "package_dir": display_path(package_dir, skill_dir),
+ "expected_capabilities": expected,
+ "summary": summary,
+ "targets": target_results,
+ "failures": failures,
+ "artifacts": {
+ "json": display_path(output_json, skill_dir),
+ "markdown": display_path(output_md, skill_dir),
+ },
+ }
+ output_json.parent.mkdir(parents=True, exist_ok=True)
+ output_md.parent.mkdir(parents=True, exist_ok=True)
+ output_json.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ output_md.write_text(render_markdown(report), encoding="utf-8")
+ return report
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Probe generated target adapters for runtime permission enforcement metadata.")
+ parser.add_argument("skill_dir", nargs="?", default=".")
+ parser.add_argument("--package-dir", default="dist")
+ parser.add_argument("--target", action="append", choices=DEFAULT_TARGETS)
+ parser.add_argument("--output-json")
+ parser.add_argument("--output-md")
+ args = parser.parse_args()
+
+ skill_dir = Path(args.skill_dir).resolve()
+ report = probe_runtime_permissions(
+ skill_dir,
+ Path(args.package_dir).resolve(),
+ args.target or DEFAULT_TARGETS,
+ Path(args.output_json).resolve() if args.output_json else skill_dir / "reports" / "runtime_permission_probes.json",
+ Path(args.output_md).resolve() if args.output_md else skill_dir / "reports" / "runtime_permission_probes.md",
+ )
+ print(json.dumps(report, ensure_ascii=False, indent=2))
+ raise SystemExit(0 if report["ok"] else 2)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/registry_audit.py b/scripts/registry_audit.py
new file mode 100644
index 0000000..8f197d2
--- /dev/null
+++ b/scripts/registry_audit.py
@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import re
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+try:
+ import yaml
+except ImportError: # pragma: no cover
+ yaml = None
+
+
+ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_REGISTRY_DIR = ROOT / "registry"
+REQUIRED_PACKAGE_FIELDS = [
+ "name",
+ "version",
+ "description",
+ "targets",
+ "maturity",
+ "owner",
+ "review_cadence",
+ "trust_level",
+ "license",
+]
+
+
+def display_path(path: Path, root: Path = ROOT) -> str:
+ try:
+ return str(path.resolve().relative_to(root.resolve()))
+ except ValueError:
+ return str(path.resolve())
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ if not path.exists():
+ return {}
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except json.JSONDecodeError:
+ return {}
+ return payload if isinstance(payload, dict) else {}
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+ if not path.exists() or yaml is None:
+ return {}
+ payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+ return payload if isinstance(payload, dict) else {}
+
+
+def read_frontmatter(path: Path) -> dict[str, Any]:
+ if not path.exists():
+ return {}
+ text = path.read_text(encoding="utf-8", errors="replace")
+ if not text.startswith("---"):
+ return {}
+ parts = text.split("---", 2)
+ if len(parts) < 3:
+ return {}
+ if yaml is not None:
+ payload = yaml.safe_load(parts[1]) or {}
+ return payload if isinstance(payload, dict) else {}
+ data: dict[str, Any] = {}
+ for line in parts[1].splitlines():
+ if ":" not in line:
+ continue
+ key, value = line.split(":", 1)
+ data[key.strip()] = value.strip().strip('"')
+ return data
+
+
+def find_skill_ir(skill_dir: Path, name: str) -> tuple[dict[str, Any], str]:
+ candidates = [
+ skill_dir / "reports" / "skill-ir.json",
+ skill_dir / "skill-ir" / "examples" / f"{name}.json",
+ skill_dir / "skill-ir" / "examples" / f"{skill_dir.name}.json",
+ ]
+ for path in candidates:
+ payload = load_json(path)
+ if payload:
+ return payload, display_path(path, skill_dir)
+ return {}, "missing"
+
+
+def license_id(skill_dir: Path) -> str:
+ for name in ("LICENSE", "LICENSE.md", "LICENSE.txt"):
+ path = skill_dir / name
+ if not path.exists():
+ continue
+ text = path.read_text(encoding="utf-8", errors="replace")
+ if re.search(r"\bMIT License\b", text, re.IGNORECASE):
+ return "MIT"
+ for line in text.splitlines():
+ value = line.strip()
+ if value:
+ return value[:80]
+ return ""
+
+
+def compatibility_matrix(skill_dir: Path, declared_targets: list[str]) -> dict[str, str]:
+ conformance = load_json(skill_dir / "reports" / "conformance_matrix.json")
+ matrix = {}
+ for target in conformance.get("targets", []):
+ name = str(target.get("target", ""))
+ if name:
+ matrix[name] = str(target.get("status", "unknown"))
+ if "agent-skills-compatible" in declared_targets and "agent-skills" in matrix:
+ matrix["agent-skills-compatible"] = matrix["agent-skills"]
+ for target in declared_targets:
+ matrix.setdefault(str(target), "missing")
+ return matrix
+
+
+def package_hash(skill_dir: Path) -> str:
+ trust = load_json(skill_dir / "reports" / "security_trust_report.json")
+ return str(trust.get("summary", {}).get("package_sha256", ""))
+
+
+def package_verification(skill_dir: Path) -> dict[str, Any]:
+ return load_json(skill_dir / "reports" / "package_verification.json")
+
+
+def install_simulation(skill_dir: Path) -> dict[str, Any]:
+ return load_json(skill_dir / "reports" / "install_simulation.json")
+
+
+def adoption_drift(skill_dir: Path) -> dict[str, Any]:
+ return load_json(skill_dir / "reports" / "adoption_drift_report.json")
+
+
+def review_waivers(skill_dir: Path) -> dict[str, Any]:
+ return load_json(skill_dir / "reports" / "review_waivers.json")
+
+
+def review_annotations(skill_dir: Path) -> dict[str, Any]:
+ return load_json(skill_dir / "reports" / "review_annotations.json")
+
+
+def compiled_targets(skill_dir: Path) -> dict[str, Any]:
+ return load_json(skill_dir / "reports" / "compiled_targets.json")
+
+
+def package_targets(manifest: dict[str, Any], interface_doc: dict[str, Any], ir: dict[str, Any]) -> list[str]:
+ candidates = (
+ manifest.get("target_platforms")
+ or ir.get("targets")
+ or interface_doc.get("compatibility", {}).get("adapter_targets")
+ or []
+ )
+ targets = []
+ for item in candidates:
+ value = str(item).strip()
+ if value and value not in targets:
+ targets.append(value)
+ return targets
+
+
+def build_package_metadata(skill_dir: Path, generated_at: str) -> dict[str, Any]:
+ frontmatter = read_frontmatter(skill_dir / "SKILL.md")
+ manifest = load_json(skill_dir / "manifest.json")
+ interface_doc = load_yaml(skill_dir / "agents" / "interface.yaml")
+ compatibility = interface_doc.get("compatibility", {})
+ trust = compatibility.get("trust", {})
+ name = str(frontmatter.get("name") or manifest.get("name") or skill_dir.name)
+ ir, ir_source = find_skill_ir(skill_dir, name)
+ verification = package_verification(skill_dir)
+ install = install_simulation(skill_dir)
+ adoption = adoption_drift(skill_dir)
+ waivers = review_waivers(skill_dir)
+ annotations = review_annotations(skill_dir)
+ compiled = compiled_targets(skill_dir)
+ archive_sha = str(verification.get("summary", {}).get("archive_sha256", ""))
+ checksums = {"package_sha256": package_hash(skill_dir)}
+ if archive_sha:
+ checksums["archive_sha256"] = archive_sha
+ description = str(
+ ir.get("trigger_surface", {}).get("description")
+ or frontmatter.get("description")
+ or manifest.get("description")
+ or ""
+ )
+ targets = package_targets(manifest, interface_doc, ir)
+ package = {
+ "schema_version": "2.0",
+ "name": name,
+ "version": str(manifest.get("version") or frontmatter.get("version") or ""),
+ "description": description,
+ "targets": targets,
+ "maturity": str(manifest.get("maturity_tier") or manifest.get("lifecycle_stage") or "scaffold"),
+ "owner": str(manifest.get("owner") or ""),
+ "review_cadence": str(manifest.get("review_cadence") or ""),
+ "trust_level": str(trust.get("source_tier") or ""),
+ "license": license_id(skill_dir),
+ "checksums": checksums,
+ "compatibility": compatibility_matrix(skill_dir, targets),
+ "source": {
+ "skill_dir": display_path(skill_dir),
+ "skill_ir": ir_source,
+ "ir_schema_version": str(ir.get("schema_version") or "missing"),
+ "canonical_metadata": "agents/interface.yaml" if (skill_dir / "agents" / "interface.yaml").exists() else "missing",
+ },
+ "artifacts": {
+ "overview_html": "reports/skill-overview.html",
+ "review_studio_html": "reports/review-studio.html",
+ "trust_report": "reports/security_trust_report.md",
+ "conformance_matrix": "reports/conformance_matrix.md",
+ "compiled_targets": "reports/compiled_targets.md" if compiled else "",
+ "package_verification": "reports/package_verification.md" if verification else "",
+ "install_simulation": "reports/install_simulation.md" if install else "",
+ "adoption_drift": "reports/adoption_drift_report.md" if adoption else "",
+ "review_waivers": "reports/review_waivers.md" if waivers else "",
+ "review_annotations": "reports/review_annotations.md" if annotations else "",
+ "package_metadata": f"registry/packages/{name}.json",
+ },
+ "distribution": {
+ "archive_verified": bool(verification.get("ok")) if verification else False,
+ "archive_sha256": archive_sha,
+ "package_verification": "reports/package_verification.json" if verification else "",
+ "install_simulated": bool(install.get("ok")) if install else False,
+ "install_simulation": "reports/install_simulation.json" if install else "",
+ },
+ "generated_at": generated_at,
+ }
+ return package
+
+
+def audit_package(package: dict[str, Any], skill_dir: Path) -> tuple[list[str], list[str]]:
+ failures = []
+ warnings = []
+ for field in REQUIRED_PACKAGE_FIELDS:
+ if not package.get(field):
+ failures.append(f"Missing package metadata field: {field}")
+ if not package.get("checksums", {}).get("package_sha256"):
+ failures.append("Missing package checksum: checksums.package_sha256")
+ if package.get("source", {}).get("ir_schema_version") != "2.0.0":
+ failures.append("Missing valid Skill IR source for registry package")
+ compatibility = package.get("compatibility", {})
+ for target in package.get("targets", []):
+ if compatibility.get(target) not in {"pass", "warn"}:
+ failures.append(f"Compatibility is not passing for target: {target}")
+ for rel in (
+ "reports/skill-overview.html",
+ "reports/review-studio.html",
+ "reports/compiled_targets.md",
+ "reports/security_trust_report.md",
+ "reports/review_waivers.md",
+ "reports/review_annotations.md",
+ ):
+ if not (skill_dir / rel).exists():
+ warnings.append(f"Recommended registry evidence is missing: {rel}")
+ verification = package.get("distribution", {})
+ if verification.get("package_verification") and not verification.get("archive_verified"):
+ failures.append("Package verification report exists but archive verification did not pass")
+ if verification.get("install_simulation") and not verification.get("install_simulated"):
+ failures.append("Install simulation report exists but install simulation did not pass")
+ return failures, warnings
+
+
+def build_index(package: dict[str, Any], generated_at: str) -> dict[str, Any]:
+ return {
+ "schema_version": "2.0",
+ "generated_at": generated_at,
+ "package_count": 1,
+ "packages": [
+ {
+ "name": package["name"],
+ "version": package["version"],
+ "maturity": package["maturity"],
+ "owner": package["owner"],
+ "targets": package["targets"],
+ "package_metadata": package["artifacts"]["package_metadata"],
+ "package_sha256": package["checksums"]["package_sha256"],
+ }
+ ],
+ }
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+ package = report["package"]
+ lines = [
+ "# Registry Audit",
+ "",
+ f"- OK: `{report['ok']}`",
+ f"- Package: `{package['name']}`",
+ f"- Version: `{package['version']}`",
+ f"- Maturity: `{package['maturity']}`",
+ f"- Owner: `{package['owner']}`",
+ f"- License: `{package['license']}`",
+ f"- Package SHA256: `{package['checksums']['package_sha256']}`",
+ f"- Archive SHA256: `{package['checksums'].get('archive_sha256', 'n/a')}`",
+ f"- Install simulated: `{package.get('distribution', {}).get('install_simulated', False)}`",
+ "",
+ "## Compatibility",
+ "",
+ "| Target | Status |",
+ "| --- | --- |",
+ ]
+ for target, status in package["compatibility"].items():
+ lines.append(f"| `{target}` | `{status}` |")
+ lines.extend(["", "## Failures", ""])
+ lines.extend([f"- {item}" for item in report["failures"]] or ["- None"])
+ lines.extend(["", "## Warnings", ""])
+ lines.extend([f"- {item}" for item in report["warnings"]] or ["- None"])
+ lines.extend(["", "## Artifacts", ""])
+ for key, value in report["artifacts"].items():
+ lines.append(f"- {key}: `{value}`")
+ return "\n".join(lines) + "\n"
+
+
+def run_registry_audit(
+ skill_dir: Path,
+ registry_dir: Path,
+ output_json: Path,
+ output_md: Path,
+ generated_at: str,
+) -> dict[str, Any]:
+ skill_dir = skill_dir.resolve()
+ registry_dir = registry_dir.resolve()
+ package = build_package_metadata(skill_dir, generated_at)
+ failures, warnings = audit_package(package, skill_dir)
+ index = build_index(package, generated_at)
+
+ package_dir = registry_dir / "packages"
+ package_path = package_dir / f"{package['name']}.json"
+ index_path = registry_dir / "index.json"
+ package_dir.mkdir(parents=True, exist_ok=True)
+ output_json.parent.mkdir(parents=True, exist_ok=True)
+ output_md.parent.mkdir(parents=True, exist_ok=True)
+ package_path.write_text(json.dumps(package, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ index_path.write_text(json.dumps(index, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+ report = {
+ "ok": not failures,
+ "schema_version": "2.0",
+ "skill_dir": display_path(skill_dir),
+ "registry_dir": display_path(registry_dir),
+ "package": package,
+ "index": index,
+ "failures": failures,
+ "warnings": warnings,
+ "artifacts": {
+ "index": display_path(index_path),
+ "package": display_path(package_path),
+ "json": display_path(output_json),
+ "markdown": display_path(output_md),
+ },
+ }
+ output_json.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ output_md.write_text(render_markdown(report), encoding="utf-8")
+ return report
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Build and audit Skill OS registry package metadata.")
+ parser.add_argument("skill_dir", nargs="?", default=".")
+ parser.add_argument("--registry-dir", default=str(DEFAULT_REGISTRY_DIR))
+ parser.add_argument("--output-json", default="reports/registry_audit.json")
+ parser.add_argument("--output-md", default="reports/registry_audit.md")
+ parser.add_argument("--generated-at", default=str(date.today()))
+ args = parser.parse_args()
+
+ payload = run_registry_audit(
+ Path(args.skill_dir),
+ Path(args.registry_dir),
+ Path(args.output_json),
+ Path(args.output_md),
+ args.generated_at,
+ )
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+ raise SystemExit(0 if payload["ok"] else 2)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/render_adoption_drift_report.py b/scripts/render_adoption_drift_report.py
new file mode 100644
index 0000000..9ba81aa
--- /dev/null
+++ b/scripts/render_adoption_drift_report.py
@@ -0,0 +1,441 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parent.parent
+
+ALLOWED_EVENTS = {"skill_activation", "skill_output", "script_run", "review_event"}
+ALLOWED_ACTIVATION_TYPES = {"implicit", "explicit", "manual", "unknown"}
+ALLOWED_OUTCOMES = {"accepted", "edited", "rejected", "missed", "failed", "reviewed", "unknown"}
+ALLOWED_FAILURE_TYPES = {
+ "none",
+ "wrong_trigger",
+ "under_trigger",
+ "bad_output",
+ "missing_resource",
+ "script_error",
+ "review_overdue",
+}
+ALLOWED_FIELDS = {
+ "event",
+ "skill",
+ "version",
+ "activation_type",
+ "outcome",
+ "failure_type",
+ "timestamp",
+}
+SENSITIVE_FIELDS = {
+ "prompt",
+ "content",
+ "input",
+ "inputs",
+ "output",
+ "outputs",
+ "transcript",
+ "message",
+ "messages",
+ "note",
+ "text",
+ "raw",
+}
+
+
+def display_path(path: Path, root: Path = ROOT) -> str:
+ try:
+ return str(path.resolve().relative_to(root.resolve()))
+ except ValueError:
+ return str(path.resolve())
+
+
+def load_json(path: Path) -> dict[str, Any]:
+ if not path.exists():
+ return {}
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except json.JSONDecodeError:
+ return {}
+ return payload if isinstance(payload, dict) else {}
+
+
+def read_frontmatter(path: Path) -> dict[str, str]:
+ if not path.exists():
+ return {}
+ text = path.read_text(encoding="utf-8", errors="replace")
+ if not text.startswith("---"):
+ return {}
+ parts = text.split("---", 2)
+ if len(parts) < 3:
+ return {}
+ data: dict[str, str] = {}
+ for line in parts[1].splitlines():
+ if ":" not in line:
+ continue
+ key, value = line.split(":", 1)
+ data[key.strip()] = value.strip().strip('"')
+ return data
+
+
+def skill_defaults(skill_dir: Path) -> dict[str, str]:
+ manifest = load_json(skill_dir / "manifest.json")
+ frontmatter = read_frontmatter(skill_dir / "SKILL.md")
+ return {
+ "skill": str(manifest.get("name") or frontmatter.get("name") or skill_dir.name),
+ "version": str(manifest.get("version") or frontmatter.get("version") or "0.0.0"),
+ }
+
+
+def utc_now() -> str:
+ return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def normalize_event(raw: dict[str, Any], defaults: dict[str, str], line_label: str) -> tuple[dict[str, str] | None, list[str]]:
+ failures: list[str] = []
+ raw_keys = set(raw.keys())
+ sensitive = sorted(raw_keys & SENSITIVE_FIELDS)
+ if sensitive:
+ failures.append(f"{line_label}: raw content fields are not allowed in telemetry: {', '.join(sensitive)}")
+ unknown = sorted(raw_keys - ALLOWED_FIELDS - SENSITIVE_FIELDS)
+ if unknown:
+ failures.append(f"{line_label}: unknown telemetry fields are blocked by the metadata-only contract: {', '.join(unknown)}")
+
+ event = str(raw.get("event") or "skill_activation")
+ activation_type = str(raw.get("activation_type") or "unknown")
+ outcome = str(raw.get("outcome") or "unknown")
+ failure_type = str(raw.get("failure_type") or "none")
+ timestamp = str(raw.get("timestamp") or utc_now())
+ skill = str(raw.get("skill") or defaults["skill"])
+ version = str(raw.get("version") or defaults["version"])
+
+ if event not in ALLOWED_EVENTS:
+ failures.append(f"{line_label}: unsupported event `{event}`")
+ if activation_type not in ALLOWED_ACTIVATION_TYPES:
+ failures.append(f"{line_label}: unsupported activation_type `{activation_type}`")
+ if outcome not in ALLOWED_OUTCOMES:
+ failures.append(f"{line_label}: unsupported outcome `{outcome}`")
+ if failure_type not in ALLOWED_FAILURE_TYPES:
+ failures.append(f"{line_label}: unsupported failure_type `{failure_type}`")
+
+ if failures:
+ return None, failures
+ return {
+ "event": event,
+ "skill": skill,
+ "version": version,
+ "activation_type": activation_type,
+ "outcome": outcome,
+ "failure_type": failure_type,
+ "timestamp": timestamp,
+ }, []
+
+
+def load_events(path: Path, defaults: dict[str, str]) -> tuple[list[dict[str, str]], list[str]]:
+ if not path.exists():
+ return [], []
+ events: list[dict[str, str]] = []
+ failures: list[str] = []
+ for index, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+ if not line.strip():
+ continue
+ try:
+ raw = json.loads(line)
+ except json.JSONDecodeError as exc:
+ failures.append(f"line {index}: invalid JSONL event: {exc.msg}")
+ continue
+ if not isinstance(raw, dict):
+ failures.append(f"line {index}: telemetry event must be a JSON object")
+ continue
+ event, event_failures = normalize_event(raw, defaults, f"line {index}")
+ failures.extend(event_failures)
+ if event:
+ events.append(event)
+ return events, failures
+
+
+def append_event(path: Path, event: dict[str, str]) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with path.open("a", encoding="utf-8") as handle:
+ handle.write(json.dumps(event, ensure_ascii=False, sort_keys=True) + "\n")
+
+
+def adoption_by_skill(events: list[dict[str, str]]) -> list[dict[str, Any]]:
+ grouped: dict[str, Counter[str]] = defaultdict(Counter)
+ for event in events:
+ grouped[event["skill"]][event["outcome"]] += 1
+ rows = []
+ for skill, counts in sorted(grouped.items()):
+ total = sum(counts.values())
+ adopted = counts["accepted"] + counts["edited"]
+ rows.append(
+ {
+ "skill": skill,
+ "events": total,
+ "accepted": counts["accepted"],
+ "edited": counts["edited"],
+ "rejected": counts["rejected"],
+ "missed": counts["missed"],
+ "adoption_rate": round(adopted / total * 100, 1) if total else 0,
+ }
+ )
+ return rows
+
+
+def atlas_review_overdue(skill_dir: Path) -> int:
+ atlas = load_json(skill_dir / "reports" / "skill_atlas.json")
+ stale = atlas.get("stale_skills", []) if isinstance(atlas.get("stale_skills"), list) else []
+ return sum(
+ 1
+ for item in stale
+ if item.get("actionable", True) and "overdue" in str(item.get("reason", "")).lower()
+ )
+
+
+def next_candidates(summary: dict[str, Any]) -> list[dict[str, str]]:
+ candidates: list[dict[str, str]] = []
+ if summary["event_count"] == 0:
+ candidates.append(
+ {
+ "signal": "no telemetry",
+ "recommendation": "Start with a small metadata-only sample before using telemetry for release decisions.",
+ }
+ )
+ if summary["missed_trigger_count"]:
+ candidates.append(
+ {
+ "signal": "missed trigger",
+ "recommendation": "Add missed prompts to trigger eval and tighten should-trigger examples.",
+ }
+ )
+ if summary["wrong_trigger_count"]:
+ candidates.append(
+ {
+ "signal": "wrong trigger",
+ "recommendation": "Add near-neighbor should-not-trigger cases and clarify exclusions.",
+ }
+ )
+ if summary["bad_output_count"]:
+ candidates.append(
+ {
+ "signal": "bad output",
+ "recommendation": "Convert the failed output shape into an Output Eval assertion and failure taxonomy entry.",
+ }
+ )
+ if summary["script_error_count"]:
+ candidates.append(
+ {
+ "signal": "script error",
+ "recommendation": "Add non-interactive script smoke tests and clearer error paths.",
+ }
+ )
+ if summary["review_overdue_count"]:
+ candidates.append(
+ {
+ "signal": "review overdue",
+ "recommendation": "Prioritize stale governed skills in Skill Atlas before creating more assets.",
+ }
+ )
+ return candidates[:6]
+
+
+def summarize(events: list[dict[str, str]], review_overdue_count: int) -> dict[str, Any]:
+ outcomes = Counter(event["outcome"] for event in events)
+ failures = Counter(event["failure_type"] for event in events if event["failure_type"] != "none")
+ event_types = Counter(event["event"] for event in events)
+ adopted = outcomes["accepted"] + outcomes["edited"]
+ event_count = len(events)
+ missed_trigger = outcomes["missed"] + failures["under_trigger"]
+ bad_output = failures["bad_output"]
+ script_error = failures["script_error"]
+ wrong_trigger = failures["wrong_trigger"]
+ risk_band = "no-data"
+ if event_count:
+ risk_points = missed_trigger + bad_output + script_error + wrong_trigger + review_overdue_count
+ if risk_points >= 4:
+ risk_band = "high"
+ elif risk_points:
+ risk_band = "medium"
+ else:
+ risk_band = "low"
+ return {
+ "event_count": event_count,
+ "activation_count": event_types["skill_activation"],
+ "accepted_count": outcomes["accepted"],
+ "edited_count": outcomes["edited"],
+ "rejected_count": outcomes["rejected"],
+ "missed_count": outcomes["missed"],
+ "failed_count": outcomes["failed"],
+ "adoption_rate": round(adopted / event_count * 100, 1) if event_count else 0,
+ "missed_trigger_count": missed_trigger,
+ "wrong_trigger_count": wrong_trigger,
+ "bad_output_count": bad_output,
+ "script_error_count": script_error,
+ "missing_resource_count": failures["missing_resource"],
+ "review_overdue_count": review_overdue_count + failures["review_overdue"],
+ "risk_band": risk_band,
+ "event_types": dict(sorted(event_types.items())),
+ "failure_types": dict(sorted(failures.items())),
+ }
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+ summary = report["summary"]
+ lines = [
+ "# Adoption And Drift Report",
+ "",
+ "Local-first, metadata-only telemetry for skill operations. Raw prompts, outputs, transcripts, and notes are not allowed in the event stream.",
+ "",
+ "## Summary",
+ "",
+ f"- Events: `{summary['event_count']}`",
+ f"- Activation events: `{summary['activation_count']}`",
+ f"- Adoption rate: `{summary['adoption_rate']}`",
+ f"- Missed trigger signals: `{summary['missed_trigger_count']}`",
+ f"- Bad output signals: `{summary['bad_output_count']}`",
+ f"- Script error signals: `{summary['script_error_count']}`",
+ f"- Review overdue signals: `{summary['review_overdue_count']}`",
+ f"- Risk band: `{summary['risk_band']}`",
+ "",
+ "## Privacy Contract",
+ "",
+ "- Storage is local-first.",
+ "- Events are metadata-only.",
+ "- Raw user prompts, model outputs, transcripts, notes, and messages are blocked.",
+ "- Distributed packages should include this aggregate report, not raw `reports/telemetry_events.jsonl`.",
+ "",
+ "## Adoption By Skill",
+ "",
+ "| Skill | Events | Accepted | Edited | Rejected | Missed | Adoption Rate |",
+ "| --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+ ]
+ for row in report["adoption_by_skill"]:
+ lines.append(
+ f"| `{row['skill']}` | {row['events']} | {row['accepted']} | {row['edited']} | "
+ f"{row['rejected']} | {row['missed']} | {row['adoption_rate']} |"
+ )
+ if not report["adoption_by_skill"]:
+ lines.append("| `none` | 0 | 0 | 0 | 0 | 0 | 0 |")
+ lines.extend(["", "## Next Iteration Candidates", ""])
+ for item in report["next_iteration_candidates"]:
+ lines.append(f"- `{item['signal']}`: {item['recommendation']}")
+ if not report["next_iteration_candidates"]:
+ lines.append("- No telemetry-driven iteration candidate yet.")
+ lines.extend(["", "## Recent Metadata Events", ""])
+ for event in report["recent_events"]:
+ lines.append(
+ f"- `{event['timestamp']}` `{event['skill']}` event=`{event['event']}` "
+ f"activation=`{event['activation_type']}` outcome=`{event['outcome']}` failure=`{event['failure_type']}`"
+ )
+ if not report["recent_events"]:
+ lines.append("- No metadata events captured yet.")
+ if report["failures"]:
+ lines.extend(["", "## Validation Failures", ""])
+ lines.extend([f"- {item}" for item in report["failures"]])
+ return "\n".join(lines) + "\n"
+
+
+def render_report(
+ skill_dir: Path,
+ events_jsonl: Path | None = None,
+ output_json: Path | None = None,
+ output_md: Path | None = None,
+ generated_at: str | None = None,
+ record_event: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+ skill_dir = skill_dir.resolve()
+ reports_dir = skill_dir / "reports"
+ reports_dir.mkdir(parents=True, exist_ok=True)
+ defaults = skill_defaults(skill_dir)
+ events_jsonl = events_jsonl or reports_dir / "telemetry_events.jsonl"
+ output_json = output_json or reports_dir / "adoption_drift_report.json"
+ output_md = output_md or reports_dir / "adoption_drift_report.md"
+ generated_at = generated_at or utc_now()
+ failures: list[str] = []
+
+ if record_event is not None:
+ event, event_failures = normalize_event(record_event, defaults, "record")
+ failures.extend(event_failures)
+ if event:
+ append_event(events_jsonl, event)
+
+ events, load_failures = load_events(events_jsonl, defaults)
+ failures.extend(load_failures)
+ summary = summarize(events, atlas_review_overdue(skill_dir))
+ report = {
+ "ok": not failures,
+ "schema_version": "2.0",
+ "generated_at": generated_at,
+ "skill_dir": display_path(skill_dir),
+ "privacy_contract": {
+ "storage": "local-first",
+ "event_scope": "metadata-only",
+ "raw_content_allowed": False,
+ "raw_event_log_packaged": False,
+ "blocked_fields": sorted(SENSITIVE_FIELDS),
+ },
+ "summary": summary,
+ "adoption_by_skill": adoption_by_skill(events),
+ "next_iteration_candidates": next_candidates(summary),
+ "recent_events": events[-10:],
+ "failures": failures,
+ "artifacts": {
+ "events_jsonl": display_path(events_jsonl),
+ "json": display_path(output_json),
+ "markdown": display_path(output_md),
+ },
+ }
+ output_json.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ output_md.write_text(render_markdown(report), encoding="utf-8")
+ return report
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Render local-first adoption and drift telemetry for a skill package.")
+ parser.add_argument("skill_dir", nargs="?", default=".")
+ parser.add_argument("--events-jsonl")
+ parser.add_argument("--output-json")
+ parser.add_argument("--output-md")
+ parser.add_argument("--generated-at")
+ parser.add_argument("--record-event", choices=sorted(ALLOWED_EVENTS))
+ parser.add_argument("--activation-type", choices=sorted(ALLOWED_ACTIVATION_TYPES), default="unknown")
+ parser.add_argument("--outcome", choices=sorted(ALLOWED_OUTCOMES), default="unknown")
+ parser.add_argument("--failure-type", choices=sorted(ALLOWED_FAILURE_TYPES), default="none")
+ parser.add_argument("--timestamp")
+ parser.add_argument("--skill-name")
+ parser.add_argument("--version")
+ args = parser.parse_args()
+
+ record_event = None
+ if args.record_event:
+ record_event = {
+ "event": args.record_event,
+ "activation_type": args.activation_type,
+ "outcome": args.outcome,
+ "failure_type": args.failure_type,
+ }
+ if args.timestamp:
+ record_event["timestamp"] = args.timestamp
+ if args.skill_name:
+ record_event["skill"] = args.skill_name
+ if args.version:
+ record_event["version"] = args.version
+
+ report = render_report(
+ Path(args.skill_dir),
+ events_jsonl=Path(args.events_jsonl).resolve() if args.events_jsonl else None,
+ output_json=Path(args.output_json).resolve() if args.output_json else None,
+ output_md=Path(args.output_md).resolve() if args.output_md else None,
+ generated_at=args.generated_at,
+ record_event=record_event,
+ )
+ print(json.dumps(report, ensure_ascii=False, indent=2))
+ if not report["ok"]:
+ raise SystemExit(2)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/render_context_reports.py b/scripts/render_context_reports.py
index fc82285..ea57191 100644
--- a/scripts/render_context_reports.py
+++ b/scripts/render_context_reports.py
@@ -1,4 +1,5 @@
#!/usr/bin/env python3
+import argparse
import json
from pathlib import Path
@@ -25,7 +26,18 @@ TARGETS = [
]
+def parse_args() -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description="Render context budget reports for root and example skills.")
+ parser.add_argument(
+ "--generated-at",
+ default="2026-03-31",
+ help="Report date written to context_budget_summary.json.",
+ )
+ return parser.parse_args()
+
+
def main() -> None:
+ args = parse_args()
rows = []
for target in TARGETS:
report = analyze_skill(target["path"])
@@ -48,7 +60,7 @@ def main() -> None:
)
summary = {
- "generated_at": "2026-03-31",
+ "generated_at": args.generated_at,
"targets": rows,
}
(ROOT / "reports").mkdir(parents=True, exist_ok=True)
diff --git a/scripts/render_review_annotations.py b/scripts/render_review_annotations.py
new file mode 100644
index 0000000..58dbe68
--- /dev/null
+++ b/scripts/render_review_annotations.py
@@ -0,0 +1,399 @@
+#!/usr/bin/env python3
+import argparse
+import hashlib
+import json
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_SOURCE = ROOT / "reports" / "review_annotations_input.json"
+DEFAULT_OUTPUT_JSON = ROOT / "reports" / "review_annotations.json"
+DEFAULT_OUTPUT_MD = ROOT / "reports" / "review_annotations.md"
+VALID_GATES = {
+ "intent-canvas",
+ "trigger-lab",
+ "output-lab",
+ "context-budget",
+ "runtime-matrix",
+ "trust-report",
+ "permission-gates",
+ "permission-runtime",
+ "skill-atlas",
+ "operations-loop",
+ "review-waivers",
+ "registry-audit",
+ "release-notes",
+}
+VALID_SEVERITIES = {"info", "note", "warning", "blocker"}
+VALID_STATUSES = {"open", "resolved", "deferred"}
+
+
+def display_path(root: Path, path: Path) -> str:
+ try:
+ return str(path.resolve().relative_to(root.resolve()))
+ except ValueError:
+ try:
+ return str(path.resolve().relative_to(ROOT.resolve()))
+ except ValueError:
+ return str(path.resolve())
+
+
+def load_json(path: Path) -> tuple[dict[str, Any], list[str]]:
+ if not path.exists():
+ return {"schema_version": "1.0", "annotations": []}, []
+ try:
+ payload = json.loads(path.read_text(encoding="utf-8"))
+ except json.JSONDecodeError as exc:
+ return {"schema_version": "1.0", "annotations": []}, [f"Invalid annotation JSON {display_path(ROOT, path)}: {exc}"]
+ if not isinstance(payload, dict):
+ return {"schema_version": "1.0", "annotations": []}, [f"Annotation file root must be an object: {display_path(ROOT, path)}"]
+ if not isinstance(payload.get("annotations", []), list):
+ return {"schema_version": "1.0", "annotations": []}, ["annotations must be a list"]
+ return payload, []
+
+
+def template_payload() -> dict[str, Any]:
+ return {
+ "schema_version": "1.0",
+ "review_contract": {
+ "gate_key": "One Review Studio gate key, such as output-lab or trust-report.",
+ "target_path": "Relative path to the source or report being annotated.",
+ "line": "Optional positive integer line number.",
+ "severity": "info | note | warning | blocker.",
+ "status": "open | resolved | deferred.",
+ "body": "Reviewer-visible annotation text.",
+ },
+ "annotations": [],
+ }
+
+
+def annotation_id(annotation: dict[str, Any]) -> str:
+ if annotation.get("id"):
+ return str(annotation["id"])
+ raw = "|".join(
+ [
+ str(annotation.get("gate_key", "")),
+ str(annotation.get("target_path", "")),
+ str(annotation.get("line", "")),
+ str(annotation.get("body", "")),
+ ]
+ )
+ return "ann-" + hashlib.sha256(raw.encode("utf-8")).hexdigest()[:12]
+
+
+def source_excerpt(path: Path, line: int | None) -> str:
+ if line is None or not path.exists() or not path.is_file():
+ return ""
+ try:
+ lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+ except OSError:
+ return ""
+ if line < 1 or line > len(lines):
+ return ""
+ return lines[line - 1].strip()[:220]
+
+
+def normalize_annotation(skill_dir: Path, raw: dict[str, Any], index: int) -> tuple[dict[str, Any], list[str]]:
+ failures: list[str] = []
+ if not isinstance(raw, dict):
+ return {}, [f"annotation #{index} must be an object"]
+
+ gate_key = str(raw.get("gate_key", "")).strip()
+ if gate_key not in VALID_GATES:
+ failures.append(f"{annotation_id(raw)}: invalid gate_key {gate_key!r}")
+
+ severity = str(raw.get("severity", "note")).strip().lower()
+ if severity not in VALID_SEVERITIES:
+ failures.append(f"{annotation_id(raw)}: invalid severity {severity!r}")
+
+ status = str(raw.get("status", "open")).strip().lower()
+ if status not in VALID_STATUSES:
+ failures.append(f"{annotation_id(raw)}: invalid status {status!r}")
+
+ body = str(raw.get("body", "")).strip()
+ if not body:
+ failures.append(f"{annotation_id(raw)}: body is required")
+
+ target_path = str(raw.get("target_path", "")).strip()
+ if not target_path:
+ failures.append(f"{annotation_id(raw)}: target_path is required")
+ rel = Path(target_path)
+ if rel.is_absolute():
+ failures.append(f"{annotation_id(raw)}: target_path must be relative")
+ target = skill_dir / "__invalid_absolute_path__"
+ else:
+ target = (skill_dir / rel).resolve()
+ try:
+ target.relative_to(skill_dir.resolve())
+ except ValueError:
+ failures.append(f"{annotation_id(raw)}: target_path escapes skill directory")
+ target = skill_dir / "__invalid_escaped_path__"
+
+ line_value = raw.get("line", None)
+ line: int | None
+ if line_value is None or line_value == "":
+ line = None
+ else:
+ try:
+ line = int(line_value)
+ except (TypeError, ValueError):
+ line = None
+ failures.append(f"{annotation_id(raw)}: line must be a positive integer")
+ else:
+ if line < 1:
+ failures.append(f"{annotation_id(raw)}: line must be a positive integer")
+
+ normalized = {
+ "id": annotation_id(raw),
+ "gate_key": gate_key,
+ "target_path": target_path,
+ "line": line,
+ "severity": severity,
+ "status": status,
+ "reviewer": str(raw.get("reviewer", "")).strip(),
+ "created_at": str(raw.get("created_at", "")).strip(),
+ "body": body,
+ "suggested_action": str(raw.get("suggested_action", "")).strip(),
+ "evidence": str(raw.get("evidence", "")).strip(),
+ "target_exists": target.exists(),
+ "source_excerpt": source_excerpt(target, line),
+ }
+ return normalized, failures
+
+
+def append_annotation(source: dict[str, Any], args: argparse.Namespace) -> dict[str, Any]:
+ annotations = list(source.get("annotations", []))
+ raw = {
+ "id": args.annotation_id,
+ "gate_key": args.gate_key,
+ "target_path": args.target_path,
+ "line": args.line,
+ "severity": args.severity,
+ "status": args.status,
+ "reviewer": args.reviewer,
+ "created_at": args.created_at or str(date.today()),
+ "body": args.body,
+ "suggested_action": args.suggested_action,
+ "evidence": args.evidence,
+ }
+ annotations.append({key: value for key, value in raw.items() if value is not None and value != ""})
+ updated = dict(source)
+ updated["annotations"] = annotations
+ updated.setdefault("schema_version", "1.0")
+ return updated
+
+
+def build_summary(annotations: list[dict[str, Any]], failures: list[str]) -> dict[str, Any]:
+ open_items = [item for item in annotations if item["status"] == "open"]
+ resolved_items = [item for item in annotations if item["status"] == "resolved"]
+ deferred_items = [item for item in annotations if item["status"] == "deferred"]
+ open_blockers = [item for item in open_items if item["severity"] == "blocker"]
+ open_warnings = [item for item in open_items if item["severity"] == "warning"]
+ return {
+ "annotation_count": len(annotations),
+ "open_count": len(open_items),
+ "resolved_count": len(resolved_items),
+ "deferred_count": len(deferred_items),
+ "open_blocker_count": len(open_blockers),
+ "open_warning_count": len(open_warnings),
+ "linked_gate_count": len({item["gate_key"] for item in annotations if item["gate_key"]}),
+ "target_missing_count": sum(1 for item in annotations if not item["target_exists"]),
+ "failure_count": len(failures),
+ }
+
+
+def render_markdown(payload: dict[str, Any]) -> str:
+ summary = payload["summary"]
+ lines = [
+ "# Review Annotations",
+ "",
+ "This report renders reviewer annotations attached to Review Studio gates and source/report paths.",
+ "",
+ f"- Annotations: `{summary['annotation_count']}`",
+ f"- Open: `{summary['open_count']}`",
+ f"- Resolved: `{summary['resolved_count']}`",
+ f"- Deferred: `{summary['deferred_count']}`",
+ f"- Open blockers: `{summary['open_blocker_count']}`",
+ f"- Open warnings: `{summary['open_warning_count']}`",
+ "",
+ ]
+ if not payload["annotations"]:
+ lines.extend(["No reviewer annotations recorded yet.", ""])
+ else:
+ lines.extend(
+ [
+ "## Annotation Ledger",
+ "",
+ "| ID | Gate | Severity | Status | Target | Reviewer | Note |",
+ "| --- | --- | --- | --- | --- | --- | --- |",
+ ]
+ )
+ for item in payload["annotations"]:
+ line = f":{item['line']}" if item.get("line") else ""
+ note = item["body"].replace("|", "\\|")
+ lines.append(
+ f"| {item['id']} | {item['gate_key']} | {item['severity']} | {item['status']} | "
+ f"{item['target_path']}{line} | {item.get('reviewer', '')} | {note} |"
+ )
+ if item.get("source_excerpt"):
+ excerpt = str(item["source_excerpt"]).replace("|", "\\|")
+ lines.append(f"| | | | | | excerpt | `{excerpt}` |")
+ if payload.get("failures"):
+ lines.extend(["", "## Failures", ""])
+ for failure in payload["failures"]:
+ lines.append(f"- {failure}")
+ lines.extend(
+ [
+ "",
+ "## Review Rule",
+ "",
+ "- Use annotations for reviewer comments tied to a gate or source line.",
+ "- Use waivers only for explicit acceptance of warning-level release risk.",
+ "- Open blocker annotations should block a release decision until resolved or deferred with rationale.",
+ ]
+ )
+ return "\n".join(lines).strip() + "\n"
+
+
+def render_review_annotations(
+ skill_dir: Path,
+ source_json: Path,
+ output_json: Path,
+ output_md: Path,
+ args: argparse.Namespace,
+) -> dict[str, Any]:
+ skill_dir = skill_dir.resolve()
+ source, failures = load_json(source_json)
+ template_written = False
+ should_write_source = False
+ if args.write_template and not source_json.exists():
+ source_json.parent.mkdir(parents=True, exist_ok=True)
+ source_json.write_text(json.dumps(template_payload(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ source = template_payload()
+ template_written = True
+ if args.add_annotation:
+ source = append_annotation(source, args)
+ should_write_source = True
+
+ annotations: list[dict[str, Any]] = []
+ seen = set()
+ for index, raw in enumerate(source.get("annotations", []), start=1):
+ normalized, item_failures = normalize_annotation(skill_dir, raw, index)
+ failures.extend(item_failures)
+ if normalized:
+ if normalized["id"] in seen:
+ failures.append(f"{normalized['id']}: duplicate annotation id")
+ seen.add(normalized["id"])
+ annotations.append(normalized)
+
+ summary = build_summary(annotations, failures)
+ if should_write_source and not failures:
+ source_json.parent.mkdir(parents=True, exist_ok=True)
+ source_json.write_text(json.dumps(source, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ payload = {
+ "schema_version": "1.0",
+ "ok": not failures,
+ "skill_dir": display_path(ROOT, skill_dir),
+ "source": display_path(skill_dir, source_json),
+ "summary": summary,
+ "annotations": annotations,
+ "failures": failures,
+ "template_written": template_written,
+ "artifacts": {
+ "json": display_path(skill_dir, output_json),
+ "markdown": display_path(skill_dir, output_md),
+ },
+ }
+ output_json.parent.mkdir(parents=True, exist_ok=True)
+ output_md.parent.mkdir(parents=True, exist_ok=True)
+ output_json.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ output_md.write_text(render_markdown(payload), encoding="utf-8")
+ return payload
+
+
+def render_report(
+ skill_dir: Path,
+ annotations_json: Path | None = None,
+ output_json: Path | None = None,
+ output_md: Path | None = None,
+) -> dict[str, Any]:
+ skill_dir = skill_dir.resolve()
+ args = argparse.Namespace(
+ write_template=False,
+ add_annotation=False,
+ annotation_id=None,
+ gate_key=None,
+ target_path=None,
+ line=None,
+ severity="note",
+ status="open",
+ reviewer=None,
+ created_at=None,
+ body=None,
+ suggested_action=None,
+ evidence=None,
+ )
+ return render_review_annotations(
+ skill_dir,
+ annotations_json or skill_dir / "reports" / "review_annotations_input.json",
+ output_json or skill_dir / "reports" / "review_annotations.json",
+ output_md or skill_dir / "reports" / "review_annotations.md",
+ args,
+ )
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Render reviewer annotations for Review Studio gates and source paths.")
+ parser.add_argument("skill_dir", nargs="?", default=".")
+ parser.add_argument("--annotations-json")
+ parser.add_argument("--output-json")
+ parser.add_argument("--output-md")
+ parser.add_argument("--write-template", action="store_true")
+ parser.add_argument("--add-annotation", action="store_true")
+ parser.add_argument("--annotation-id")
+ parser.add_argument("--gate-key", choices=sorted(VALID_GATES))
+ parser.add_argument("--target-path")
+ parser.add_argument("--line", type=int)
+ parser.add_argument("--severity", choices=sorted(VALID_SEVERITIES), default="note")
+ parser.add_argument("--status", choices=sorted(VALID_STATUSES), default="open")
+ parser.add_argument("--reviewer")
+ parser.add_argument("--created-at")
+ parser.add_argument("--body")
+ parser.add_argument("--suggested-action")
+ parser.add_argument("--evidence")
+ args = parser.parse_args()
+
+ skill_dir = Path(args.skill_dir).resolve()
+ annotations_json = Path(args.annotations_json).resolve() if args.annotations_json else skill_dir / "reports" / "review_annotations_input.json"
+ output_json = Path(args.output_json).resolve() if args.output_json else skill_dir / "reports" / "review_annotations.json"
+ output_md = Path(args.output_md).resolve() if args.output_md else skill_dir / "reports" / "review_annotations.md"
+
+ if args.add_annotation:
+ missing = [name for name in ("gate_key", "target_path", "body") if not getattr(args, name)]
+ if missing:
+ payload = {
+ "schema_version": "1.0",
+ "ok": False,
+ "skill_dir": display_path(ROOT, skill_dir),
+ "source": display_path(skill_dir, annotations_json),
+ "summary": build_summary([], missing),
+ "annotations": [],
+ "failures": [f"--add-annotation requires {', '.join(missing)}"],
+ "template_written": False,
+ "artifacts": {
+ "json": display_path(skill_dir, output_json),
+ "markdown": display_path(skill_dir, output_md),
+ },
+ }
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+ raise SystemExit(2)
+
+ payload = render_review_annotations(skill_dir, annotations_json, output_json, output_md, args)
+ print(json.dumps(payload, ensure_ascii=False, indent=2))
+ raise SystemExit(0 if payload["ok"] else 2)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/render_review_studio.py b/scripts/render_review_studio.py
index 6ce6f77..1c1b7cf 100644
--- a/scripts/render_review_studio.py
+++ b/scripts/render_review_studio.py
@@ -11,6 +11,13 @@ try:
except ImportError: # pragma: no cover
yaml = None
+try:
+ from trust_check import permission_governance_status as compute_permission_governance_status
+ from trust_check import script_inventory as trust_script_inventory
+except ImportError: # pragma: no cover
+ compute_permission_governance_status = None
+ trust_script_inventory = None
+
ROOT = Path(__file__).resolve().parent.parent
@@ -72,6 +79,48 @@ def report_link(output_html: Path, skill_dir: Path, rel_path: str) -> str:
return link_from(output_html, skill_dir / rel_path)
+def find_line(path: Path, patterns: list[str] | None = None) -> int | None:
+ if not path.exists():
+ return None
+ if not patterns:
+ return 1
+ try:
+ lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+ except OSError:
+ return 1
+ for pattern in patterns:
+ for index, line in enumerate(lines, start=1):
+ if pattern in line:
+ return index
+ return 1
+
+
+def source_refs(
+ skill_dir: Path,
+ output_html: Path,
+ specs: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+ refs: list[dict[str, Any]] = []
+ for spec in specs:
+ rel_path = str(spec.get("path", "")).strip()
+ if not rel_path:
+ continue
+ path = skill_dir / rel_path
+ exists = path.exists()
+ line = find_line(path, spec.get("patterns", []))
+ refs.append(
+ {
+ "path": rel_path,
+ "label": str(spec.get("label", rel_path)),
+ "kind": str(spec.get("kind", "source")),
+ "line": line,
+ "exists": exists,
+ "link": link_from(output_html, path) if exists else "",
+ }
+ )
+ return refs
+
+
def gate(key: str, label: str, status: str, detail: str, evidence: str, link: str = "") -> dict[str, str]:
return {
"key": key,
@@ -111,6 +160,16 @@ def min_output_cases(maturity: str) -> int:
return 1
+def fallback_permission_governance(skill_dir: Path) -> dict[str, Any]:
+ if compute_permission_governance_status is None or trust_script_inventory is None:
+ return {}
+ try:
+ scripts = trust_script_inventory(skill_dir)
+ return compute_permission_governance_status(skill_dir, scripts)
+ except Exception:
+ return {}
+
+
def build_gates(skill_dir: Path, output_html: Path, data: dict[str, dict[str, Any]]) -> list[dict[str, str]]:
overview = data["overview"]
maturity = target_maturity(skill_dir, overview)
@@ -152,14 +211,37 @@ def build_gates(skill_dir: Path, output_html: Path, data: dict[str, dict[str, An
)
output = data["output_quality"]
+ output_execution = data["output_execution"]
+ output_blind = data["output_blind_review"]
+ output_review = data["output_review_adjudication"]
output_summary = output.get("summary", {})
+ output_execution_summary = output_execution.get("summary", {})
+ output_blind_summary = output_blind.get("summary", {})
+ output_review_summary = output_review.get("summary", {})
required_cases = min_output_cases(maturity)
case_count = int(output_summary.get("case_count", 0) or 0)
file_backed = int(output_summary.get("file_backed_case_count", 0) or 0)
near_neighbor = int(output_summary.get("near_neighbor_case_count", 0) or 0)
boundary = int(output_summary.get("boundary_case_count", 0) or 0)
- output_blocked = not output.get("ok", False) or not output_summary.get("gate_pass", False) or case_count < required_cases
- output_warn = file_backed == 0 or near_neighbor == 0 or boundary == 0
+ blind_pair_count = int(output_blind_summary.get("pair_count", 0) or 0)
+ execution_variant_count = int(output_execution_summary.get("variant_run_count", 0) or 0)
+ execution_command_count = int(output_execution_summary.get("command_executed_count", 0) or 0)
+ execution_model_count = int(output_execution_summary.get("model_executed_count", 0) or 0)
+ execution_recorded_count = int(output_execution_summary.get("recorded_fixture_count", 0) or 0)
+ review_pair_count = int(output_review_summary.get("pair_count", 0) or 0)
+ review_judgment_count = int(output_review_summary.get("judgment_count", 0) or 0)
+ review_invalid_count = int(output_review_summary.get("invalid_decision_count", 0) or 0)
+ blind_missing = maturity in {"production", "library", "governed"} and (not output_blind or blind_pair_count < case_count)
+ execution_failed = bool(output_execution) and (not output_execution.get("ok", True) or int(output_execution_summary.get("failure_count", 0) or 0) > 0)
+ review_invalid = bool(output_review) and (not output_review.get("ok", True) or review_invalid_count > 0)
+ output_blocked = (
+ not output.get("ok", False)
+ or not output_summary.get("gate_pass", False)
+ or case_count < required_cases
+ or execution_failed
+ or review_invalid
+ )
+ output_warn = file_backed == 0 or near_neighbor == 0 or boundary == 0 or blind_missing
if not output:
output_status = "warn"
output_detail = "output eval scorecard is missing; generate it before production review"
@@ -167,7 +249,15 @@ def build_gates(skill_dir: Path, output_html: Path, data: dict[str, dict[str, An
output_status = "block" if output_blocked else ("warn" if output_warn else "pass")
output_detail = (
f"{case_count}/{required_cases} cases; with-skill {output_summary.get('with_skill_pass_rate', 0)}; "
- f"baseline {output_summary.get('baseline_pass_rate', 0)}; file-backed {file_backed}; near-neighbor {near_neighbor}"
+ f"baseline {output_summary.get('baseline_pass_rate', 0)}; file-backed {file_backed}; near-neighbor {near_neighbor}; "
+ f"blind A/B {blind_pair_count}"
+ + (
+ f"; exec {execution_variant_count}; command {execution_command_count}; "
+ f"model {execution_model_count}; recorded {execution_recorded_count}"
+ if output_execution
+ else ""
+ )
+ + (f"; reviewed {review_judgment_count}/{review_pair_count}" if output_review else "")
)
gates.append(
gate(
@@ -232,7 +322,8 @@ def build_gates(skill_dir: Path, output_html: Path, data: dict[str, dict[str, An
trust_detail = (
f"{trust_summary.get('secret_findings', 0)} secrets; "
f"{trust_summary.get('script_count', 0)} scripts; "
- f"{trust_summary.get('network_script_count', 0)} network-capable scripts"
+ f"{trust_summary.get('network_script_count', 0)} network-capable scripts; "
+ f"{trust_summary.get('help_smoke_failed_count', 0)} help smoke failures"
)
gates.append(
gate(
@@ -245,19 +336,87 @@ def build_gates(skill_dir: Path, output_html: Path, data: dict[str, dict[str, An
)
)
+ permission_governance = trust.get("permission_governance", {}) if isinstance(trust.get("permission_governance", {}), dict) else {}
+ if trust and not permission_governance:
+ permission_governance = fallback_permission_governance(skill_dir)
+ if not trust:
+ permission_status = "warn"
+ permission_detail = "permission governance evidence is missing because trust report is missing"
+ elif not permission_governance:
+ permission_status = "warn"
+ permission_detail = "permission governance evidence is missing from trust report"
+ else:
+ required = int(permission_governance.get("required_count", 0) or 0)
+ approved = int(permission_governance.get("approval_count", 0) or 0)
+ gaps = (
+ int(permission_governance.get("missing_count", 0) or 0)
+ + int(permission_governance.get("invalid_count", 0) or 0)
+ + int(permission_governance.get("expired_count", 0) or 0)
+ )
+ if gaps:
+ permission_status = "block" if maturity == "governed" else "warn"
+ else:
+ permission_status = "pass"
+ required_names = ", ".join(permission_governance.get("required_capabilities", []) or []) or "none"
+ permission_detail = f"{approved}/{required} permissions approved; gaps {gaps}; required {required_names}"
+ gates.append(
+ gate(
+ "permission-gates",
+ "权限批准",
+ permission_status,
+ permission_detail,
+ "reports/security_trust_report.json + security/permission_policy.json",
+ report_link(output_html, skill_dir, "security/permission_policy.md"),
+ )
+ )
+
+ runtime_permissions = data["runtime_permissions"]
+ runtime_permissions_summary = runtime_permissions.get("summary", {})
+ if not runtime_permissions:
+ runtime_permission_status = "block" if maturity == "governed" else "warn"
+ runtime_permission_detail = "runtime permission probe report is missing"
+ elif runtime_permissions.get("failures"):
+ runtime_permission_status = "block"
+ runtime_permission_detail = f"{runtime_permissions_summary.get('failure_count', len(runtime_permissions.get('failures', [])))} runtime permission probe failures"
+ else:
+ runtime_permission_status = "pass"
+ runtime_permission_detail = (
+ f"{runtime_permissions_summary.get('pass_count', 0)}/{runtime_permissions_summary.get('target_count', 0)} targets probed; "
+ f"native {runtime_permissions_summary.get('native_enforcement_count', 0)}; "
+ f"metadata fallback {runtime_permissions_summary.get('metadata_fallback_count', 0)}; "
+ f"residual risks {runtime_permissions_summary.get('residual_risk_count', 0)}"
+ )
+ gates.append(
+ gate(
+ "permission-runtime",
+ "权限探针",
+ runtime_permission_status,
+ runtime_permission_detail,
+ "reports/runtime_permission_probes.json",
+ report_link(output_html, skill_dir, "reports/runtime_permission_probes.md"),
+ )
+ )
+
atlas = data["atlas"]
atlas_summary = atlas.get("summary", {})
- atlas_issues = int(atlas_summary.get("route_collision_count", 0) or 0) + int(atlas_summary.get("owner_gap_count", 0) or 0)
+ actionable_route_collisions = int(
+ atlas_summary.get("actionable_route_collision_count", atlas_summary.get("route_collision_count", 0)) or 0
+ )
+ actionable_owner_gaps = int(atlas_summary.get("actionable_owner_gap_count", atlas_summary.get("owner_gap_count", 0)) or 0)
+ actionable_stale = int(atlas_summary.get("actionable_stale_count", atlas_summary.get("stale_count", 0)) or 0)
+ atlas_issues = actionable_route_collisions + actionable_owner_gaps + actionable_stale
if not atlas:
atlas_status = "warn"
atlas_detail = "skill atlas is missing; portfolio-level conflicts are unknown"
else:
atlas_status = "warn" if atlas_issues else "pass"
atlas_detail = (
- f"{atlas_summary.get('skill_count', 0)} skills; "
- f"{atlas_summary.get('route_collision_count', 0)} route collisions; "
- f"{atlas_summary.get('owner_gap_count', 0)} owner gaps; "
- f"{atlas_summary.get('stale_count', 0)} stale"
+ f"{atlas_summary.get('skill_count', 0)} skills, "
+ f"{atlas_summary.get('actionable_skill_count', atlas_summary.get('skill_count', 0))} actionable; "
+ f"{actionable_route_collisions} actionable route collisions; "
+ f"{actionable_owner_gaps} actionable owner gaps; "
+ f"{actionable_stale} actionable stale; "
+ f"{atlas_summary.get('non_actionable_issue_count', 0)} scoped non-actionable issues"
)
gates.append(
gate(
@@ -270,6 +429,107 @@ def build_gates(skill_dir: Path, output_html: Path, data: dict[str, dict[str, An
)
)
+ adoption = data["adoption_drift"]
+ adoption_summary = adoption.get("summary", {})
+ if not adoption:
+ adoption_status = "warn"
+ adoption_detail = "adoption drift report is missing; real usage impact is unknown"
+ elif adoption.get("failures"):
+ adoption_status = "block"
+ adoption_detail = f"telemetry privacy or schema failures: {len(adoption.get('failures', []))}"
+ else:
+ risk_band = adoption_summary.get("risk_band", "no-data")
+ adoption_status = "warn" if risk_band in {"no-data", "medium", "high"} else "pass"
+ adoption_detail = (
+ f"{adoption_summary.get('event_count', 0)} metadata events; "
+ f"adoption {adoption_summary.get('adoption_rate', 0)}; "
+ f"missed {adoption_summary.get('missed_trigger_count', 0)}; "
+ f"bad-output {adoption_summary.get('bad_output_count', 0)}; "
+ f"risk {risk_band}"
+ )
+ gates.append(
+ gate(
+ "operations-loop",
+ "运营回路",
+ adoption_status,
+ adoption_detail,
+ "reports/adoption_drift_report.json",
+ report_link(output_html, skill_dir, "reports/adoption_drift_report.md"),
+ )
+ )
+
+ waiver = data["review_waivers"]
+ waiver_summary = waiver.get("summary", {})
+ active_covered = set(waiver_summary.get("covered_gate_keys", []) or [])
+ prior_blockers = [item for item in gates if item["status"] == "block"]
+ prior_warnings = [item for item in gates if item["status"] == "warn"]
+ unwaived_warnings = [item for item in prior_warnings if item["key"] not in active_covered]
+ if not waiver:
+ waiver_status = "warn"
+ waiver_detail = "review waiver ledger is missing; warning acceptance is not auditable"
+ elif waiver.get("failures"):
+ waiver_status = "block"
+ waiver_detail = f"{len(waiver.get('failures', []))} invalid waiver records"
+ elif prior_blockers:
+ waiver_status = "block"
+ waiver_detail = f"{len(prior_blockers)} blocker gates cannot be waived in v0"
+ elif unwaived_warnings:
+ waiver_status = "warn"
+ waiver_detail = (
+ f"{waiver_summary.get('active_count', 0)} active waivers; "
+ f"{len(unwaived_warnings)} warning gates still need reviewer decision"
+ )
+ else:
+ waiver_status = "pass"
+ waiver_detail = f"{waiver_summary.get('active_count', 0)} active waivers cover current warnings"
+ gates.append(
+ gate(
+ "review-waivers",
+ "人工批准",
+ waiver_status,
+ waiver_detail,
+ "reports/review_waivers.json",
+ report_link(output_html, skill_dir, "reports/review_waivers.md"),
+ )
+ )
+
+ registry = data["registry"]
+ install = data["install_simulation"]
+ if not registry:
+ if maturity in {"library", "governed"}:
+ registry_status = "warn"
+ registry_detail = "registry audit is missing; package metadata is not reviewable"
+ else:
+ registry_status = "pass"
+ registry_detail = "registry audit is optional until team distribution is required"
+ else:
+ compatibility = registry.get("package", {}).get("compatibility", {})
+ pass_count = sum(1 for status in compatibility.values() if status == "pass")
+ registry_status = "block" if registry.get("failures") else ("warn" if registry.get("warnings") else "pass")
+ registry_detail = (
+ f"{registry.get('package', {}).get('name', 'package')} "
+ f"{registry.get('package', {}).get('version', 'n/a')}; "
+ f"{pass_count}/{len(compatibility)} compatibility entries pass"
+ )
+ if install:
+ if install.get("failures"):
+ registry_status = "block"
+ install_summary = install.get("summary", {})
+ registry_detail += (
+ f"; install {'pass' if install.get('ok') else 'fail'}"
+ f" with {install_summary.get('adapter_count', 0)} adapters"
+ )
+ gates.append(
+ gate(
+ "registry-audit",
+ "注册审计",
+ registry_status,
+ registry_detail,
+ "reports/registry_audit.json + reports/install_simulation.json",
+ report_link(output_html, skill_dir, "reports/registry_audit.md"),
+ )
+ )
+
promotion = data["promotion"]
migration_path = ROOT / "docs" / "migration-v2.md"
if promotion:
@@ -280,13 +540,24 @@ def build_gates(skill_dir: Path, output_html: Path, data: dict[str, dict[str, An
else:
release_status = "warn"
release_detail = "promotion decisions are missing; release notes need reviewer confirmation"
+ upgrade = data["upgrade_check"]
+ if upgrade:
+ upgrade_summary = upgrade.get("summary", {})
+ if upgrade.get("failures"):
+ release_status = "block"
+ elif upgrade.get("warnings") and release_status == "pass":
+ release_status = "warn"
+ release_detail += (
+ f"; upgrade {upgrade_summary.get('declared_bump', 'n/a')}"
+ f" declared / {upgrade_summary.get('recommended_bump', 'n/a')} recommended"
+ )
gates.append(
gate(
"release-notes",
"发布路线",
release_status,
release_detail,
- "reports/promotion_decisions.json + docs/migration-v2.md",
+ "reports/promotion_decisions.json + reports/upgrade_check.json + docs/migration-v2.md",
report_link(output_html, skill_dir, "reports/promotion_decisions.md") if promotion else str(migration_path),
)
)
@@ -301,7 +572,12 @@ def weighted_score(gates: list[dict[str, str]]) -> int:
"context-budget": 10,
"runtime-matrix": 10,
"trust-report": 10,
+ "permission-gates": 10,
+ "permission-runtime": 10,
"skill-atlas": 10,
+ "operations-loop": 10,
+ "review-waivers": 10,
+ "registry-audit": 10,
"release-notes": 10,
"intent-canvas": 10,
}
@@ -322,9 +598,22 @@ def evidence_paths(skill_dir: Path) -> dict[str, str]:
"skill_overview": "reports/skill-overview.html",
"review_viewer": "reports/review-viewer.html",
"output_eval": "reports/output_quality_scorecard.md",
+ "output_execution": "reports/output_execution_runs.md",
+ "output_blind_review": "reports/output_blind_review_pack.md",
+ "output_review_adjudication": "reports/output_review_adjudication.md",
"runtime_conformance": "reports/conformance_matrix.md",
"trust_report": "reports/security_trust_report.md",
+ "permission_policy": "security/permission_policy.md",
+ "runtime_permissions": "reports/runtime_permission_probes.md",
"skill_atlas": "reports/skill_atlas.html",
+ "compiled_targets": "reports/compiled_targets.md",
+ "adoption_drift": "reports/adoption_drift_report.md",
+ "review_waivers": "reports/review_waivers.md",
+ "review_annotations": "reports/review_annotations.md",
+ "registry_audit": "reports/registry_audit.md",
+ "package_verification": "reports/package_verification.md",
+ "install_simulation": "reports/install_simulation.md",
+ "upgrade_check": "reports/upgrade_check.md",
"migration": "docs/migration-v2.md",
"skill_ir": "reports/skill-ir.json",
}
@@ -339,11 +628,23 @@ def load_review_data(skill_dir: Path) -> dict[str, dict[str, Any]]:
"intent_dialogue": load_json(reports / "intent-dialogue.json"),
"route_scorecard": load_json(reports / "route_scorecard.json"),
"output_quality": load_json(reports / "output_quality_scorecard.json"),
+ "output_execution": load_json(reports / "output_execution_runs.json"),
+ "output_blind_review": load_json(reports / "output_blind_review_pack.json"),
+ "output_review_adjudication": load_json(reports / "output_review_adjudication.json"),
+ "compiled_targets": load_json(reports / "compiled_targets.json"),
"conformance": load_json(reports / "conformance_matrix.json"),
+ "runtime_permissions": load_json(reports / "runtime_permission_probes.json"),
"trust": load_json(reports / "security_trust_report.json"),
"context_budget": load_json(reports / "context_budget.json"),
"promotion": load_json(reports / "promotion_decisions.json"),
"atlas": load_json(reports / "skill_atlas.json"),
+ "adoption_drift": load_json(reports / "adoption_drift_report.json"),
+ "review_waivers": load_json(reports / "review_waivers.json"),
+ "review_annotations": load_json(reports / "review_annotations.json"),
+ "registry": load_json(reports / "registry_audit.json"),
+ "package_verification": load_json(reports / "package_verification.json"),
+ "install_simulation": load_json(reports / "install_simulation.json"),
+ "upgrade_check": load_json(reports / "upgrade_check.json"),
"manifest": load_json(skill_dir / "manifest.json"),
"frontmatter": parse_frontmatter(skill_dir / "SKILL.md"),
"interface": load_yaml(skill_dir / "agents" / "interface.yaml"),
@@ -353,25 +654,66 @@ def load_review_data(skill_dir: Path) -> dict[str, dict[str, Any]]:
def insight_cards(data: dict[str, dict[str, Any]]) -> list[dict[str, str]]:
overview = data["overview"]
output = data["output_quality"].get("summary", {})
+ output_execution = data["output_execution"].get("summary", {})
+ output_blind = data["output_blind_review"].get("summary", {})
+ output_review = data["output_review_adjudication"].get("summary", {})
+ compiled = data["compiled_targets"].get("summary", {})
conformance = data["conformance"].get("summary", {})
+ runtime_permissions = data["runtime_permissions"].get("summary", {})
trust = data["trust"].get("summary", {})
atlas = data["atlas"].get("summary", {})
+ adoption = data["adoption_drift"].get("summary", {})
+ waivers = data["review_waivers"].get("summary", {})
+ annotations = data["review_annotations"].get("summary", {})
+ registry = data["registry"].get("package", {})
+ package_verification = data["package_verification"].get("summary", {})
+ install_simulation = data["install_simulation"].get("summary", {})
+ upgrade = data["upgrade_check"].get("summary", {})
cards = [
{
"label": "Skill IR",
"value": str(overview.get("skill_ir", {}).get("schema_version", "missing")),
"detail": f"{overview.get('skill_ir', {}).get('target_count', 0)} targets in platform-neutral contract",
},
+ {
+ "label": "Compiler",
+ "value": f"{compiled.get('pass_count', 0)}/{compiled.get('target_count', 0)}",
+ "detail": "target contracts compiled from Skill IR",
+ },
{
"label": "Output Delta",
"value": str(output.get("delta", "n/a")),
"detail": f"{output.get('case_count', 0)} cases; {output.get('file_backed_case_count', 0)} file-backed",
},
+ {
+ "label": "Exec Runs",
+ "value": str(output_execution.get("variant_run_count", 0)),
+ "detail": (
+ f"command {output_execution.get('command_executed_count', 0)}; "
+ f"model {output_execution.get('model_executed_count', 0)}; "
+ f"recorded {output_execution.get('recorded_fixture_count', 0)}"
+ ),
+ },
+ {
+ "label": "Blind A/B",
+ "value": str(output_blind.get("pair_count", 0)),
+ "detail": "review pairs hide baseline vs with-skill labels",
+ },
+ {
+ "label": "Review A/B",
+ "value": f"{output_review.get('judgment_count', 0)}/{output_review.get('pair_count', 0)}",
+ "detail": f"adjudication decisions; pending {output_review.get('pending_count', 0)}",
+ },
{
"label": "Runtime",
"value": f"{conformance.get('pass_count', 0)}/{conformance.get('target_count', 0)}",
"detail": "target conformance pass rate",
},
+ {
+ "label": "Perm Probe",
+ "value": f"{runtime_permissions.get('metadata_fallback_count', 0)}/{runtime_permissions.get('target_count', 0)}",
+ "detail": f"{runtime_permissions.get('native_enforcement_count', 0)} native enforcement targets",
+ },
{
"label": "Trust",
"value": str(trust.get("secret_findings", 0)),
@@ -382,6 +724,41 @@ def insight_cards(data: dict[str, dict[str, Any]]) -> list[dict[str, str]]:
"value": str(atlas.get("route_collision_count", 0)),
"detail": f"{atlas.get('skill_count', 0)} scanned skills; route collisions",
},
+ {
+ "label": "Drift",
+ "value": str(adoption.get("risk_band", "n/a")),
+ "detail": f"{adoption.get('event_count', 0)} metadata events; {adoption.get('missed_trigger_count', 0)} missed triggers",
+ },
+ {
+ "label": "Waivers",
+ "value": str(waivers.get("active_count", 0)),
+ "detail": f"{waivers.get('covered_gate_count', 0)} gates covered; human risk decisions",
+ },
+ {
+ "label": "Notes",
+ "value": f"{annotations.get('open_count', 0)}/{annotations.get('annotation_count', 0)}",
+ "detail": f"{annotations.get('open_blocker_count', 0)} open blocker annotations",
+ },
+ {
+ "label": "Registry",
+ "value": str(registry.get("version", "n/a")),
+ "detail": f"{len(registry.get('targets', []))} targets; {registry.get('license', 'no license')} license",
+ },
+ {
+ "label": "Archive",
+ "value": "pass" if data["package_verification"].get("ok") else "n/a",
+ "detail": f"{package_verification.get('archive_entry_count', 0)} zip entries; package verification",
+ },
+ {
+ "label": "Install",
+ "value": "pass" if data["install_simulation"].get("ok") else "n/a",
+ "detail": f"{install_simulation.get('adapter_count', 0)} adapters readable; local install simulation",
+ },
+ {
+ "label": "Upgrade",
+ "value": str(upgrade.get("recommended_bump", "n/a")),
+ "detail": f"declared {upgrade.get('declared_bump', 'n/a')}; {upgrade.get('breaking_change_count', 0)} breaking changes",
+ },
]
return cards
@@ -430,9 +807,267 @@ def render_issue_list(title: str, items: list[dict[str, str]]) -> str:
return f"