holocron/.agents/skills/write-skill/SKILL.md

name: write-skill description: Use when the user wants to author a new skill file or convert an existing placeholder to the canonical authoring standard. Triggers: "write a new skill for X", "create a SKILL.md that does Y", "build a skill to handle Z". Do NOT use when fixing or updating an existing well-formed skill (use upgrade-skill), running existing evals (use write-eval), refactoring application code, or writing documentation for non-skill artifacts. metadata: category: factory

Required inputs

• Skill name — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous
• Category — from the category table in CATEGORIES.md; ask if unclear
• Purpose + use cases — what the skill does and what tasks it handles; source for the trigger description
• For placeholder conversions: existing SKILL.md path — read before writing

Negative trigger cases are NOT a required input. The agent proposes them based on the skill's purpose and adjacent skills found during the overlap scan. The user confirms or refines before trigger testing begins.

Constraints

• Write two files for every skill: SKILL.md at .agents/skills/<name>/SKILL.md and META.md alongside it
• Frontmatter has three fields only: name, description, and metadata.category — add allowed-tools only when the skill has a narrow, well-defined tool surface
• Keep the body under 500 lines — move anything longer into separate files in the skill directory
• Use XML tags only when the body has three or more logical sections and exceeds 500 tokens — default to plain prose
• Test the trigger description against all three cases — explicit, implicit, negative — before writing any body content. Hard gate: a failed case means revise and retest, not proceed
• Check for overlapping skills in .agents/skills/ before writing anything — if overlap is found, surface it and wait for direction
• For placeholder conversions: read the existing SKILL.md first and remove all stale or outdated content

Process

1. Scan for overlap. Check .agents/skills/ for skills with similar purpose or trigger phrases. If overlap is found, surface it and wait for explicit direction — do not continue.

2. Grill. Run a focused grill to reach shared understanding of: skill name, category, purpose, and use cases. One question at a time, with a recommendation for each.

3. Write and test the trigger description. Draft description:. Propose negative trigger cases based on the skill's purpose and adjacent skills — get explicit user confirmation before running tests. Test all three cases and show per-case PASS/FAIL. A failed case means revise and retest — do not proceed.

4. Walk through each section. For each section in SKILL-TEMPLATE.md: propose content, state where it comes from, present alternatives if they exist. Wait for explicit human confirmation before moving to the next section.

5. Copy both templates. Copy SKILL-TEMPLATE.md to .agents/skills/<name>/SKILL.md. Copy META-TEMPLATE.md to .agents/skills/<name>/META.md. Do not modify content yet — copy first, fill second.

6. Fill both files. Fill in the copied SKILL.md with confirmed section content. Fill in the copied META.md with version, updated date, when, source (if applicable), and references (if applicable).

7. Invoke write-eval. Do not mark the skill complete without an eval file.

8. Prompt for HITL. Ask the user to open a fresh session, trigger the skill, and confirm output before committing.

Output format

Two files produced for every skill:

• SKILL.md — copy-filled from SKILL-TEMPLATE.md at .agents/skills/<name>/SKILL.md
• META.md — copy-filled from META-TEMPLATE.md at .agents/skills/<name>/META.md

For placeholder conversions, SKILL.md replaces the existing file entirely — no partial edits.

Failure handling

• Template file missing — stop, report the path searched, do not write from memory
• Existing SKILL.md not found for a placeholder conversion — stop, report the path searched
• write-eval fails or is unavailable — flag, do not mark the skill complete

Self-check

• Overlap check completed before any content was written
• Trigger description tested against all three cases — all passed before body content was written
• Negative trigger cases confirmed by user before testing
• Each section confirmed explicitly by user before SKILL.md was written
• SKILL.md copy-filled from SKILL-TEMPLATE.md at correct path
• META.md copy-filled from META-TEMPLATE.md at correct path
• Frontmatter contains only name, description, and metadata.category (plus allowed-tools if applicable)
• Body is under 500 lines
• For placeholder conversions: existing files read, all stale content removed, old directory deleted if renamed
• write-eval invoked — eval file exists at correct path
• User prompted for HITL behavioral test