Spec Skill Moat

Step 3 -- Generate SKILL.md Body

Write each section in order:

1. Title -- H1 matching the skill name in title case.
2. Guiding Principle -- A blockquote with an original or attributed aphorism relevant to the skill's purpose.
3. Introduction -- 2-4 sentences explaining what the skill does, when to use it, and what it produces.
4. Procedure -- Numbered steps (H3 per step) with:
   • Clear imperative instructions ("Read the file", "Validate each entry").
   • Tool references in backtick brackets: [Read], [Glob], [Bash].
   • Decision points as bullet sub-lists with conditions and actions.
5. Quality Criteria -- Numbered list, minimum 4 testable criteria. Each criterion must be verifiable by reading the output alone.
6. Anti-Patterns -- Numbered list, minimum 3 entries. Each anti-pattern includes: the mistake, why it is wrong, and what to do instead.
7. Edge Cases -- Numbered list, minimum 2 entries. Each edge case includes: the scenario, expected behavior, and handling instructions.

Step 4 -- Apply Progressive Disclosure

• Count lines in the generated SKILL.md body (excluding frontmatter).
• If >500 lines: extract detailed tables, extended examples, or deep reference material into references/ files. Replace with a cross-reference line: > See references/{filename} for details.
• If >300 lines: add a table of contents after the introduction.
• Reference files themselves have no line limit but should use H2 sections for scannability.

Step 5 -- Generate MOAT Asset Files

Based on the design's MOAT strategy:

• references/: Write reference files for lookup tables, specification details, rubrics, or catalogs that support the skill. Each file gets H1 title, purpose statement, and structured content.
• examples/: Write example files showing sample inputs and expected outputs. Use fenced code blocks for structured data.
• prompts/: Write prompt files containing metaprompts or prompt templates the skill uses internally. Each prompt gets a name, purpose, and the prompt text in a fenced block.

Step 6 -- Score Against MOAT 6 Dimensions

Evaluate the complete spec package against each dimension (1-10 scale):

See references/moat-structure-spec.md for the full rubric with scoring anchors.

Step 7 -- Revise Below-Threshold Dimensions

• If any dimension scores <7, identify the specific deficiency.
• Revise the affected section(s) to address the gap.
• Re-score. Repeat until all dimensions are >=7.
• Record final scores in the output summary.

Step 8 -- Verify Constraints and Output

• Confirm SKILL.md body is <=500 lines.
• Confirm frontmatter has all required fields.
• Confirm at least 4 quality criteria, 3 anti-patterns, 2 edge cases.
• Output the complete spec package: SKILL.md text + all MOAT asset file contents.
• Include a summary table: file name, line count, purpose.

Quality Criteria

• Every SKILL.md contains all 7 required body sections (title, guiding principle, introduction, procedure, quality criteria, anti-patterns, edge cases).
• Procedure steps reference specific tools using [ToolName] notation.
• All 6 MOAT dimensions score >=7/10 with scores reported in output.
• SKILL.md body does not exceed 500 lines (frontmatter excluded).
• Trigger phrases in the description cover at least 3 natural language variations.
• Cross-references to MOAT asset files use correct relative paths.

Assumptions & Limits

• Requires a completed skill design document as input. Cannot generate a SKILL.md from a brief concept alone -- that is design-skill's responsibility.
• The 500-line limit applies to the SKILL.md body only. Frontmatter and MOAT asset files have no line limit.
• MOAT dimension scoring is self-assessed during generation. The scores represent the author's judgment, not an external audit. Use audit-content-quality for independent scoring.
• Progressive disclosure (Step 4) moves content to reference files, which may create cross-reference dependencies. If references are deleted later, the SKILL.md will have broken links.
• Cannot guarantee that generated trigger phrases will actually activate the skill in all runtime contexts -- trigger matching depends on the model's interpretation.

Good vs Bad

Bad spec output:

# My Skill
Do the validation thing. Check stuff. Report results.

Missing: no frontmatter, no guiding principle, no structured procedure, no quality criteria, no anti-patterns, no edge cases, no MOAT assets.

Good spec output:

---