opencode-skills-collection 3.1.0 → 3.1.2

package/bundled-skills/yao-meta-skill/references/distribution-registry-method.md

@@ -0,0 +1,60 @@
+# Distribution Registry Method
+
+Registry metadata turns a local skill directory into an installable and reviewable package record.
+
+## When To Use
+
+Use registry audit for library, governed, team-distributed, or upgrade-sensitive skills. Scaffold skills can skip it until reuse is real.
+
+## Required Evidence
+
+- package name, version, owner, maturity, review cadence, and license
+- Skill IR source and schema version
+- trust level and package SHA256
+- package verification status and archive SHA256 when a zip distribution is built
+- install simulation status when an archive is meant to be installed locally or by a team
+- adoption/drift aggregate status when local telemetry exists
+- target compatibility matrix
+- upgrade diff, recommended version bump, and breaking-change notes when a previous package baseline exists
+- links to overview, Review Studio, trust report, conformance matrix, package verification, install simulation, adoption drift evidence, and review waivers
+
+## Release Rule
+
+Do not publish a team package when registry audit reports missing version, hash, owner, review cadence, license, valid Skill IR, or passing compatibility for declared targets.
+
+For an installable archive, first build the distribution and run package verification:
+
+```bash
+python3 scripts/yao.py package . --platform openai --platform claude --platform generic --platform vscode --output-dir dist --zip
+python3 scripts/yao.py package-verify . --package-dir dist --require-zip
+python3 scripts/yao.py install-simulate . --package-dir dist
+python3 scripts/yao.py registry-audit .
+python3 scripts/yao.py upgrade-check . --previous-package-json registry/examples/yao-meta-skill-1.0.0.json
+```
+
+Do not claim archive readiness when package verification reports unsafe zip paths, missing target adapters, missing package manifest, registry metadata mismatch, or unreadable archive contents.
+
+Do not claim install readiness when install simulation cannot extract the archive into a temporary skill root, load `SKILL.md` frontmatter, read `manifest.json`, read `agents/interface.yaml`, find the overview and Review Studio reports, or load each generated adapter.
+
+Do not sync a local or active install from source until the same package has passed install preflight. `scripts/sync_local_install.py` must run install simulation against the configured package directory and fail before copying files when any target/capability pair lacks active permission approval or target-specific enforcement evidence. Use `--skip-install-preflight` only for isolated diagnostics, not for release or active install.
+
+Do not include raw `reports/telemetry_events.jsonl` in a distributed package. Include only aggregate adoption drift reports, and block release review when telemetry contains raw prompts, outputs, transcripts, notes, or messages.
+
+Review waiver evidence may be distributed as `reports/review_waivers.md/json` because it is metadata-only reviewer accountability. Do not store raw prompts, outputs, transcripts, credentials, or private customer detail in waiver reasons.
+
+Do not claim upgrade readiness when upgrade check reports an insufficient version bump, target removal without a major bump, compatibility regression without a major bump, package name change, or invalid semver. Include `reports/upgrade_check.md` in the reviewer evidence bundle so release notes and migration guidance are tied to the exact registry diff.
+
+## Reviewer Gate
+
+A reviewer should be able to answer:
+
+1. Which package version is being installed?
+2. Who owns the package?
+3. Which targets are compatible?
+4. Which checksum identifies the reviewed package contents?
+5. Which reports prove trust and runtime readiness?
+6. Was the installable archive verified, and which checksum identifies it?
+7. Was the archive install-simulated in a temporary local skill root?
+8. Did local or active install sync preserve that preflight and installer permission gate?
+9. What changed since the previous package, and does the declared version bump match the recommended bump?
+10. Are adoption and drift signals summarized without packaging raw local telemetry?

package/bundled-skills/yao-meta-skill/references/eval-playbook.md

