YAO stands for Yielding AI Outcomes — the goal is not to generate more prompt text, but to produce reusable AI assets and real operational outcomes.

yao-meta-skill is a lightweight but rigorous system for creating, evaluating, packaging, and governing reusable agent skills.

Quick Start · Examples · Evals · Failure Library · Method Doctrine

It turns rough workflows, transcripts, prompts, notes, and runbooks into reusable skill packages with:

• a clear trigger surface
• a lean SKILL.md
• optional references, scripts, and evals
• a front-loaded intent dialogue that starts from the user's real work, desired outcome, and quality bar
• an automatic GitHub benchmark scan that pulls the top three public repositories first, extracts borrow or avoid patterns, and then asks whether the user has references worth learning from
• a generated visual HTML overview for each newly initialized skill
• a side-by-side HTML review studio for first-pass human review
• 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 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
• neutral source metadata plus client-specific adapters
• governance, promotion, and portability checks built into the default flow

Hero view: turn messy operational input into a governed, reusable skill package through one compact flow.

flowchart LR
    A["Inputs<br/>workflow / prompt / transcript / docs / notes"] --> B["Route<br/>SKILL.md"]
    B --> C["Design<br/>method + gates"]
    C --> D["Run<br/>create / validate / eval / promote"]
    D --> E["Outputs<br/>skill package + reports + adapters"]

Read it in 10 seconds:

• Inputs: start from rough operational material.
• Route: define boundary and trigger in a lean SKILL.md.
• Design: choose the right archetype, gates, and resource split.
• Run: use the unified CLI to build, validate, optimize, and promote.
• Outputs: ship a reusable skill plus evidence, governance signals, and portability artifacts.

This is a scenario-oriented benchmark shared with the project. It is most useful when deciding which system fits a workflow, not as a universal claim that one approach beats every other approach in every context.

• Choose skill-creator when the main goal is fast solo ideation, flexible interaction, and quick iteration with a lighter process.
• Choose yao-meta-skill when the goal is to build a reusable asset with explicit boundaries, evaluation gates, governance, portability, and long-term maintainability.
• A practical hybrid pattern is: use a conversational creator to get a first draft, then use yao-meta-skill to harden the package, add evidence, and make it team-ready.

1. Describe the workflow, prompt set, or repeated task you want to turn into a skill.
2. Start with a short, human intent dialogue so the real job, outputs, exclusions, constraints, and standards are explicit.
3. Let quickstart run a short GitHub benchmark scan first, study the top three public repositories it retrieves, then ask whether the user has examples worth learning from; use local files only for fit and privacy checks.
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/intent-dialogue.md, reports/skill-overview.html, and reports/iteration-directions.md before adding more structure.

Or use the unified authoring CLI:

python3 scripts/yao.py quickstart --output-dir .
python3 scripts/yao.py github-benchmark-scan my-skill --query "release workflow portability"
python3 scripts/yao.py reference-scan my-skill \
  --external-reference "World Class Method::method::Borrow a tight evaluation loop.::Do not copy heavy process." \
  --user-reference "A product or repo I admire::taste::Learn the clarity and operating standard.::Do not copy wording." \
  --local-constraint "Current Library Naming::structure::Keep naming aligned with the local skill library.::Do not inherit private references."
python3 scripts/yao.py review-viewer my-skill
python3 scripts/yao.py feedback my-skill --note "Tighten exclusions before adding scripts." --rating 4 --category boundary
python3 scripts/yao.py baseline-compare
python3 scripts/yao.py package . --platform generic --output-dir dist

1. Start from a raw workflow note.
2. Turn it into a skill package with SKILL.md, agents/interface.yaml, and only the folders the workflow actually needs.
3. Validate the trigger description with evals/trigger_cases.json.
4. Export compatibility artifacts for the clients you care about.
5. 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

Unified authoring flow:

python3 scripts/yao.py init my-skill --description "Describe what the skill does."
python3 scripts/yao.py validate my-skill
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 package . --platform openai --platform claude --platform generic --output-dir dist --zip
python3 scripts/yao.py test

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:

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

