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 <detectable symptom>, first <repair action>. If still failing, <fallback or handoff>.

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-name>/
  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.