holocron/plugins/kyberforge/skills/write-skill/SKILL.md at 41c4da31cf69b534f17439efbbd45dcbbb61b157 - holocron - Gitea: Git with a cup of tea

Defame1297/holocron

Files

Defame1297 2b649782a2 fix(kyberforge): resolve plugin-create path bug, validate.sh false positives, and write-skill YAML error

- plugin-create/SKILL.md: fix ${CLAUDE_PLUGIN_ROOT} path (create-plugin → plugin-create, 4 occurrences)
- plugin-create/SKILL.md: delegate reserved name validation to new references/reserved-names.md (complete list)
- plugin-create/SKILL.md: add displayName reminder in step 4, full-validation pointer in step 7
- plugin-create/references/reserved-names.md: complete reserved name list extracted from claude-code.md
- plugin-create/references/manifest-fields.md: quick-ref for both plugin.json manifests and marketplace entry
- plugin-create/META.md: update stale when: and references: fields to reflect post-migration paths
- plugin-create/assets/plugin-template/hooks.json: unify empty hooks schema to {} (was [])
- write-skill/SKILL.md: fix YAML frontmatter parse error — wrap description in >- block scalar
- validate.sh: strip backtick spans before ../  check to eliminate documentation false positives
- inventory.sh: same backtick-span fix, applied to both outer check and per-line reporting
- tests/test_scripts.sh: fix SCRIPTS_DIR path to skills/marketplace-architect/scripts/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-20 18:41:29 +00:00

6.8 KiB

Raw Blame History

name, description, metadata, model

name

description

metadata

model

write-skill

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.

category
factory

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 required fields: name, description, metadata.category — add allowed-tools only when the skill has a narrow, well-defined tool surface; add model: only when the skill's task complexity warrants a specific model tier (see SKILL-TEMPLATE.md for routing guidance)
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

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.
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.
Conflict check. Spawn a sub-agent: read docs/ai-constitution.md, docs/research/ai-coding-factory/ai-coding-factory-principles.md, and docs/notes/factory-integration-decisions.md, then check the agreed skill purpose and design against all three. Where a factory principle is superseded by an integration decision, the decision takes precedence — do not flag it as a conflict. Return a numbered list of genuine unresolved tensions, or confirm none found. An empty list is a valid result. Hard gate: resolve any findings before proceeding.
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.
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.
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.
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).
Invoke write-eval. Do not mark the skill complete without an eval file.
Run self-check. Work through every item in the Self-check section below. Do not proceed until all items pass.
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
Conflict check sub-agent ran against constitution and factory principles — findings resolved before any writing began
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 name, description, and metadata.category; optional allowed-tools and model: only where justified
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