@@ -0,0 +1,69 @@
+# Trigger And Eval Playbook
+
+Use this playbook for skills that matter enough to test.
+
+## A. Trigger Evaluation
+
+Create three prompt buckets:
+
+### 1. Should Trigger
+
+Prompts that clearly need the skill.
+
+Goal:
+
+- verify recall
+
+### 2. Should Not Trigger
+
+Prompts that are clearly outside the skill boundary.
+
+Goal:
+
+- verify precision
+
+### 3. Near Neighbors
+
+Prompts that look similar but should use another skill or no skill.
+
+Goal:
+
+- catch false positives and ambiguous routing
+
+## B. Execution Evaluation
+
+For each important use case, create 1 to 3 realistic prompts with:
+
+- user-like phrasing
+- representative inputs or file types
+- expected output description
+- key checks
+
+## C. Revision Loop
+
+When a skill underperforms:
+
+1. Fix boundary or description problems before adding more body text.
+2. Move brittle logic into scripts or templates.
+3. Split reference content if `SKILL.md` becomes bloated.
+4. Re-run the same eval set before expanding scope.
+
+## D. Minimum QA By Skill Tier
+
+### Personal skill
+
+- 2 realistic prompts
+- manual review
+
+### Team skill
+
+- 3 to 5 realistic prompts
+- trigger positives and negatives
+- one revision loop
+
+### Infrastructure or meta-skill
+
+- 5+ execution prompts
+- trigger positives, negatives, and near neighbors
+- benchmark notes across revisions
+- ownership and drift review

package/bundled-skills/yao-meta-skill/references/gate-selection.md

@@ -0,0 +1,68 @@
+# Gate Selection
+
+Gate selection should track risk. More gates are not automatically better.
+
+## Minimum Gates By Risk
+
+| Risk Level | Typical Archetype | Required Gates |
+| --- | --- | --- |
+| low | Scaffold | `validate_skill.py`, `resource_boundary_check.py` |
+| medium | Production | low-risk gates plus `trigger_eval.py` |
+| high | Library | medium-risk gates plus `optimize_description.py`, route confusion, packaging validation |
+| critical | Governed | high-risk gates plus governance scoring, regression history, promotion policy |
+
+## Trigger Gates
+
+Use trigger gates when:
+
+- a route can be confused with a nearby skill
+- the workflow will be reused by multiple people
+- the skill boundary must be defended over time
+
+Trigger gates, in order:
+
+1. `trigger_eval.py`
+2. `optimize_description.py`
+3. blind holdout
+4. judge-backed blind holdout
+5. adversarial holdout
+6. route confusion
+
+## Packaging Gates
+
+Use packaging gates when:
+
+- output must be consumed by multiple clients
+- metadata drift would break discoverability
+- portability is part of the skill's value
+
+Packaging gates:
+
+- `validate_skill.py`
+- `cross_packager.py`
+- packager failure fixtures
+- adapter snapshot checks
+
+## Governance Gates
+
+Use governance gates when:
+
+- the skill is shared infrastructure
+- the skill has an owner and review cadence
+- lifecycle state matters
+
+Governance gates:
+
+- `governance_check.py`
+- regression history
+- maturity scoring
+- promotion policy
+
+## Context Gates
+
+Use context gates on every non-trivial skill.
+
+- `context_sizer.py`
+- `resource_boundary_check.py`
+
+If rigor increases but initial load crosses the tier budget, move detail into `references/`, `scripts/`, or `reports/` before adding more checks.

package/bundled-skills/yao-meta-skill/references/governance.md

