Describe the workflow, prompt set, or repeated task you want to turn into a skill.
Use yao-meta-skill to generate or improve the package in scaffold, production, or library mode.
Run context_sizer.py, resource_boundary_check.py, governance_check.py, trigger_eval.py, and cross_packager.py as needed to validate and export the result.

5-Minute Workflow

Start from a raw workflow note.
Turn it into a skill package with SKILL.md, agents/interface.yaml, and only the folders the workflow actually needs.
Validate the trigger description with evals/trigger_cases.json.
Export compatibility artifacts for the clients you care about.
Compare the result against the examples in examples/.

Minimum commands:

python3 scripts/trigger_eval.py --description-file evals/improved_description.txt --cases evals/trigger_cases.json
python3 scripts/run_description_optimization_suite.py
python3 scripts/judge_blind_eval.py --description-file SKILL.md --cases evals/blind_holdout/trigger_cases.json --semantic-config evals/semantic_config.json
python3 scripts/context_sizer.py .
python3 scripts/resource_boundary_check.py .
python3 scripts/governance_check.py . --require-manifest
python3 scripts/cross_packager.py . --platform openai --platform claude --platform generic --expectations evals/packaging_expectations.json --zip
python3 tests/verify_packager_failures.py

Or run everything together:

make test

Results

The homepage panel below is generated from the current eval suite so the family-level outcome is visible without opening raw JSON.

regression corpus: 66 prompts across 21 families
aggregate result: 0 false positives, 0 false negatives, average precision 1.0, average recall 1.0
suite status:

Suite	Cases	Precision	Recall
train	31	1.0	1.0
dev	22	1.0	1.0
holdout	13	1.0	1.0

Family	Cases	Pass Rate
`brainstorm_only`	2	1.0
`brainstorm_vs_build`	1	1.0
`complex_multi_asset`	3	1.0
`document_export_vs_agent_skill`	4	1.0
`document_only`	3	1.0
`explain_not_package`	1	1.0
`explain_only`	5	1.0
`future_outline_vs_build`	4	1.0
`iterate_existing_skill`	5	1.0
`long_context_document_only`	3	1.0
`long_context_near_neighbor`	3	1.0
`long_context_summary_only`	2	1.0
`long_context_trigger`	4	1.0
`meta_skill_creation`	1	1.0
`one_off_vs_reusable`	2	1.0
`package_for_team`	2	1.0
`paraphrase_trigger`	5	1.0
`partial_scaffold_not_full_skill`	4	1.0
`summary_only`	3	1.0
`translate_only`	4	1.0
`workflow_to_skill`	5	1.0

Full reports: reports/eval_suite.json and reports/family_summary.md

packaging validation: openai, claude, and generic targets pass contract checks
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
packaging failure fixtures: invalid metadata, invalid YAML, and unsupported targets fail as expected
failure library regressions: anti-pattern families pass automated checks
governance and resource-boundary checks are part of the default test path
root governance maturity score: 90/100; governed benchmark example: 95/100
context budgets: root 886/1000, complex benchmark 790/1000, governed benchmark 760/1000
quality density: root 146.7, complex benchmark 164.6, governed benchmark 171.1
regression milestones are tracked in reports/regression_history.md
description drift history is tracked in reports/description_drift_history.md
route confusion is tracked in reports/route_scorecard.md
promotion evidence is summarized in reports/iteration_ledger.md
promotion decisions are published in reports/promotion_decisions.md
candidate lifecycle states are published in reports/candidate_registry.md
context budget summaries are tracked in reports/context_budget.md

What It Does

This project helps you create, refactor, evaluate, and package skills as durable capability bundles rather than one-off prompts.

The design logic is simple:

Capture the real recurring job behind the user's request.
Set a clean skill boundary so one package does one coherent job.
Optimize the trigger description before over-writing the body.
Keep the main skill file small and move details into references or scripts.
Add quality gates only when they pay for themselves.
Export compatibility artifacts only for the clients you actually need.

Method Doctrine

The repository now treats method as a first-class asset instead of scattered guidance.

Why It Exists

Most teams keep valuable operating knowledge scattered across chats, personal prompts, oral habits, and undocumented workflows. This project converts that hidden process knowledge into:

discoverable skill packages
repeatable execution flows
lower-context instructions
reusable team assets
compatibility-ready distributions

Repository Structure

yao-meta-skill/
├── SKILL.md
├── README.md
├── LICENSE
├── .gitignore
├── agents/
│   └── interface.yaml
├── evals/
├── examples/
├── references/
├── scripts/
└── templates/

Core Components

`SKILL.md`

The main skill entrypoint. It defines the trigger surface, operating modes, compact workflow, and output contract.

`agents/interface.yaml`

The neutral metadata source of truth. It stores display and compatibility metadata without locking the source tree to one vendor-specific path.

`references/`

Long-form material that should not bloat the main skill file. This includes design rules, evaluation guidance, compatibility strategy, and quality rubrics.

`scripts/`

Utility scripts that make the meta-skill operational:

trigger_eval.py: evaluates trigger descriptions with semantic intent concepts, explicit exclusions, and near-neighbor prompts
run_eval_suite.py: runs train/dev/holdout trigger suites, reports family-level regressions, and fails if aggregate regressions appear
optimize_description.py: generates candidate descriptions, scores them on dev, visible holdout, blind holdout, and adversarial holdout suites, then reports calibration and family health
judge_blind_eval.py: applies an independent rubric judge to blind-holdout prompts so blind acceptance is not backed only by the main threshold scorer
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
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
context_sizer.py: estimates context weight and warns when the initial load gets too large
resource_boundary_check.py: audits whether detail is split across SKILL.md, references/, scripts/, assets/, and evals/ appropriately
governance_check.py: validates owner, review cadence, lifecycle stage, and maturity metadata
render_context_reports.py: generates root and example context-budget reports plus a shared context summary
render_regression_history.py: turns milestone snapshots into a readable regression history report
cross_packager.py: builds client-specific export artifacts with explicit platform contracts and validation
init_skill.py, lint_skill.py, validate_skill.py, diff_eval.py: minimal authoring toolchain

