yao-meta-skill

Yao Meta Skill

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 creates, evaluates, packages, and governs reusable agent skills. The 1.0 line focused on turning repeated workflows into installable, readable, cross-platform skill packages. The 2.0 line expands that factory into a Skill OS: a governed system for modeling a skill once, compiling it for multiple targets, testing its behavior, reviewing its release evidence, and tracking the next iteration.

Quick Start · Skill OS 2.0 · 1.0 vs 2.0 · Operator UX · Benchmark · Examples · Evals · Failure Library · Method Doctrine

Skill OS 2.0 Upgrade

Skill OS 2.0 keeps the original promise of yao-meta-skill, but makes the package lifecycle more explicit. Instead of stopping at SKILL.md, it adds a semantic contract, target compilers, evaluation evidence, release gates, and operation reports around the skill.

• Skill IR: a platform-neutral intermediate representation for intent, triggers, inputs, outputs, boundaries, references, and expected artifacts.
• Target compilers and adapters: generated surfaces for OpenAI, Claude, generic agent skills, Agent Skills compatible packages, and VS Code-oriented workflows.
• Output Eval Lab: trigger checks, output assertions, execution evidence, timing and token evidence, benchmark reproducibility, blind-review packs, answer keys, and adjudication reports.
• Review Studio 2.0: a single HTML gate page for intent, triggers, output eval, context cost, runtime checks, trust, Skill Atlas signals, adoption drift, waivers, annotations, release evidence, warnings, blockers, and fix actions.
• Evidence and release governance: evidence consistency checks, package verification, install simulation, runtime permission probes, world-class evidence intake, world-class ledger, operator runbook, and public claim guard.
• SkillOps loop: metadata-only adoption drift, telemetry hooks, adaptive proposals, daily and weekly curator reports, and portfolio-level drift signals.

Current posture: the repository is ready for beta and external testing, while stronger public "world-class" claims remain evidence-gated. Provider-backed production evidence, human blind-review evidence, native permission execution, and real-client telemetry are tracked as separate evidence tasks instead of being treated as completed work.

See the companion artifacts:

• Visual 1.0 vs 2.0 comparison report
• Chinese desktop preview
• English desktop preview

From 1.0 to 2.0

2.0 Use Cases

• Create a new skill from repeated work: start with a workflow note, prompt set, transcript, runbook, or document pattern, then generate a package with a lean entrypoint, explicit inputs and outputs, references, reports, and the lightest justified gates.
• Upgrade a personal skill into a team asset: add interface contracts, manifests, target adapters, trust checks, output evals, reviewer waivers, release notes, and Review Studio evidence before other people depend on the skill.
• Prepare a skill for beta release: run package verification, install simulation, compatibility checks, runtime permission probes, and evidence consistency checks, then separate beta readiness from stronger public claims.
• Keep a skill useful after release: use metadata-only telemetry, adoption drift, feedback logs, SkillOps reports, and adaptive proposals to decide whether the next move should be documentation, an eval, a skill patch, or a governance update.
• Compare with other meta-skill approaches: keep Anthropic/OpenAI-style conversational creation and lean instruction writing where they fit, then use yao-meta-skill when the package needs evidence, portability, release gates, and repeatable maintenance.

Operator UX Commands

These read-only helper commands turn common maintainer questions into repeatable diagnostics:

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

• install-status explains whether the active skill is coming from .codex/skills, .agents/skills, or the disabled mirror, and flags duplicate active installs.
• localized-doc-sync-check verifies that the Chinese README carries the public homepage sections that were added to the English README.
• pr-review-report reads GitHub PR metadata, changed files, status checks, and suggested local commands without merging or mutating the PR.

Capability Surface

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
• an inference-first intent dialogue that asks one personalized question only for core task, output, or direction forks, stops after two rounds, and records structured assumptions without retaining a full transcript
• 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, adoption drift, reviewer waivers, reviewer annotations, release evidence, and per-warning fix actions
• a Skill OS 2.0 audit that maps each world-class requirement to current evidence, human-required gaps, and external-required gaps
• a Skill OS 2.0 blueprint coverage report that maps the upgrade plan's core modules and recommended PRs to concrete artifacts, commands, and tests
• a world-class evidence plan that turns remaining provider, human, native-permission, and real-client telemetry gaps into executable evidence tasks
• a world-class evidence ledger that records which external and human evidence is accepted or still pending without treating planned work as proof
• a world-class evidence intake contract that validates external and human evidence packets for provenance, privacy, artifact refs, and anti-overclaim rules before ledger review
• a redacted world-class preflight report that checks local files, environment readiness, human/external prerequisites, and source blockers before operators collect evidence
• a world-class submission review queue that compares evidence packets, intake validation, source artifacts, and ledger state without accepting evidence
• a world-class operator runbook that gives reviewers the exact commands, artifacts, and collection checklist needed to close remaining evidence gaps
• a world-class claim guard that scans public claim surfaces and blocks premature completed/true claims while the evidence ledger still has pending external or human evidence
• a benchmark reproducibility manifest that checks methodology sections, required artifacts, failure disclosure, and reproduction commands
• an evidence consistency gate that compares generated reports against each other so benchmark, overview, interpretation, adoption, world-class ledger, coverage, and Review Studio facts do not drift silently
• 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 Python compatibility gate that catches supported-runtime syntax hazards before they reach GitHub Actions or packaged distribution
• 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, with optional yao.py CLI run capture, external client event emit hooks, hook recipes, and JSONL import that record command names and outcomes without arguments or raw content
• an explicit-source adaptive proposal loop that summarizes redacted repeated user preferences and generates approval-gated adaptation proposals without scanning private logs or writing source files
• a SkillOps opportunity scorer and decision policy that ranks redacted repeated signals, maps them to report-only, AGENTS update, existing-skill patch, or eval-addition actions, and keeps every durable write approval-gated
• a weekly SkillOps curator report that aggregates daily opportunities, Skill Atlas portfolio signals, release lock state, and world-class evidence gaps into a proposal-only maintenance queue