@@ -0,0 +1,134 @@
+# Governance Model
+
+This project treats important skills as governed assets rather than one-shot prompt files.
+
+## Goals
+
+- keep shared skills trustworthy over time
+- make ownership explicit
+- avoid stale or oversized skill packages
+- define when a skill should evolve, split, or retire
+
+## Required Governance Metadata
+
+For reusable or library-grade skills, `manifest.json` should include:
+
+- `name`
+- `version`
+- `owner`
+- `updated_at`
+- `review_cadence`
+- `status`
+- `maturity_tier`
+- `lifecycle_stage`
+
+## Allowed Values
+
+### `status`
+
+- `experimental`
+- `active`
+- `deprecated`
+
+### `maturity_tier`
+
+- `scaffold`
+- `production`
+- `library`
+- `governed`
+
+### `lifecycle_stage`
+
+- `scaffold`
+- `production`
+- `library`
+- `governed`
+
+### `review_cadence`
+
+- `monthly`
+- `quarterly`
+- `semiannual`
+- `annual`
+- `per-release`
+
+## Governance Rules
+
+### 1. Owner Required
+
+Any skill meant for reuse must have a named owner or owning team.
+
+### 2. Review Cadence Required
+
+If a skill is shared, it must declare how often it should be reviewed.
+
+### 3. Maturity Should Match Rigor
+
+- `scaffold`: lightweight, personal, low-governance
+- `production`: reusable team skill with validation
+- `library`: curated shared skill with explicit packaging and evals
+- `governed`: critical or meta-level skill with regression, maintenance, and review expectations
+
+### 4. Deprecated Skills Need Explicit Intent
+
+Deprecated skills should include a deprecation note or replacement reference in adjacent documentation or manifest extensions.
+
+### 5. Drift Must Be Observable
+
+Important skills should keep:
+
+- a regression history
+- visible evaluation results
+- known anti-patterns or failure modes
+
+## Governance Actions
+
+Use governance review to decide whether a skill should:
+
+- stay as-is
+- tighten trigger boundaries
+- split into sibling skills
+- move detail into `references/`
+- move brittle logic into `scripts/`
+- be deprecated or replaced
+
+## Governance Maturity Scoring
+
+`scripts/governance_check.py` also computes a maturity score out of `100`.
+
+### Score Buckets
+
+The governance checker computes a score band in addition to the declared manifest tier. The score band is a diagnostic output, not a replacement for the declared lifecycle tier.
+
+- `90-100`: governed
+- `80-89`: production
+- `65-79`: reusable
+- `45-64`: emerging
+- `<45`: draft
+
+### Recommended Minimums For Declared Tiers
+
+- `scaffold`: no hard minimum
+- `production`: `80`
+- `library`: `85`
+- `governed`: `90`
+
+### Score Dimensions
+
+- metadata integrity
+- ownership and review cadence
+- boundary and eval evidence
+- operational assets
+- maintenance evidence
+
+The score is not a replacement for human review. It is a fast signal that a shared skill is structured enough to be trusted, maintained, and audited. `scripts/governance_check.py` warns when a declared tier claims more rigor than the score currently supports.
+
+## Why This Matters
+
+Most skill systems stop at creation. World-class skill systems also manage:
+
+- ownership
+- drift
+- maturity
+- deprecation
+- evidence of ongoing quality

package/bundled-skills/yao-meta-skill/references/human-review-template.md

@@ -0,0 +1,54 @@
+# Human Review Template
+
+Use this template when a description candidate is ready for human review after automated gates have run.
+
+## Review Header
+
+- target:
+- review date:
+- reviewer:
+- current description:
+- candidate description:
+- promotion decision:
+
+## What Changed
+
+- what was the intended improvement?
+- what route boundary is now clearer?
+- what family or holdout behavior improved?
+
+## Automated Evidence
+
+- visible holdout result:
+- blind holdout result:
+- judge-backed blind result:
+- adversarial result:
+- route confusion result:
+- calibration / risk band:
+
+## Boundary Questions
+
+- does the candidate trigger only when a reusable skill package is actually needed?
+- does it avoid one-off explanation, translation, or summary-only requests?
+- does it avoid stealing sibling routes?
+- does it stay short enough for the target maturity tier?
+
+## Authoring Discipline
+
+- are unresolved assumptions named or clarified before deepening the package?
+- is the package no larger than the real recurring job requires?
+- do changed files trace directly to the requested improvement?
+- did the author avoid speculative features, decorative folders, and generic configuration?
+- does each new artifact have a verification reason?
+
+## Decision
+
+- approve promotion
+- keep current
+- block candidate
+
+## Notes
+
+- rationale:
+- follow-up actions:
+- next review trigger:

package/bundled-skills/yao-meta-skill/references/intent-dialogue.md

