Created a Skill for interpreting Skills, now open-sourced on GitHub. The original design document for interpreting Skills has also been uploaded. This is a quality interpretation, learning analysis, and usage guidance Skill for the Agent Skills ecosystem. After execution, it converts a target Skill into structured analysis data and a bilingual HTML report. It helps us better learn and understand excellent Skills in the market, better use and evaluate Skills, and better improve and iterate Skills. The core architecture of this Skill adopts the design principle of “static parsing first, evidence chain throughout, report layer explanation.” When a target Skill enters the analyzer, it first performs safety preprocessing, then structural inventory, metadata parsing, content dissection, script and dependency analysis, risk scanning, scoring calculation, and report rendering. Download and deploy to AI terminals like Codex or Claude code, execute the input example: “Interpret Skill:https://github.com/yaojingang/yao-meta-skill…” and you will receive a complete Skill interpretation along with the interpretation report (see example images for details).

yaojingang/yao-meta-skill

Source: https://github.com/yaojingang/yao-meta-skill

Yao Meta Skill

CI (https://github.com/yaojingang/yao-meta-skill/actions/workflows/test.yml)
License: MIT
English 中文 日本語 Français Русский

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 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, 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
• a Browser/Chrome Native Messaging telemetry host that can receive length-prefixed metadata-only client events and generate a local launcher plus manifest without storing raw content
• a Skill Atlas drift layer that reads aggregate adoption reports and surfaces portfolio-level drift signals without packaging raw telemetry logs
• 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 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

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

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

Weighted Quality Benchmark

This benchmark is a project-level engineering review, scored from 0-10 per dimension and weighted to 100.
GitHub stars are intentionally excluded because they measure ecosystem heat, not meta-skill engineering quality.

Weighted score formula: sum(score / 10 * weight).

Best-Fit Scenarios

• Choose Yao Meta Skill when the target is a reusable team asset with explicit boundaries, trigger evaluation, governance, packaging, portability, and local execution checks.
• Choose Anthropic Skill Creator when the target is a conversation-first creation loop and the priority is human-guided iteration over repository-level governance.
• Choose OpenAI Skill Creator when the target is a compact reference for writing lean skill instructions and keeping context small.
• A practical hybrid pattern is still useful: draft conversationally, then use yao-meta-skill to harden the package, add evidence, and make it team-ready.

Quick Start

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 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-interpretation.html first for the bilingual interpretation report. It defaults to Simplified Chinese and provides an English switch in the top right. Then open reports/skill-overview.html for the audit scorecard and 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:

``bash
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 skill-interpretation my-skill
python3 scripts/yao.py review-viewer my-skill
python3 scripts/yao.py review-studio my-skill
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 adapt-scan my-skill –source ./curated-user-signals.jsonl
python3 scripts/yao.py adapt-propose my-skill
python3 scripts/yao.py daily-skillops my-skill –source ./curated-user-signals.jsonl
python3 scripts/yao.py weekly-curator my-skill
python3 scripts/yao.py adoption-drift my-skill –record-event skill_activation –activation-type explicit –outcome accepted
YAO_CLI_TELEMETRY=1 python3 scripts/yao.py validate my-skill
python3 scripts/yao.py telemetry-emit my-skill –event skill_activation –activation-type explicit –outcome accepted –command browser-extension
python3 scripts/yao.py telemetry-hooks my-skill
python3 scripts/telemetry_native_host.py my-skill –write-launcher /tmp/yao-telemetry-host.sh –write-manifest /tmp/yao-telemetry-host.json –allowed-origin chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/
python3 scripts/yao.py telemetry-import my-skill –input-jsonl /tmp/external-client-events.jsonl –command browser-extension
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 skill-ir . –output-json skill-ir/examples/yao-meta-skill.json
python3 scripts/yao.py compile-skill . –target openai –target claude –target generic –target vscode
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 python-compat .
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
python3 scripts/yao.py world-class-evidence . SUBMISSIONS_DIR=“{SUBMISSIONS_DIR:-evidence/world_class/submissions}" python3 scripts/yao.py world-class-preflight . --submissions-dir "SUBMISSIONS_DIR”
python3 scripts/yao.py world-class-submission-kit . –output-dir “$SUBMISSIONS_DIR”

Alternative: prefill artifact SHA-256 digests while keeping drafts template-only.

python3 scripts/yao.py world-class-submission-kit . –output-dir “SUBMISSIONS_DIR" --prefill-artifacts python3 scripts/yao.py world-class-intake . --submissions-dir "SUBMISSIONS_DIR”
python3 scripts/yao.py world-class-submission-review . –submissions-dir “SUBMISSIONS_DIR" python3 scripts/yao.py world-class-ledger . --submissions-dir "SUBMISSIONS_DIR”
python3 scripts/yao.py world-class-runbook . –submissions-dir “$SUBMISSIONS_DIR”
python3 scripts/yao.py world-class-claim-guard .
python3 scripts/yao.py benchmark-reproducibility .
python3 scripts/yao.py evidence-consistency .
``

Local Development Source

Development source: this repository is the source of truth for authoring and review.
Disabled mirror: ~/.agents/skills.disabled/yao-meta-skill is the local backup mirror for this source.
Keeping the mirror outside ~/.agents/skills prevents Codex from showing a duplicate Yao Meta Skill while this repository is also visible in the active workspace.

Sync the current source into the disabled mirror:

bash make sync-local-install

The sync command first rebuilds the package and runs install preflight against dist/yao-meta-skill.zip. It refuses to sync when package extraction, adapter readability, or installer permission enforcement fails.
After the preflight passes, it copies Git-tracked files plus new source files in code and guidance directories such as scripts/, tests/, references/, and docs/. It skips untracked business-skill folders and untracked private reports by default, so local experiments do not leak into the mirror.

Restore an active global Codex install only when you intentionally want this skill discoverable outside the development.