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 model: sonnet

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 — content that explains rather than directs belongs in sub-files, not the body
• Sub-files use three spec-defined optional directories: scripts/ (executable code), references/ (on-demand docs), assets/ (templates, data files, lookup tables); additional files (e.g. META.md) are valid at the skill root. File references must be one level deep — no nested chains. Wire each sub-file with an explicit instruction in the step that needs it (e.g. "See references/lookup.md for error codes") — without a wiring instruction the file is never loaded
• 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 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 with the /grill-me skill 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. Using the agreed name, category, purpose, and use cases from the grill, 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, plus optional sub-files if the skill requires them:

• 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
• scripts/, references/, or assets/ — created only when needed; each file wired with an explicit step instruction

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
• If sub-files exist: placed in correct directory type (scripts/, references/, or assets/) and wired with an explicit instruction in the relevant step
• For placeholder conversions: existing files read, all stale content removed, old directory deleted if renamed
• write-eval invoked — eval file exists at correct path, covers trigger cases (explicit, implicit, negative) and at least one output case
• User prompted for HITL behavioral test