@@ -0,0 +1,138 @@
+# Intent Dialogue
+
+Use a short, human conversation before deep authoring so the first version of the skill is anchored in the real job rather than in a guessed prompt shape.
+
+## Why This Step Exists
+
+- raw workflow material is often incomplete, mixed, or ambiguous
+- the wrong boundary chosen early is expensive to repair later
+- good trigger design depends on knowing what should not route here
+- execution assets should follow confirmed outputs, not assumptions
+
+## What To Capture
+
+Ask only the questions that change the package design.
+
+1. If this worked beautifully, what recurring job would it quietly take off the user's plate?
+2. What real inputs would people actually hand to it?
+3. What finished output should it hand back so the user can keep moving?
+4. What near-neighbor requests should it politely refuse?
+5. What matters most here: speed, consistency, auditability, portability, governance, or tone/style fit?
+6. Are there any public or private references the user wants this skill to learn from? Only borrow patterns, never copy wording or private material.
+7. What assets already exist: docs, scripts, templates, examples, or prior prompts?
+8. What constraints matter: privacy, naming, local library fit, or target environments?
+
+## Interview Rule
+
+- prefer `5-7` sharp questions over a long discovery questionnaire
+- start with a calm, human framing before switching into precise design questions
+- guide like a patient teacher or thoughtful coach, not like a rigid intake clerk
+- mirror the user's language and emotional temperature
+- first invite a natural explanation, then offer a lightweight template only as an option
+- ask boundary questions early
+- ask output questions before architecture questions
+- stop once the skill can be described clearly in one sentence
+- do not enter deep authoring until the recurring job, target output, and exclusion boundary are clear enough to defend
+
+## First Message Pattern
+
+The first message should feel like guided co-creation, not form filling.
+
+Recommended flow:
+
+1. briefly acknowledge the user's seed idea
+2. explain that you want to first understand the real recurring work and what a good outcome looks like
+3. invite the user to describe it naturally in their own words
+4. offer a tiny scaffold only if they want a shortcut
+
+Good example shape:
+
+- `Let's make this easy. Tell me what kind of repeated work you want this skill to quietly take over, what people will hand to it, and what a useful finished result should look like. If you want, I can also give you a tiny template to fill in.`
+
+Warmer guidance:
+
+- sound like you are sitting beside the user, helping them sort out a half-formed idea
+- do not rush into system terms such as `archetype`, `gate`, or `package` in the first breath
+- name the user's possible feeling: fuzzy, scattered, not fully formed, hard to describe
+- make it feel safe to answer imperfectly
+- offer to help extract structure after they speak naturally
+
+Bad example shape:
+
+- `Name:`
+- `One-line capability:`
+- `Real input:`
+- `Target output:`
+
+The second pattern is allowed only when the user explicitly asks for a structured template.
+
+## Chinese First-Turn Opening Patterns
+
+Use these as tone references when the conversation is in Chinese. Do not copy them mechanically; adapt them to the user's context and voice.
+
+### 温柔陪伴型
+
+适合：用户想法还比较模糊，或者需要先被接住。
+
+示例：
+
+- `我们先别急着定结构，你就像跟我聊天一样说说看：你最想让这个 skill 以后帮你稳稳接住哪一类重复工作？它如果做得很理想，最后应该交回你一个什么样的结果？`
+- `没关系，现在不完整也可以。你先把脑子里已经有的部分告诉我，我来帮你一点点收拢成一个清晰的 skill。`
+- `你可以先说个大概，比如“它以后主要帮我处理什么”、“别人通常会丢给它什么材料”、“我希望它最后产出什么”，剩下的我再陪你一起补齐。`
+
+### 专业教练型
+
+适合：用户目标明确，希望被高效带着走，但仍然不想面对生硬表单。
+
+示例：
+
+- `我们先把这件事讲清楚，再决定 skill 怎么设计。你先告诉我三件事：它最核心要接住的重复任务是什么，别人会给它什么输入，最后你希望它交付什么结果。`
+- `我先不让你填模板。你先用自己的话说说：这件事做成以后，最重要的价值是什么，哪些相近请求你反而不希望它处理。`
+- `先把业务和结果说清楚，结构我来替你提炼。你只要告诉我：它该做什么、不该做什么、做好以后对你有什么帮助。`
+
+### 共创伙伴型
+
+适合：用户有一定想法，希望一起打磨，而不是被问卷式采集。
+
+示例：
+
+- `我们把它当成一次共创来做。你先说说这个 skill 最值得被做出来的地方是什么，我再帮你把边界、输入和输出慢慢收成一个可复用的包。`
+- `你可以先丢给我一个粗糙版本，不用一次说完整。我会先帮你看它真正的核心任务是什么，再一起决定要不要加规则、脚本或评测。`
+- `如果你愿意，我们可以先从“理想中的它能帮你省掉什么麻烦”开始聊，然后再往下收敛成 skill 的能力边界。`
+
+### Lightweight Optional Scaffold
+
+Only offer this after the natural opening, not before.
+
+示例：
+
+- `如果你懒得一点点讲，我也可以给你一个很小的版本，你只填这几项就行：它最想接住的事、常见输入、理想输出、明确不做什么。`
+- `如果你更习惯结构化一点，我可以把问题收成 4 行小模板；如果你想自然讲，也完全可以直接说。`
+
+## Output
+
+The dialogue should produce:
+
+- one clear capability sentence
+- a list of real inputs
+- a list of required outputs
+- a short exclusion list
+- a note on user-supplied references or benchmark preferences
+- one recommended archetype
+- one recommended first evaluation target
+
+## Failure Pattern
+
+Do not continue into full authoring when the dialogue still leaves these unresolved:
+
+- whether the request is really reusable
+- which near-neighbor requests should not trigger
+- what concrete deliverable the skill must return
+
+If one of these is unresolved, ask the smallest possible follow-up that will unlock the design. Do not compensate by adding extra references, scripts, or governance.
+
+Also treat these as dialogue failures:
+
+- the first reply feels like a cold worksheet instead of a guided conversation
+- the user is forced into a full template before the real job is understood
+- the assistant asks for package structure before clarifying the desired outcome