`evals/`

Reusable trigger and packaging checks, including baseline and improved descriptions for comparison plus the root semantic configuration that drives description optimization.

This directory also contains route confusion fixtures and promotion policy rules for deciding when a route is promotable.

`examples/`

End-to-end examples showing raw workflow input, design summary, final generated skill shape, and targeted description-optimization packs where route wording is tuned against example-specific dev and holdout cases.

`.github/workflows/test.yml`

Continuous integration entrypoint that runs the full local regression suite on push and pull request.

Validation Notes

Trigger evaluation now uses a local semantic-intent model with explicit positive concepts, exclusion concepts, and boundary-case reporting.
The sample trigger report now covers a larger positive, negative, and near-neighbor set rather than a tiny demo set.
Train/dev/holdout trigger suites now separate iterative tuning from final verification.
Description optimization now uses dev for ranking, visible holdout for non-regression, blind holdout for acceptance, and adversarial holdout for harder route-collision checks without feeding the ranking loop.
Judge-backed blind eval now adds a rubric-based second opinion for blind prompts, so blind acceptance is not decided by one scorer alone.
Description drift history now records adversarial calibration gaps and family coverage, so routing changes can be judged on confidence and family stability rather than raw error counts alone.
Route confusion is now tracked explicitly across the root meta-skill, frontend review skill, governed incident skill, and no_route cases, so route theft is visible instead of implicit.
Promotion policy now requires visible holdout, blind holdout, adversarial holdout, and route confusion to stay clean before a description should be considered promotable.
Promotion checking now emits explicit decisions, candidate lifecycle states, iteration bundles, and human-review stubs rather than leaving promotion as a prose-only step.
Promotion decisions now distinguish “no candidate beat current” from “current still has residual route risk,” so iteration can be audited without forcing every issue into a false block.
Packaging validation now uses explicit contracts and YAML parsing, but it is still a lightweight local validation layer rather than a full platform integration suite.
evals/failure-cases.md captures known weak spots that should remain part of regression checks.
failures/ captures reusable anti-pattern writeups and machine-runnable failure cases for routing, packaging, and authoring failures.
tests/verify_packager_failures.py checks that invalid metadata, invalid YAML, and unsupported targets fail clearly.
Governance metadata and resource-boundary rules now have runnable checks instead of staying as prose only.
Governance checks now emit a maturity score so governed assets can be compared instead of only pass/fail checked.
Description optimization drift history is now versioned separately from the main trigger regression history so routing improvements are visible over time.
Iteration evidence now records why a candidate was kept, blocked, or promotable via a shared regression-cause taxonomy and bundle artifacts.
Declared maturity tiers are checked against recommended minimum governance scores, so production, library, and governed assets can be compared without forcing every strong example into the same label.
Context budgets are now tiered and explicit, so a governed skill can still choose a stricter production-sized initial-load budget.
Resource-boundary checks now detect decorative directories and compute a local quality-density signal instead of only checking raw token counts.

`templates/`

Starter templates for simple and more advanced skill packages.

How To Use

1. Use the skill directly

Invoke yao-meta-skill when you want to:

create a new skill
improve an existing skill
add evals to a skill
convert a workflow into a reusable package
prepare a skill for wider team adoption

2. Generate a new skill package

The typical flow is:

describe the workflow or capability
identify trigger phrases and outputs
choose scaffold, production, or library mode
generate the package
run the sizing and trigger checks if needed
export target-specific compatibility artifacts

3. Export compatibility artifacts

Examples:

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
python3 scripts/governance_check.py ./yao-meta-skill --require-manifest
python3 scripts/trigger_eval.py --description-file evals/improved_description.txt --cases evals/trigger_cases.json --baseline-description-file evals/baseline_description.txt

Advantages

Neutral by default: source files stay vendor-neutral, while adapters are generated only when needed.
Context efficient: the project explicitly pushes detail out of the main skill file.
Evaluation-aware: trigger and sizing checks are built into the workflow.
Governed: important skills can be checked for lifecycle metadata, ownership, and review cadence.
Evidence-driven: regression history and maturity scoring make progress visible across revisions.
Reusable: the output is a package, not just a paragraph of prompt text.
Portable: compatibility is handled through packaging rather than duplicating source files for every client.

Best Fit

This project is best for:

agent builders
internal tooling teams
prompt engineers moving toward structured skills
organizations building reusable skill libraries

Documentation

Language	Entry
English	README.md
中文	docs/README.zh-CN.md
日本語	docs/README.ja-JP.md
Français	docs/README.fr-FR.md
Русский	docs/README.ru-RU.md

Examples And Evals

Examples: examples/README.md
Evals: evals/README.md
Failure library: failures/README.md
Failure regression check: verify_failure_regressions.py
Regression history: reports/regression_history.md
Root governance score: reports/governance_score.json
Packaging contracts: references/packaging-contracts.md
Governance model: references/governance.md
Resource boundary spec: references/resource-boundaries.md
Platform capability matrix: references/platform-capability-matrix.md
Failure fixtures: tests/fixtures
Adapter snapshots: tests/snapshots
Evolution example: examples/evolution-frontend-review/README.md
Governed example: examples/governed-incident-command/design-summary.md
Governed example score: examples/governed-incident-command/generated-skill/reports/governance_score.json
World-class roadmap: WORLD_CLASS_PLAN.md

License

MIT. See LICENSE.