yao-meta-skill: a Skill OS for agent skills that need evidence and release gates

The problem yao-meta-skill solves, and who has it

Most agent skills start as a markdown file and a few prompts. That is enough while one person uses them. It stops being enough the moment a second person installs the skill, because there is no way to tell whether the installed copy matches the intent, whether it triggers on the right requests, or whether the last edit made it worse. The README frames the 1.0 line as turning repeated workflows into installable, readable, cross-platform skill packages, and the 2.0 line as expanding that factory into what it calls a Skill OS: model a skill once, compile it for several targets, test its behavior, review release evidence, track the next iteration.

The intended user is a skill maintainer rather than a skill consumer. The 2.0 use cases listed in the README are concrete about this: create a skill from a workflow note, transcript or runbook; upgrade a personal skill into a team asset by adding interface contracts, manifests, target adapters, trust checks and output evals; prepare a skill for beta release with package verification, install simulation and runtime permission probes; keep it useful after release through metadata-only telemetry and adoption drift. If you only write prompts for yourself, none of those stages apply and the repository is heavier than the job.

Skill IR, target compilers and the gate contract

The architectural move in 2.0 is the Skill IR, described in the README as a platform-neutral intermediate representation for intent, triggers, inputs, outputs, boundaries, references and expected artifacts. Instead of hand-editing one markdown entrypoint per platform, you describe the skill once in the IR, and target compilers and adapters generate surfaces for OpenAI, Claude, generic agent skills, Agent Skills compatible packages and VS Code-oriented workflows. The repository layout matches that description: there are top-level skill-ir/, registry/, schemas/ and runtime/ directories alongside the older agents/, references/ and templates/ entries.

Around the compiled package sits the evidence layer. The Output Eval Lab covers trigger checks, output assertions, execution evidence, timing and token evidence, benchmark reproducibility, blind-review packs, answer keys and adjudication reports. Review Studio 2.0 is a single HTML gate page that collects intent, triggers, output eval, context cost, runtime checks, trust, Skill Atlas signals, adoption drift, waivers, annotations, release evidence, warnings, blockers and fix actions. Release governance adds evidence consistency checks, package verification, install simulation, runtime permission probes and a public claim guard. The SkillOps loop closes the cycle with metadata-only adoption drift, telemetry hooks, adaptive proposals and daily and weekly curator reports.

That is a lot of surface for one skill, and the README is unusually direct about its own posture: the repository is described as ready for beta and external testing, with stronger public claims evidence-gated, and provider-backed production evidence, human blind-review evidence, native permission execution and real-client telemetry tracked as separate evidence tasks rather than completed work. Read that as the maintainer telling you which parts of the pipeline are exercised and which are scaffolding.

Installing yao-meta-skill and running a first diagnostic

The repository is installed from a clone rather than from a package index; the README's quick start points at the repository itself, and the Makefile pins the interpreter. REQUIRED_PYTHON_VERSION is 3.11, so the first useful command is the version check, which fails early if your default python3 is older.

make python-version-check

With the interpreter confirmed, the Operator UX commands are the cheapest way to see whether the tool is working in your environment. They are described as read-only helpers that turn common maintainer questions into repeatable diagnostics. Run install-status against the checkout to find out which copy of the skill is active.

python3 scripts/yao.py install-status --expected-source .

The README states that this command explains whether the active skill comes from .codex/skills, .agents/skills or the disabled mirror, and flags duplicate active installs. If you have ever edited one copy of a skill and watched an agent use another, that output is the reason the command exists. The Makefile also defines two install directories you can compare against: ACTIVE_SKILL_INSTALL_DIR defaults to $(HOME)/.agents/skills/yao-meta-skill and LOCAL_SKILL_INSTALL_DIR to $(HOME)/.agents/skills.disabled/yao-meta-skill.

Two more read-only helpers are documented in the same block. localized-doc-sync-check verifies that the Chinese README carries the public homepage sections added to the English README, and pr-review-report takes a pull request number plus a --repo flag.

python3 scripts/yao.py localized-doc-sync-check
python3 scripts/yao.py pr-review-report 4 --repo yaojingang/yao-meta-skill