package/bundled-skills/yao-meta-skill/references/iteration-philosophy.md

@@ -0,0 +1,30 @@
+# Iteration Philosophy
+
+The first skill package is a routeable baseline, not the final answer.
+
+## Principle
+
+Improve the skill by the smallest change that increases reliability more than it increases context cost.
+
+## What Good Iteration Looks Like
+
+- tighten boundary before adding prose
+- improve description before enlarging the file tree
+- add references only when they remove ambiguity
+- add scripts only when deterministic logic repeats
+- add gates only when risk justifies maintenance cost
+- prefer one strong next step over five vague upgrades
+
+## Default Priority Order
+
+1. trigger clarity and exclusions
+2. execution assets that remove repeated manual work
+3. promotion, governance, and portability only when reuse justifies them
+
+## First-Version Rule
+
+After the initial package is created, always surface the three highest-value next iteration directions. This keeps the author focused on the best improvement path instead of expanding the skill in every direction at once.
+
+## Anti-Pattern
+
+Do not treat iteration as "make the package bigger." A larger package is only better when routing, execution, or governance becomes materially more reliable.

package/bundled-skills/yao-meta-skill/references/non-skill-decision-tree.md

@@ -0,0 +1,39 @@
+# Non-Skill Decision Tree
+
+Do not build a skill when the user really wants a direct answer or a lightweight artifact.
+
+## Use A Direct Answer Instead
+
+Prefer a normal response when the job is:
+
+- explain a concept
+- summarize a document
+- translate text
+- brainstorm ideas without packaging
+- answer a one-off question
+
+## Use A Document Instead
+
+Prefer a document or note when the output is:
+
+- wiki or knowledge-base content
+- a reusable-looking document with no agent execution
+- a policy memo
+- a handoff note
+
+## Use A Script Instead
+
+Prefer a script without a full skill when:
+
+- the task is deterministic
+- routing is not the hard part
+- the user wants a utility, not a routed capability
+
+## Promote To A Skill Only When
+
+- the job is recurring
+- discoverability matters
+- the workflow needs a boundary
+- the process benefits from reusable instructions or checks
+
+If there is doubt, start with `Scaffold` and upgrade only after reuse becomes real.