Spec Skill Builder

Use this skill to design Codex Skills as reusable capability modules. Always produce a design artifact first. Create executable skill files only when the user explicitly asks to implement, generate, materialize, or install the skill.

When executable files are requested, use the system skill-creator skill for initialization, editing, metadata, validation, and iteration. This skill defines the design and handoff contract; skill-creator performs the implementation workflow.

Required Output

Always deliver a skill design artifact unless the user explicitly requests another format.

Include:

1. Recommended skill type
2. Why this type fits
3. Skill spec
4. Proposed artifact structure
5. Required and optional resources
6. Script deposition opportunities
7. Validation checklist
8. Iteration strategy

Use references/design-artifact-template.md as the default output structure for design-only requests.

Scenario Intake

Extract only the context needed to design the skill:

• User goal
• Example requests that should trigger the skill
• Expected outputs
• Existing files, scripts, workflows, or scaffolds
• Reuse frequency
• Failure risk
• Determinism needs
• Whether the user asked for design only or executable implementation

Ask at most one concise question if a missing answer would materially change the skill type. Otherwise make a conservative assumption and state it.

Skill Type Selection

Choose one primary type.

Type A: Prompt-Only Skill

Use for reasoning, writing, review, planning, diagnosis, decision protocols, and domain guidance.

Default artifact:

SKILL.md

Do not add scripts for subjective or one-off reasoning.

Type B: Prompt + Scaffold Skill

Use when the skill benefits from reusable templates, references, assets, helper scripts, or a repeatable folder structure.

Possible artifacts:

SKILL.md
scripts/
references/
assets/
agents/openai.yaml

Only include folders that are justified by the workflow.

Type C: Scaffold-to-Skill Reverse Engineering

Use when the user already has a project, script collection, folder scaffold, toolchain, or repeated manual workflow.

Read references/reverse-engineering-skill.md before designing this type.

Extract the reusable behavior, remove accidental project-specific details, and identify stable entry commands, inputs, outputs, assumptions, and validation steps.

Type D: Road-Building Script Skill

Use when the workflow should leave reusable scripts or automation behind after solving tasks.

Read references/road-building-pattern.md before designing this type.

Read references/road-building-business-script-contract.md when the designed skill will be called to produce reusable business scripts for scheduling systems.

Read references/road-building-excel-example.md when an example of output-level Road-Building design would help, especially for Excel/CSV, SQL, report generation, or scheduler-ready business scripts.

The SKILL.md should be the router and operating manual. Scripts should become the paved paths for repeated, fragile, file-heavy, data-heavy, command-heavy, or validation-heavy work. The paved paths must be output-level artifacts in task output directories, project folders, or user-selected locations.

Do not define road-building as adding generated scripts back into the skill's own scripts/ directory. Updating the skill itself is skill maintenance, not road-building.

Use Type D only when the scenario meets the threshold in references/skill-type-selection.md.

Spec Template

For every skill design, define:

Skill name:
Purpose:
Recommended type:
Trigger scenarios:
Non-goals:
Inputs:
Outputs:
Required tools:
Workflow:
Reusable resources:
Script deposition plan:
Road deposition scope:
Validation:
Failure handling:
Iteration strategy:
Implementation handoff:

Resource Decisions

Use references/ for detailed domain knowledge, schemas, examples, variant guidance, or long rules that should load only when needed.

Use scripts/ for deterministic, repeated, fragile, file-heavy, data-heavy, parsing, conversion, formatting, validation, or batch operations.

Use assets/ for templates, boilerplate, images, fonts, or files copied into outputs.

Do not create resources merely because the skill format supports them.

For detailed type selection rules, read references/skill-type-selection.md.

Script Deposition

Recommend or create scripts when:

• The same code would likely be rewritten.
• The task is easy to get subtly wrong.
• The work touches many files.
• The task depends on exact parsing, conversion, formatting, or validation.
• The output must be deterministic.
• The workflow can be parameterized.

Do not create scripts for one-off judgment or subjective writing.

If a road-building workflow uses a script index, keep that index in the task output directory, project folder, or user-selected location. The helper scripts/update_script_index.py can maintain such an output-level index.

Road-building business scripts must be delivered with matching usage documentation. Do not design a road-building skill that emits only a script without instructions for rerun, scheduling, parameters, outputs, and validation.

Implementation Handoff

If the user asks only for design, stop after the design artifact.

If the user explicitly asks for executable implementation:

1. Announce that implementation will use the system skill-creator workflow.
2. Follow skill-creator instructions to initialize or update the skill.
3. Create only justified resources.
4. Test scripts that are created or changed.
5. Run the skill validation script.
6. Report created files and validation results.

Validation Checklist

A complete design artifact must answer:

• Does the skill have a clear purpose and trigger surface?
• Is the recommended type justified?
• Are non-goals and boundaries explicit?
• Are inputs and outputs concrete?
• Are resources justified rather than decorative?
• Are script deposition opportunities identified?
• Is validation executable or at least observable?
• Is implementation clearly marked as optional unless requested?

Executable skill artifacts must also satisfy skill-creator validation.