--- name: xiaoshiyilangzhao1996-droid/skillplus-create source: https://app.decimal.ai/s/xiaoshiyilangzhao1996-droid-skillplus-create@1/SKILL.md source_sha256: 6cf308847b1c --- # SKILL+ Create Use this skill to turn a repeatable workflow or project practice into a new Agent Skill that another agent can load, understand, execute, and evaluate. This skill creates a candidate skill package. It does not claim the skill is production-ready until evaluation evidence exists. ## Inputs Collect or infer: - Workflow goal and target user-agent. - Trigger phrases or task situations that should load the skill. - Existing artifacts: transcripts, task logs, PRs, docs, spreadsheets, screenshots, commands, prompts, or human SOPs. - Success examples, failure examples, and human corrections. - Expected output artifact and acceptance criteria. - Safety boundaries: external send, delete, deploy, finance, legal, private data, credentials, or irreversible actions. - Target harnesses such as Codex, Hermes, Claude Code, OpenCode, or a custom runner. If evidence is thin, create an experimental skill and mark missing evidence in the creation report. ## Workflow ### 1. Decide Whether A Skill Should Exist Create a skill only when at least one condition is true: - The workflow repeats across tasks or projects. - The agent repeatedly needs the same background, tool order, checks, or failure recovery. - Human corrections reveal a stable failure mechanism. - The task has an output contract or verification method. - The skill would reduce context explanation for future agents. Do not create a skill for one-off facts, unverifiable preferences, private details that cannot be sanitized, or tasks that require unstructured real-time human judgment. ### 2. Build The Experience Pool Classify evidence before writing: | Bucket | Use | |---|---| | `success_positive` | Extract procedures, tool order, verification habits, and reusable checklists. | | `failure_recovered` | Extract failure mechanisms, repair paths, and fallback logic. | | `failure_unrecovered` | Identify missing capability, missing tool, or boundary that the skill must expose. | | `human_gold` | Define human baseline, expected quality, and acceptance criteria. | Prefer a mixed pool. Do not build a skill only from failures unless the user explicitly wants a narrow remediation skill. ### 3. Propose The Skill Shape Decide the capability boundary: - `create`: no existing skill covers the capability. - `extend`: an existing skill covers the domain but lacks the observed failure mechanism. - `split`: the proposed skill would make an existing skill too broad. - `merge`: multiple proposed skills overlap and should become one capability package. The proposed skill must name the behavior change it should cause in the agent, not just the topic it describes. ### 4. Draft The Contract Write `SKILL.md` as a compact task contract: ```text Goal Inputs Workflow Failure Modes Verification Boundaries Runtime Resources Output Contract Handoff ``` Use a minimal contract for low-risk text-only skills. Use a full contract when the skill touches tools, files, external systems, privacy, publication, deployment, finance, legal, or multi-agent workflows. The frontmatter description must be a routing trigger. It should say when to load the skill, using task situations users actually say. ### 5. Add Runtime Resources Keep `SKILL.md` lean. Move detail into resources: - `references/` for long rules, domain notes, paper digests, examples of good/bad traces, and policy context. - `examples/` for sample inputs, expected outputs, and realistic prompts. - `scripts/` only when deterministic checks or repeated fragile operations exist. - `evals/` for routing, behavior, and outcome tasks. Every resource referenced in `SKILL.md` must have a clear load condition. Do not write machine-local absolute paths into reusable skill files. Use relative paths inside the skill package and cite public repository paths or paper names in references. ### 6. Encode Failures For each recurring failure, write an if/then recovery rule: ```text If , first . If still failing, . ``` Avoid vague instructions such as "be careful", "consider", "use judgment", or "handle appropriately" unless paired with concrete checks. ### 7. Prepare Evaluation Assets Create or request: - 5 to 10 training traces or examples when available. - 2 to 3 selection tasks or test prompts for first validation. - 3 to 5 held-out tasks before claiming production readiness. - A no-skill baseline when the harness can run it. - A human baseline note when comparing against office work. If no evaluation assets exist, include `experimental` status and a clear evidence gap. ### 8. Output The Skill Package Return or create: ```text / SKILL.md references/ examples/ scripts/ # optional; include only for deterministic checks or fragile repeated operations evals/ creation-report.md ``` `creation-report.md` must follow `references/creation-report-template.md` and include: - Why this skill should exist. - Evidence used and missing evidence. - Expected behavior change. - Safety boundaries. - Suggested selection/test tasks. - First-gate comparison plan. - Final decision: `accept`, `revise`, `merge_into_existing`, `split_required`, `reject`, or `blocked`. - Release status: `experimental`, `validated`, or `blocked`. ### 9. Run The Generated Skill First Gate Before calling the generated skill ready, compare: | Arm | Purpose | |---|---| | `no_skill` | Measures the agent's baseline without the new skill. | | `candidate_skill` | Measures whether the generated skill changes behavior in the intended direction. | | `human_gold` | Anchors quality against the original office workflow, SOP, or expert sample when available. | Use at least 2 selection prompts and 1 behavior prompt for first gate. For high-risk, public, external-send, or multi-agent skills, require 3 to 5 held-out tasks and human review. Decide: - `accept`: candidate beats or matches baseline, respects boundaries, and has no overlap risk. - `revise`: candidate is promising but fails a contract, routing, or verification requirement. - `merge_into_existing`: an existing skill should absorb the useful behavior. - `split_required`: the candidate bundles unrelated capabilities. - `reject`: the skill does not improve agent behavior or cannot be verified. - `blocked`: evidence, permissions, or evaluation assets are insufficient. ## Verification Before finishing: - Check routing: would an agent load this skill from description alone? - Check contract: are input, output, verification, boundaries, and handoff explicit? - Check runtime boundary: is `SKILL.md` compact and are resources indexed? - Check failure encoding: are known failures written as actionable if/then paths? - Check evaluation: is there at least a selection plan, even if not yet executed? - Check first gate: is there a no-skill/candidate/human-gold comparison plan or recorded result? - Check portability: are all reusable paths relative to the skill package or public source locations? ## Boundaries - Do not claim a new skill is production-ready without held-out evaluation or explicit human acceptance. - Do not store private traces, credentials, customer data, or internal secrets in reusable skill files. - Do not create overlapping narrow skills when one existing skill should be extended. - Do not make the skill a persona or hidden instruction override unless persona is the product. - Do not let the same agent-generated rationale substitute for validation evidence. ## Runtime Resources Load `references/source-mechanics.md` when you need the research and code mechanics behind this skill, especially Trace2Skill, EvoSkill, SkillLens, Skill-Schema-V2, SkillOpt, and darwin-skill. Load `references/creation-report-template.md` when producing `creation-report.md`. Use `examples/source-workflow.example.md` and `examples/generated-skill-review.example.md` only when the user needs a concrete example of the expected input or review output shape. Use `evals/test-prompts.json` when validating this skill or designing the first gate for a generated skill.