For a broader sweep, the Makefile exposes a large set of targets whose names map to the pipeline stages: package-verify-check, install-simulation-check, output-eval-check, runtime-permission-check, evidence-consistency-check and adoption-drift-check among them. The README does not document which of these are expected to pass on a fresh clone, so treat the first run as reconnaissance rather than a pass or fail signal.

Where the pipeline is thin, and when this is the wrong tool

The honest limitation is stated in the README itself. Provider-backed production evidence, human blind-review evidence, native permission execution and real-client telemetry are listed as separate evidence tasks, not finished features. If your release decision depends on those, the repository does not yet supply them, and the public claim guard exists precisely to stop you from asserting more than the evidence supports.

The second constraint is weight. A skill that lives in one client and one repository does not need a semantic IR, a compiler, an eval lab, a release lock and a curator report. Anthropic-style and OpenAI-style conversational skill creation, and plain instruction writing, are described in the README as approaches to keep where they fit; the project positions itself for packages that need evidence, portability, release gates and repeatable maintenance. Choosing it for a weekend prompt collection means maintaining a build pipeline for a file that changes twice a year.

The third is operational. The Makefile is long, the checks are numerous, and the README does not document rollback for a skill that has already been released to a team. If your team cannot run Python 3.11 in CI and cannot absorb a check suite that grows with the governance model, the maintenance cost lands on whoever owns the release, not on the tool.

How it differs from skill-creator style tooling

The closest comparison in practice is skill-creator style tooling, the conversational generators that scaffold a SKILL.md and iterate on the instructions with you. Those tools optimize the authoring moment: you describe the workflow, the assistant drafts the skill, you refine the wording. The artifact is the markdown file, and quality is judged by reading it.

yao-meta-skill accepts that authoring step and then adds everything after it. The artifact is a compiled package with a Skill IR behind it, target-specific surfaces in front of it, and an evidence ledger beside it. Quality is judged by trigger checks, output assertions, execution evidence, benchmark reproducibility and a review gate rather than by reading the entrypoint. The README's own comparison entry puts it plainly: keep the conversational creation and lean instruction writing where they fit, and use yao-meta-skill when the package needs evidence, portability, release gates and repeatable maintenance.

That difference also explains the repository's shape. A generator ships a template directory. This one ships schemas/, registry/, runtime/, evals/, evidence/, failures/ and a Makefile with dozens of checks, because the output is meant to be audited by someone who did not write it.

Maintenance status, licence and upgrade cost

The repository is not archived. Its last push was on 2026-08-17, roughly a month before this writing, so it is current enough to read as an active codebase, but there are no retrieved releases to point at, which means versioning information has to come from the VERSION file and the README's own 1.0 and 2.0 framing rather than from a changelog.

Upgrade cost is the part worth budgeting. The 1.0 to 2.0 table in the README shows the architecture changing from SKILL.md, agents/interface.yaml and manifest files to Skill IR, compilers, adapters, gate contracts, evidence ledgers and release locks. A skill written against the 1.0 shape does not automatically carry the 2.0 evidence model, and the Makefile includes an upgrade-check target, which implies the maintainers expect migrations rather than assuming compatibility. The README does not document a rollback path once a skill has been released under the new gates.

The licence is MIT, per the LICENSE file and the badge at the top of the README. That is permissive: you can reuse, modify and redistribute the code, including in closed products, provided the copyright notice and permission notice travel with it. It says nothing about the skills you generate with the tool, which are your own artifacts, and nothing about any third-party content you pull into a skill. That is a description of the licence text, not legal advice; if your organisation has a policy on generated artifacts, read the LICENSE yourself.

Editorial conclusion

Adopt yao-meta-skill if you maintain skills that other people install and you need the package to carry a contract, a target adapter and reviewable evidence before release. Do not adopt it for a single prompt you will paste into one client, and do not adopt it if you cannot run Python 3.11 in CI, because the Makefile's checks are the product. Before committing, run make python-version-check and python3 scripts/yao.py install-status --expected-source . in your own tree and confirm what the install status reports about duplicate active installs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. yaojingang/yao-meta-skill on GitHub