• packaging validation: openai, claude, and generic targets pass contract checks
• 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
• 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 971/1000, complex benchmark 790/1000, governed benchmark 760/1000
• quality density: root 133.9, 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
• lightweight with-skill vs baseline comparison is published in reports/baseline-compare.md
• context budget summaries are tracked in reports/context_budget.md
• portability status is tracked in reports/portability_score.md

In the latest weighted review shared with the project, Yao scored strongest in the dimensions that define a production-grade meta-skill system:

• Method completeness 9.8: the repository now has a formal doctrine for skill engineering, gate selection, non-skill decisions, lifecycle governance, and resource boundaries.
• Engineering toolchain 9.8: authoring, validation, packaging, reporting, promotion checks, and CI are wired into one operational toolchain rather than scattered scripts.
• Governance, maintenance, and safety 9.8: important skills can carry lifecycle state, review cadence, maturity score, trust boundaries, and promotion evidence.
• Evaluation loop 9.7: trigger quality is checked with train/dev/holdout, blind holdout, adversarial holdout, judge-backed blind eval, drift history, and promotion gates.
• Portability and packaging 9.6: the source stays neutral while adapters, degradation rules, and packaging contracts preserve reusable semantics across target environments.
• Trigger and boundary design 9.5: route confusion, anti-pattern regressions, and promotion policy make trigger quality an auditable routing problem instead of a loose prompt-writing exercise.
• Context efficiency 9.4: the entrypoint stays compact, context budgets are tiered, and quality density is tracked instead of only raw token counts.

The overall direction is deliberate: keep the entrypoint light, make the evaluation loop strict, and treat governance as a first-class part of skill quality.

• Lightweight: the entrypoint stays compact, context budgets are explicit, and extra structure is added only when it pays for itself.
• Rigorous: trigger quality is checked with family regressions, blind holdout, adversarial holdout, route confusion, judge-backed blind eval, and promotion gates.
• Governed: important skills are treated as maintainable assets with lifecycle state, maturity expectations, ownership, and review cadence.
• Portable: source metadata stays neutral while adapters, degradation rules, and packaging contracts preserve reusable semantics across environments.

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

The design logic is simple:

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

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

• Skill Engineering Method
• Intent Dialogue
• Reference Scan Strategy
• Skill Archetypes
• Gate Selection
• Iteration Philosophy
• Non-Skill Decision Tree
• Regression Cause Taxonomy
• Human Review Template

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

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

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

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

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

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
• 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
• 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
• render_portability_report.py: scores cross-environment portability from neutral metadata, degradation rules, and consumer validation coverage
• init_skill.py, lint_skill.py, validate_skill.py, diff_eval.py: minimal authoring toolchain

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.

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.

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

• 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.

Starter templates for simple and more advanced skill packages.

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

The typical flow is:

1. describe the workflow or capability
2. identify trigger phrases and outputs
3. choose scaffold, production, or library mode
4. generate the package
5. run the sizing and trigger checks if needed
6. export target-specific 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

• Method-first, not prompt-first: skill creation is treated as a formal engineering workflow with archetypes, gate selection, and non-skill decisions.
• Trigger-aware by design: descriptions are optimized with route confusion, blind holdout, adversarial families, and promotion policy instead of one-shot intuition.
• Lightweight at the entrypoint: SKILL.md stays compact while references, scripts, and evals are only added when they pay for themselves.
• Toolchain-backed: initialization, validation, optimization, reporting, packaging, and testing are available through one unified CLI and CI path.
• Governed as an asset: important skills can carry ownership, lifecycle state, maturity expectations, and review cadence.
• Portable by default: source metadata stays neutral while adapters and degradation rules preserve compatibility across target environments.
• Evidence-rich: route scorecards, regression history, context budgets, portability scores, and promotion decisions are published as artifacts instead of hidden implementation detail.

This project is best for:

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

• 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

MIT. See LICENSE.