Skill Writer

Use this as the single canonical workflow for skill creation and improvement. Primary success condition: maximize high-value input coverage before authoring so the resulting skill has minimal blind spots.

Load only the path(s) required for the task:

Task Read

Set skill class and required dimensions references/mode-selection.md

Apply writing constraints for depth vs concision references/design-principles.md

Select structure pattern for this skill references/skill-patterns.md

Select workflow orchestration pattern for process-heavy skills references/workflow-patterns.md

Select output format pattern for deterministic quality references/output-patterns.md

Choose workflow path and required outputs references/mode-selection.md

Load representative synthesis examples by skill type references/examples/*.md

Synthesize external/local sources with depth gates references/synthesis-path.md

Author or update SKILL.md and supporting files references/authoring-path.md

Optimize skill description and trigger precision references/description-optimization.md

Iterate using positive/negative/fix examples references/iteration-path.md

Evaluate behavior and compare baseline vs with-skill (opt-in quantitative) references/evaluation-path.md

Register and validate skill changes references/registration-validation.md

Step 1: Resolve target and path

• Resolve target skill path and intended operation (create , update , synthesize , iterate ).

• Read references/mode-selection.md and select the required path(s).

• Classify the skill (workflow-process , integration-documentation , security-review , skill-authoring , generic ).

• Ask one direct question if class or depth requirements are ambiguous; otherwise state explicit assumptions.

Step 2: Run synthesis when needed

Read references/synthesis-path.md .

• Collect and score relevant sources with provenance.

• Apply trust and safety rules when ingesting external content.

• Produce source-backed decisions and coverage/gap status.

• Load one or more profiles from references/examples/*.md when the skill is hybrid.

• Enforce baseline source pack for skill-authoring workflows.

• Enforce depth gates before moving to authoring.

Step 3: Run iteration first when improving from outcomes/examples

Read references/iteration-path.md first when selected path includes iteration (for example operation iterate ).

• Capture and anonymize examples with provenance.

• Re-evaluate skill behavior against working and holdout slices.

• Propose improvements from positive/negative/fix evidence.

• Carry concrete behavior deltas into authoring.

Skip this step when selected path does not include iteration .

Step 4: Author or update skill artifacts

Read references/authoring-path.md .

• Write or update SKILL.md in imperative voice with trigger-rich description.

• Create focused reference files and scripts only when justified.

• Follow references/skill-patterns.md , references/workflow-patterns.md , and references/output-patterns.md for structure and output determinism.

• For authoring/generator skills, include transformed examples in references:

• happy-path

• secure/robust variant

• anti-pattern + corrected version

Step 5: Optimize description quality

Read references/description-optimization.md .

• Validate should-trigger and should-not-trigger query sets.

• Reduce false positives and false negatives with targeted description edits.

• Keep trigger language generic across Codex and Claude.

Step 6: Evaluate outcomes

Read references/evaluation-path.md .

• Run a lightweight qualitative check by default (recommended).

• For integration/documentation and skill-authoring skills, include the concise depth rubric from references/evaluation-path.md .

• Run deeper eval playbook and quantitative baseline-vs-with-skill only when requested or risk warrants it.

• Record outcomes and unresolved risks.

Step 7: Register and validate

Read references/registration-validation.md .

• Apply repository registration steps.

• Run quick validation with strict depth gates.

• Reject shallow outputs that fail depth gates or required artifact checks.

Output format

Return:

• Summary

• Changes Made

• Validation Results

• Open Gaps