Agent skill
method:create
Codex-powered compiler for turning a natural-language workflow description into a method skill that matches the live corpus. 5 phases: Intake -> Analysis -> Authoring -> Validation -> Refinement. Codex workers handle analysis, file generation, and quality gate; Claude does intake and a final refinement pass optimized for Claude Code. Use when you want to create a method, compile a method, author a method skill, or turn this workflow into a method. Not for editing existing methods, not a runtime engine, and not for one-off prompts.
Install this agent skill to your Project
npx add-skill https://github.com/petekp/claude-code-setup/tree/main/skills/method-create
SKILL.md
Method Create
This skill compiles a workflow description into a method skill pair:
method.yaml for topology and SKILL.md for runtime truth. The artifact chain
is `workflow-brief.md -> method-analysis.md -> draft-method.yaml + draft-SKILL.md
- cross-validation.md -> validation-report.md -> method.yaml + SKILL.md`.
Codex workers do the heavy lifting: pattern analysis, file generation, and quality validation. The orchestrator handles intake (interactive) and a final refinement pass that optimizes the generated method for Claude Code — trigger metadata, dispatch patterns, skill discovery, and session ergonomics.
This is a compiler, not a runtime engine. It can author either artifact-centric
delivery methods or validator methods, but it does not execute the generated
method. After authoring, recommend method:dry-run before anyone trusts the
result for real work.
When to Use
- You want to create a new method from a natural-language workflow description
- You want to turn a proven multi-phase workflow into a reusable method skill
- You need to decide whether the workflow is an artifact-centric method or a validator
- You need both
method.yamlandSKILL.mdto match the live corpus
Do NOT use for editing an existing method, building a runtime engine, or wrapping a tiny one-off prompt in unnecessary method structure.
Glossary
- Artifact - A durable method output file under
${RUN_ROOT}/artifacts/unless the step explicitly writes a final deliverable toTARGET_METHOD_ROOT. - Runtime truth - The execution contract in
SKILL.md: commands, paths, headers, gates, resume rules, and adapter seams. - Topology metadata - The ordered phase and step structure in
method.yaml. - Method family - The live branch the workflow fits: artifact-centric or validator.
- Cross-validation - The field-by-field comparison that proves the authored
method.yamlandSKILL.mdagree. - Adapter seam - A dispatch boundary such as
manage-codexwhose runtime contract must be described explicitly in prose.
Principles
- Compiler, not runtime.
method:createauthors a method skill. It does not execute the generated workflow and it is not itself amanage-codexmethod. - Codex generates, Claude refines. Codex workers handle analysis, authoring, and quality validation. The orchestrator handles intake and a final refinement pass that optimizes for Claude Code.
SKILL.mdis runtime truth. Treatmethod.yamlas topology only. If the files disagree, the method is mechanically broken.- Frontmatter does trigger work. The generated
nameanddescriptiondecide whether the skill is discoverable at all. - Step granularity is a contract. YAML topology steps must match prose topology steps. Worker detail may expand inside one step; topology may not drift.
- Cross-validate before dry-run. Codex cross-validates during authoring; Claude verifies during refinement. Both passes are mandatory.
- Trip the circuit breaker early. If the workflow does not fit the live method contract, say so instead of forcing a fake method.
Setup
WORKFLOW_SOURCE="<inline-description-or-path>"
TARGET_METHOD_SLUG="<new-method-slug>"
TARGET_METHOD_ROOT="${HOME}/.claude/skills/method/${TARGET_METHOD_SLUG}"
RUN_ROOT=".relay/method-runs/${TARGET_METHOD_SLUG}-method-create"
STAGING="${RUN_ROOT}/staging"
mkdir -p "${RUN_ROOT}/artifacts" "${STAGING}" \
"${RUN_ROOT}/handoffs" "${RUN_ROOT}/last-messages" \
"${TARGET_METHOD_ROOT}"
Record these inputs before authoring:
WORKFLOW_SOURCE- the user's workflow description, notes, or source fileTARGET_METHOD_SLUG- the generated method directory name (undermethod/)TARGET_METHOD_ROOT- where the finalmethod.yamlandSKILL.mdwill liveRUN_ROOT- where relay state, compiler artifacts, and staging drafts liveSTAGING- where Codex workers write draft files (sandbox cannot write to~/.claude/)
The method: prefix is added automatically to the frontmatter name field. For
example, slug foo-bar produces name: method:foo-bar and lives at
~/.claude/skills/method/foo-bar/.
Domain Skill Selection
method:create does not need autonomous workers by default. When the workflow
you are compiling includes dispatch steps, author them with these limits:
- Default to 1-2 domain skills and at most 3 total skills per autonomous dispatch
- Never append interactive skills to
codex exec --full-auto - Document any exception to the skill-budget ceiling explicitly in the generated method
Canonical Header Schema
Every generated dispatch step should point back to this header contract unless the author has a stronger, step-specific reason to inline a fuller variant.
# Step N: <title>
## Mission
[What the worker must accomplish]
## Inputs
[The exact artifacts, digests, or external inputs the worker reads]
## Output
- **Path:** [exact path where the worker must write its primary artifact]
- **Schema:** [required sections or headings]
## Success Criteria
[What done means for this step]
## Handoff Instructions
Write your primary output to the path above. Also write a standard handoff to
`handoffs/handoff.md` with these exact section headings:
### Files Changed
### Tests Run
### Verification
### Verdict
### Completion Claim
### Issues Found
### Next Steps
Those relay headings are not cosmetic. compose-prompt.sh checks for
### Files Changed, ### Tests Run, and ### Completion Claim. If they are
missing, it may append relay-protocol.md and leak unresolved placeholders into
the worker prompt.
Key Rules
Runtime Source Of Truth
- Put identity, phase order, step order, actions, artifacts, fanout shape, and
coarse gate types in
method.yaml - Put commands, paths, output schemas, prompt headers, resume rules, fallback
synthesis, adapter seams, and reopen choreography in
SKILL.md - Treat drift between the two files as a mechanical defect, not a documentation nit
Trigger Metadata
- Generated frontmatter must contain only
nameanddescription namemust be kebab-case and match the method directorydescriptionmust encode trigger phrases, method shape, and negative scope- Weak metadata like "helps with workflows" is structurally legal and operationally poor
Prose And YAML Granularity
- Keep phases serial
- Represent parallelism only as intra-step fanout with
execution: parallelandworkers - Keep YAML topology step count aligned with prose topology step count
- Expand worker detail under one step instead of inventing extra topology steps
Diagnose-Only Review Contract
When a generated review step is assessment only, say so explicitly:
This step is assessment only - the worker does NOT modify source code.
Also define:
- who performs remediation if issues are found
- the bounded verdict vocabulary
- the reopen or rerun rule
Adapter Seam Contract
If the generated workflow uses adapter: manage-codex, the generated SKILL.md
must include all of the following:
- child root creation
CHARTER.mdcreation from the parent execution contract- the real
compose-prompt.shandcodex exec --full-autocalls - required child files:
CHARTER.md,batch.json,handoffs/handoff-<slice-id>.md, andhandoffs/handoff-converge.md - readback order:
handoff-converge.md, thenbatch.json, then the last slice handoff - outer synthesis rules for the parent artifact
- escalation behavior if convergence says
ISSUES REMAIN
Reference Pack
These sections are the inline authoring reference. A fresh session should not need the original review package open beside the generated method.
Canonical method.yaml Starter
schema_version: "1"
method:
id: your-method-slug
version: "YYYY-MM-DD"
title: Your Method Title
description: >
One-sentence method thesis. Topology only - this file does not encode runtime
behavior or adapter contracts.
phases:
- id: framing
title: Framing
execution: serial
steps:
- id: intake
title: Intake
action: interactive
produces: brief.md
gate:
type: outputs_present
required: [brief.md]
checks:
- "Decision or problem statement non-empty"
- id: evidence
title: Evidence
execution: serial
steps:
- id: parallel-probes
title: Parallel Probes
action: dispatch
execution: parallel
workers:
- id: probe-a
title: Probe A
skills: [deep-research]
produces: probe-a.md
- id: probe-b
title: Probe B
skills: []
produces: probe-b.md
consumes: [brief.md]
produces: [probe-a.md, probe-b.md]
gate:
type: outputs_present
required: [probe-a.md, probe-b.md]
checks:
- "Both worker artifacts exist and follow the promised schema"
- id: synthesis
title: Synthesis
action: synthesis
consumes: [probe-a.md, probe-b.md]
produces: packet.md
gate:
type: outputs_present
required: [packet.md]
checks:
- "Named sections present"
- id: delivery
title: Delivery
execution: serial
steps:
- id: implement
title: Implement
action: dispatch
adapter: manage-codex
consumes: [packet.md]
produces: implementation-handoff.md
max_attempts: 3
notes: >
Delegates to manage-codex. Orchestrator creates CHARTER.md and
synthesizes the outer handoff from child workflow artifacts.
- id: validate
title: Final Review
action: dispatch
consumes: [packet.md, implementation-handoff.md]
produces: review.md
gate:
type: verdict-reopen
outcomes:
ready: continue
revise: interactive-reopen
Artifact-Centric SKILL.md Starter
---
name: your-method-slug
description: >
Artifact-driven method for [goal]. [N] steps across [M] phases: [Phase A] ->
[Phase B] -> [Phase C]. Use when [positive trigger]. Do not use for
[negative trigger].
---
# Your Method
One or two paragraphs stating the artifact chain, why it exists, and what kind
of failure it prevents.
## When to Use
- Specific trigger 1
- Specific trigger 2
- Specific trigger 3
Do NOT use for [negative scope].
## Glossary
- **Artifact** - Durable method output under `${RUN_ROOT}/artifacts/`.
- **Worker handoff** - Raw relay output, not the canonical artifact chain.
- **Synthesis** - Orchestrator-authored artifact created from upstream artifacts.
## Principles
- **Artifacts, not commentary.** Every step exits with a durable file.
- **Self-contained headers.** Dispatch prompts do not rely on implied template behavior.
- **Reopen on disconfirming evidence.** Invalidating evidence changes the workflow.
## Setup
```bash
RUN_SLUG="<topic-slug>"
RUN_ROOT=".relay/method-runs/${RUN_SLUG}"
mkdir -p "${RUN_ROOT}/artifacts"
```
## Domain Skill Selection
[Skill budget, domain mapping, and exclusions]
## Canonical Header Schema
[The shared header contract]
## Phase 1: <Name>
### Step 1: <Title> - `interactive`
## Phase 2: <Name>
### Step 2: <Title> - `dispatch`
## Phase 3: <Name>
### Step 3: <Title> - `synthesis`
## Artifact Chain Summary
[Show the durable chain]
## Resume Awareness
[Artifact order, relay-state precedence, child adapter state]
## Circuit Breaker
[When to escalate]
Validator SKILL.md Starter
Use this section order instead of the artifact-centric starter when the method's primary job is symbolic execution or mechanical validation of another method:
---
name: your-method-slug
description: >
Validator method for mechanically tracing [target] against a fixed checklist.
Use when [positive trigger]. Do not use for delivery workflows or runtime execution.
---
# Your Validator Method
Short paragraph explaining the validator's core model and what a passing trace means.
## Core Model
## When to Use
## Inputs
## Output Location
## Citation Discipline
## Source-of-Truth Rule
## Fixed Checklist
## Workflow
### Special Step Types
## Targeted Closure Pass
## Failure Logging
## Output Schema
## Finish Condition
## Practical Notes
Gate Selection Decision Table
| Gate type | Use when | Required contract | Bad smells |
|---|---|---|---|
outputs_present |
Artifact quality can be checked from the file plus explicit content checks | Exact output schema, concrete gate checks, fallback synthesis if a worker wrote only handoffs/handoff.md |
Gate says only "file exists" or "looks good" |
evidence-reopen |
A proof step can validate, adjust, or invalidate the plan | Bounded verdicts, explicit artifact to update, explicit user checkpoint for invalidation | Proof can fail but the method only says "revise and continue" |
verdict-consistency |
A terminal verdict is valid only if it matches named evidence boundaries | Verdict meanings, exact evidence threshold, exact failing boundary requirement | "Closed" or equivalent is allowed without naming the checked boundary |
verdict-reopen |
A review step decides between continue and upstream revision | Diagnose-only contract, ready threshold, named reopen targets, user prompt for target plus governing issue | Review both edits code and judges it, or REVISE has no named target |
Quality Gate Checklist
Artifact Chain Integrity
- Name one canonical artifact per topology step or one explicit promoted output
- Distinguish worker handoffs from canonical method artifacts
- Name the exact output path and schema for every dispatch step
- Declare every external input and the first step that reads it
- Normalize parallel fanout before downstream synthesis depends on one contract
Gate Semantics
- Give every non-trivial step a gate stronger than file existence
- Bound verdict vocabulary and next-action routing
- Preserve the same gate semantics in
SKILL.mdandmethod.yaml - Record the governing issue whenever a verdict triggers reopen
Handoff Contract Compliance
- Use the canonical header schema and exact relay headings
- Tell the worker where the primary artifact lives and where the handoff lives
- Mark diagnose-only review steps explicitly
- Do not promote a raw handoff into a semantic artifact without synthesis
Resume Safety
- Check step-local relay state first and promoted artifacts second
- Treat parallel completeness as "all worker artifacts exist and satisfy the gate"
- Inspect child state like
batch.jsonbefore restartingmanage-codex - Resume from the chosen reopen target, not blindly from the verdict step
Dispatch Compatibility
- Use only real CLI flags, template behavior, and adapter behavior
- Keep autonomous skill budgets at 3 total skills unless a justified exception is documented
- Never append interactive skills to autonomous dispatches
- Make adapter seams concrete enough to execute by hand
Prose/YAML Consistency
- Align phase order, step count, consumes, produces, parallelism, gates, and adapters
- Keep runtime semantics in
SKILL.md - Author both files, then cross-validate them field by field
- Surface unsupported capabilities explicitly instead of implying hidden runtime behavior
- Verify total SKILL.md line count is proportional to method complexity. Comparable methods in the corpus: flow-audit-and-repair (593), research-to-implementation (646), spec-hardening (628), decision-pressure-loop (600). A method with similar topology should not exceed ~750 lines without justification. If it does, run the conciseness rules before shipping.
Authoring Checklist
- Define the method family and trigger surface.
- Lock the topology and step granularity.
- Inventory the artifact chain and every external input.
- Draft
method.yamlwith the live topology schema. - Draft
SKILL.mdfrontmatter and shared sections. - Write every step contract with the right action pattern.
- Add gates, verdicts, and reopen choreography.
- Add worker-role and adapter contracts.
- Add resume and circuit-breaker behavior.
- Cross-validate
SKILL.mdandmethod.yaml. 10b. Apply conciseness rules:- Setup must not re-list inputs that Step 1 captures — forward-reference only
- The canonical header schema should be shown compressed (required section names + relay heading rule), not as a full markdown template
- Show the dispatch recipe (compose-prompt + codex exec) in full exactly once; subsequent steps reference it
- Tighten adapter seam contracts to required fields, not heredoc templates — keep child-root layout, required CHARTER sections, readback order, and escalation rule; cut the shell heredoc
- Remove standalone
Verify: test -flines — the gate owns existence checks - Principles should not restate the intro or the dual-mode description in abstract form
- Body negative scope can reference frontmatter instead of repeating the full list
- Run the quality gate and recommend
method:dry-run.
Quality-Gate Crosswalk
| Quality category | Author task | Done when |
|---|---|---|
| Artifact Chain Integrity | Name every artifact, path, promotion rule, and external input | No consumer has to guess where input comes from |
| Gate Semantics | Write bounded gates plus outcome routing | Every negative outcome has a concrete next action |
| Handoff Contract Compliance | Freeze the header schema and relay headings | compose-prompt.sh cannot contaminate the prompt |
| Resume Safety | Define relay-first resume and reopen-target resume | A fresh session knows where to restart |
| Dispatch Compatibility | Check every command, skill budget, template, and adapter seam | A reviewer can execute the prose mechanically |
| Prose/YAML Consistency | Cross-check both files field by field | No topology drift remains |
Anti-Pattern Catalog
| ID | Smell |
|---|---|
AP-01 |
Open Artifact Chain - a step declares an output that no worker or synthesis step actually produces |
AP-02 |
Copy-The-Handoff - a generic handoff is copied verbatim into a semantic artifact |
AP-03 |
Template Misbinding - a step uses review, ship-review, converge, or implement for the wrong job |
AP-04 |
Placeholder Leakage - unresolved placeholders reach the worker prompt |
AP-05 |
Interactive Skill In Autonomous Dispatch - an AskUserQuestion-style skill is appended to codex exec --full-auto |
AP-06 |
Relay Layout Drift - parent, child, and adapter layouts assume different ownership boundaries |
AP-07 |
Resume By Final Artifacts Only - resume logic ignores step-local relay state such as batch.json |
AP-08 |
Review Overwrites Implementation Evidence - the only implementation story lives in a path reused by review |
AP-09 |
Ambiguous Final Synthesis - the method says "copy the final handoff" without explicit source artifacts and synthesis rules |
AP-10 |
Weak Gates - a gate checks only existence or generic completion |
AP-11 |
No Reopen Rule - disconfirming evidence appears but the method only says "revise and continue" |
AP-12 |
Guide Instead Of Contract - downstream work gets a guide that drops invariants, tests, or rollback triggers |
AP-13 |
Multiple Authoritative Packets - old and new packets coexist without a supersession rule |
AP-14 |
Faux Runtime Claims - the method denies being a runtime engine while depending on hidden runtime behavior |
AP-15 |
Prose/YAML Drift - SKILL.md and method.yaml disagree about topology or branching |
AP-16 |
Boilerplate Swamps Signal - shell ceremony buries the only step-specific rules that matter |
AP-17 |
Hidden External Input - a required source document, script, template, or method root is never declared |
AP-18 |
Faux Validator - a validator names checks but never defines symbolic execution, citations, or a fixed checklist |
AP-19 |
Review Step Mutates Source - a verdict step also changes code or rewrites the artifact under review |
AP-20 |
Reopen Without Governing Issue - the method says "reopen" but never records what issue caused it |
AP-21 |
Setup Duplicates Intake - the Setup section lists runtime inputs that Step 1's interactive intake already captures. Keep runtime inputs in one place (the intake step). Setup should only contain RUN_ROOT creation and a forward reference to Step 1. |
AP-22 |
Repeated Dispatch Shell Blocks - near-identical compose-prompt.sh | codex exec --full-auto blocks appear in every dispatch step. Show the full recipe once (first dispatch step), then reference it. Per-step blocks should only name the header path, skills, and template if non-default. |
AP-23 |
Duplicate Readback Orders - the same readback order appears in both the adapter contract and a later summary. Keep it in one location (the adapter contract section). |
AP-24 |
Standalone Verify Lines - a Verify: test -f ... line that duplicates the gate check immediately below it. Every existence check should live in the gate, not also as a standalone line. |
AP-25 |
Circuit Breaker Echoes Alternatives - a "Good alternatives" list at the end that repeats the redirects already named in the circuit breaker bullets. Remove the echo list. |
Phase 1: Intake
Step 1: Workflow Intake - interactive
Objective: Turn the user's workflow description into a durable authoring brief before any topology is invented.
User checkpoint: The user confirms the real workflow shape, what should trigger the generated method, and whether this is a delivery method or validator.
Ask the user:
- What should a fresh session be able to accomplish with this method end to end?
- What phases or checkpoints already exist in the workflow?
- Which steps require human judgment, and which are interactive, dispatch, or synthesis candidates?
- What artifacts must survive each phase?
- What external inputs, adapters, scripts, templates, or child workflows does it depend on?
- Is this an artifact-centric method or a validator? If unsure, what is being validated and does the workflow execute product work?
- What should trigger the skill, and what is explicitly out of scope?
- Where should the generated method be written?
Write ${RUN_ROOT}/artifacts/workflow-brief.md:
# Workflow Brief
## Method Goal
## Trigger Surface
## Negative Scope
## Method Family
## Candidate Phase List
## Judgment Checkpoints
## Artifact Chain
## External Inputs and Adapters
## Output Target
## Open Questions
Gate: workflow-brief.md exists with non-empty Method Goal, Trigger Surface,
Negative Scope, Method Family, and Output Target sections.
Failure mode: The compiler authors a method for the wrong problem, wrong family, or wrong trigger surface.
Phase 2: Analysis
Step 2: Pattern Mapping - dispatch
Objective: Normalize the brief into the live method patterns and identify the exact contract the generated files must encode.
Write a prompt header to ${RUN_ROOT}/prompt-header-analysis.md:
# Step 2: Pattern Mapping
## Mission
Read the workflow brief and map it to the live method patterns. Determine whether
this is an artifact-centric method or a validator method. Output a structured
analysis that will feed directly into file generation.
## Inputs
- `${RUN_ROOT}/artifacts/workflow-brief.md`
- The Reference Pack embedded in this skill's SKILL.md (starters, gate table,
quality gate, anti-patterns)
## Output
- **Path:** `${RUN_ROOT}/artifacts/method-analysis.md`
- **Schema:**
## Recommended Method Family
## Phase Topology
## Step Inventory
## Action Map
## Artifact Chain and Promotion Rules
## Gate Plan
## External Inputs and Notes
## Resume and Reopen Plan
## Adapter and Worker Contracts
## Inline Reference Requirements
## Success Criteria
- Method family is explicitly chosen with reasoning
- Every step has an action type, artifact(s), and gate plan
- Circuit breaker triggered if the workflow does not fit
## Handoff Instructions
### Files Changed
### Tests Run
### Completion Claim
Assemble and dispatch:
./scripts/relay/compose-prompt.sh \
--header "${RUN_ROOT}/prompt-header-analysis.md" \
--template implement \
--root "${RUN_ROOT}" \
--out "${RUN_ROOT}/prompt-analysis.md"
cat "${RUN_ROOT}/prompt-analysis.md" | \
codex exec --full-auto \
-o "${RUN_ROOT}/last-messages/last-message-analysis.txt" -
Verify: test -f ${RUN_ROOT}/artifacts/method-analysis.md
Analysis rules (encode in the prompt header):
- Choose the artifact-centric family unless the primary job is symbolic execution or validation of another method
- Do not invent a third family
- Keep phases serial and use worker fanout only inside a single step
- Mark review steps as diagnose-only when they should not mutate source
- If
manage-codexappears, record the full adapter-seam contract now - If the workflow is too small, too graph-like, or too runtime-dependent for the live method contract, trip the circuit breaker instead of forcing it
Gate: method-analysis.md exists with explicit Phase Topology, Step
Inventory, Action Map, Artifact Chain and Promotion Rules, Gate Plan, and
Resume and Reopen Plan.
Failure mode: The generated files look plausible but encode the wrong family, wrong topology, or hidden runtime assumptions.
Phase 3: Authoring
Step 3: Compile Method Files - dispatch
Objective: Generate draft method.yaml and SKILL.md from the analysis,
cross-validate them, and write all three to the staging area.
Write a prompt header to ${RUN_ROOT}/prompt-header-authoring.md that includes:
- The full workflow brief digest
- The full method analysis digest
- The Reference Pack (canonical starters, gate table, quality gate, anti-patterns)
- Instructions to write:
${STAGING}/method.yaml— from the canonical YAML starter${STAGING}/SKILL.md— from the appropriate family starter${RUN_ROOT}/artifacts/cross-validation.md— field-by-field comparison
Assemble and dispatch:
./scripts/relay/compose-prompt.sh \
--header "${RUN_ROOT}/prompt-header-authoring.md" \
--template implement \
--root "${RUN_ROOT}" \
--out "${RUN_ROOT}/prompt-authoring.md"
cat "${RUN_ROOT}/prompt-authoring.md" | \
codex exec --full-auto \
-o "${RUN_ROOT}/last-messages/last-message-authoring.txt" -
Verify: test -f ${STAGING}/method.yaml && test -f ${STAGING}/SKILL.md && test -f ${RUN_ROOT}/artifacts/cross-validation.md
Cross-validation rules (encode in the prompt header):
- Compare phase ids, titles, and order
- Compare step ids, titles, actions, consumes, produces, adapters, and retries
- Compare parallel fanout shape and worker roles
- Compare gate types, verdict vocabularies, and reopen outcomes
- Compare the declared external inputs and adapter seams
- Fix every drift before declaring done
- The generated
namemust usemethod:prefix (e.g.,method:foo-bar)
Gate: method.yaml, SKILL.md, and cross-validation.md exist in staging,
the files agree on topology and branching, and the generated SKILL.md includes
the embedded reference pack.
Failure mode: The method looks polished but fails because SKILL.md and
method.yaml describe different workflows.
Phase 4: Validation
Step 4: Quality Gate - dispatch
Objective: Codex review worker walks the six quality categories against the draft files. This step is assessment only — the worker does NOT modify the drafts.
Write a prompt header to ${RUN_ROOT}/prompt-header-validation.md that includes:
- Digests of
${STAGING}/method.yamland${STAGING}/SKILL.md - Full
cross-validation.mdcontent - The Quality Gate Checklist and Anti-Pattern Catalog from this skill
- Instructions to write
${RUN_ROOT}/artifacts/validation-report.md
Assemble and dispatch:
./scripts/relay/compose-prompt.sh \
--header "${RUN_ROOT}/prompt-header-validation.md" \
--template ship-review \
--root "${RUN_ROOT}" \
--out "${RUN_ROOT}/prompt-validation.md"
cat "${RUN_ROOT}/prompt-validation.md" | \
codex exec --full-auto \
-o "${RUN_ROOT}/last-messages/last-message-validation.txt" -
Verify: test -f ${RUN_ROOT}/artifacts/validation-report.md
Validation report schema:
# Validation Report
## Artifact Chain Integrity
## Gate Semantics
## Handoff Contract Compliance
## Resume Safety
## Dispatch Compatibility
## Prose/YAML Consistency
## Anti-Patterns Found
## Verdict: READY / REVISE
## Recommended Next Step
Validation rules (encode in the prompt header):
- Walk every quality category explicitly; do not stop at the first defect
- Name anti-patterns by ID when they appear
- If the generated method claims validator behavior, confirm the validator contract actually includes inputs, citations, fixed checklist, workflow, failure logging, and finish condition
- If the generated method claims adapter support, verify the seam is concrete
- This step is assessment only — do NOT modify the draft files
- Check for AP-21 through AP-25 (conciseness anti-patterns). Pay special attention to:
- AP-22 (Repeated Dispatch Shell Blocks) — count the number of full compose+exec blocks. More than one is a smell.
- AP-21 (Setup Duplicates Intake) — check if Setup lists runtime inputs that the intake step already collects.
Gate: validation-report.md exists with all six quality categories walked
and a binary READY/REVISE verdict.
Failure mode: A surface-level review passes a method with hidden gaps.
Phase 5: Refinement
Step 5: Claude Code Refinement - synthesis
Objective: The orchestrator reads all upstream artifacts and the Codex
validation findings, refines the draft files for Claude Code optimization, and
installs the final method to TARGET_METHOD_ROOT.
Read these inputs:
${STAGING}/method.yamland${STAGING}/SKILL.md(Codex drafts)${RUN_ROOT}/artifacts/cross-validation.md${RUN_ROOT}/artifacts/validation-report.md
Refinement checklist:
- Trigger metadata — Is the
descriptionfield optimized for Claude Code's skill discovery? Does it encode trigger phrases, phase count, and negative scope? Would a user typing a natural request actually match this skill? - Dispatch patterns — Do all
dispatchsteps use the correctcompose-prompt.shflags andcodex exec --full-autopatterns? Are relay headings present in every header? - Session ergonomics — Will this method feel natural when invoked via
/method:<name>? Are interactive steps conversational? Are synthesis steps clear about what the orchestrator writes? - Address REVISE findings — If the validation report says REVISE, fix every named issue in the drafts before installing.
- Cross-validate again — After any refinement edits, re-verify that
method.yamlandSKILL.mdstill agree on topology. 5b. Conciseness pass — Before installing, verify:- No setup/intake duplication (AP-21)
- Dispatch recipe shown in full once only (AP-22)
- No duplicate readback orders (AP-23)
- No standalone verify lines (AP-24)
- No circuit breaker echo lists (AP-25)
- Canonical header schema is compressed, not templated
- SKILL.md line count is proportional to corpus norms
- Install — Copy refined files to
${TARGET_METHOD_ROOT}/method.yamland${TARGET_METHOD_ROOT}/SKILL.md.
Gate with reopen: Read the validation verdict plus refinement results.
READYafter refinement -> install toTARGET_METHOD_ROOTand recommend runningmethod:dry-runagainst one concrete featureREVISEwith issues the orchestrator cannot resolve -> present findings to the user and ask:- Which artifact should reopen:
workflow-brief.md,method-analysis.md, or the authored files? - What specific issue should govern the reopen?
- Which artifact should reopen:
Append a ## Reopen Decision section to validation-report.md, update the
chosen upstream artifact if needed, and resume from the selected step.
Failure mode: The compiler ships a method that looks corpus-shaped but still contains hidden gaps, weak gates, or unusable adapter seams.
Artifact Chain Summary
workflow-brief.md [Step 1, interactive]
-> method-analysis.md [Step 2, Codex dispatch]
-> draft-method.yaml + draft-SKILL.md [Step 3, Codex dispatch, staging]
-> cross-validation.md [Step 3, Codex dispatch]
-> validation-report.md [Step 4, Codex dispatch]
-> method.yaml + SKILL.md [Step 5, Claude refinement, installed]
Draft files live in ${STAGING}/. Final deliverables live in ${TARGET_METHOD_ROOT}/.
Compiler artifacts (cross-validation.md, validation-report.md) stay under
${RUN_ROOT}/artifacts/ as the authoring audit trail.
Resume Awareness
If work already exists, resume in this order:
- Check
${RUN_ROOT}/artifacts/workflow-brief.md - Check
${RUN_ROOT}/artifacts/method-analysis.md - Check
${STAGING}/method.yaml,${STAGING}/SKILL.md, and${RUN_ROOT}/artifacts/cross-validation.md - Check
${RUN_ROOT}/artifacts/validation-report.md - Check
${TARGET_METHOD_ROOT}/method.yamland${TARGET_METHOD_ROOT}/SKILL.md
If validation-report.md exists with a REVISE verdict, read its
## Reopen Decision section and resume from the chosen step instead of blindly
rerunning validation.
If the final files exist in TARGET_METHOD_ROOT but not in staging, the
refinement step already completed — do not re-run.
This is best-effort. The durable state is the artifact set on disk, not the chat thread.
Circuit Breaker
Stop and recommend a different path when:
- the workflow is a simple prompt or a tiny conventional skill with no real multi-phase contract
- the request is to edit an existing method instead of authoring a new one
- the workflow needs arbitrary graph execution, hidden runtime ledgers, or pipeline orchestration that the live method schema does not model
- the workflow is really a runtime engine, installer, or adapter implementation task rather than a method authoring task
- the method family cannot honestly be expressed as artifact-centric or validator
Good alternatives:
- Hand-author a small non-method skill
- Use
skill-creatorfor ordinary skill work that does not need method topology - Use
method:dry-runto validate an already-authored method - Use
pipelineor a design/architecture skill if the real need is orchestration
Didn't find tool you were looking for?