Creating Skills in the Hoen Library¶

Source of truth — read this first¶

Author directly in this repository under library/skills/. Each skill folder is self-contained and is the canonical source of truth.

Directory convention (Authoring)¶

Canonical source for every skill lives at:

library/skills/<skill-name>/SKILL.md

Examples in this repo:

library/skills/
  git-hygiene/SKILL.md
  unit-test/SKILL.md
  create-hoen-skill/SKILL.md

When creating a new skill:

mkdir -p library/skills/<skill-name>
# Write SKILL.md into that directory — done.

Folder name and the name: frontmatter field must match exactly. No README.md inside skill folders — supplementary docs go in sibling files (see "Keep it under 500 lines" below).

SKILL.md Structure¶

Every skill is a single SKILL.md file (case-sensitive): YAML frontmatter, then title, then body.

---
name: kebab-case-name
description: "What it does. When to use it. Include trigger phrases."

phase: [implement]
hoen: [1-version-control]
maturity: experimental
metadata:
  user-invocable: false

provenance:
  original_creator:
    name: person-or-team
  library_added_by:
    name: wu-committer
    date_added: YYYY-MM-DD
  source:
    origin_project: engagement-name
    hoen_library_tag: vX.Y.Z-or-not_set
    source_commit: git-sha-or-not_set
  stewarding_team: wires-uncrossed
---

# Skill Title

> **When to use:** One line mirroring the frontmatter description.

## Instructions

Core guidance — what the agent needs to know. Use `###` subheadings for steps.

---

## References

Optional links to `references/` files.

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| What the user sees | Why | What to do |

See CONVENTIONS.md — Human scanability for frontmatter and body outline rules.

Frontmatter Rules¶

Field	Requirement
`name`	Required. Lowercase kebab-case, max 64 chars, must match folder name.
`description`	Required. Under 1024 chars. Must state what it does and when to use it. No XML angle brackets.
`phase`	Required. One or more of `diagnose`, `plan`, `implement`, `cross-cutting` (see CONVENTIONS.md).
`hoen`	Required. One or more HoEN-need codes from taxonomy/.
`maturity`	Required. One of `experimental`, `recommended`, `golden-path`.
`metadata`	Optional. Add `user-invocable`, `author`, `version` as needed.
`provenance`	Required. Must include `original_creator` (set to a person or team before merge — `not_set` is a temporary placeholder only) and `library_added_by`.

Writing Effective Skills¶

1. Assume competence¶

The agent is already knowledgeable. Only include information it wouldn't already have: project-specific conventions, domain rules, non-obvious decisions, exact commands.

Ask for each paragraph: "Does this justify its token cost?"

2. Be specific and actionable¶

# Bad
Validate the data before proceeding.

# Good
Run `python scripts/validate.py --input {filename}` before proceeding.
If validation fails, common issues: missing required fields, invalid
date formats (use YYYY-MM-DD).

3. Description is critical for discovery¶

The description determines whether the agent loads the skill. Structure it as:

[What it does] + [When to use it] + [Trigger phrases]

# Bad
description: Helps with testing.

# Good
description: >-
  Guidelines for writing unit tests in this project. Use when writing,
  reviewing, or generating unit tests. Emphasizes clarity, consolidation
  of related assertions, and avoiding duplication.

Write descriptions in third person (they appear in the system prompt).

4. Keep it under 500 lines¶

If a skill needs more detail, use progressive disclosure — link to reference files in the same skill folder:

my-skill/
├── SKILL.md            # Core instructions (under 500 lines)
├── reference.md        # Detailed docs (read on demand)
└── examples.md         # Usage examples (read on demand)

Keep references one level deep — link from SKILL.md directly to sibling files. Deeply nested references may not get read.

5. Include troubleshooting¶

Use the pattern:

**Error:** [What the user sees]
**Cause:** [Why it happens]
**Solution:** [How to fix it]

6. Match specificity to fragility¶

Freedom level	When to use	Example
High (text guidance)	Multiple valid approaches	Code review style
Medium (templates)	Preferred pattern, some variation OK	Report format
Low (exact scripts)	Fragile ops, consistency critical	DB migrations

Naming Conventions¶

Folder: kebab-case, no spaces, no capitals, no underscores
File: Exactly SKILL.md (not skill.md, SKILL.MD, etc.)
No README.md inside skill folders — all docs go in SKILL.md or reference files
Avoid vague names like helper, utils, tools

What NOT to Do¶

Anti-pattern	Instead
Spreading one skill's instructions across unrelated top-level folders	Keep skill instructions and support files under `library/skills/<name>/`
Writing huge one-file skills with no progressive disclosure	Keep `SKILL.md` concise and move detail to `references/`
Verbose explanations the agent already knows	Only project-specific or non-obvious info
Time-sensitive instructions ("before August 2025…")	Use "current" / "deprecated" sections
Inconsistent terminology within a skill	Pick one term and use it throughout
XML angle brackets in frontmatter	Forbidden for security reasons

Checklist¶

Before finalising a new skill, verify:

[ ] Folder is at library/skills/<kebab-case-name>/ (not .agents/skills/ or .claude/skills/)
[ ] File is named exactly SKILL.md
[ ] File starts with a frontmatter --- block containing name, description, phase, hoen, maturity, provenance
[ ] name matches folder name
[ ] Description includes what and when
[ ] provenance.original_creator is set to a person or team (not not_set)
[ ] library-maintenance/validation/validate-skill.mjs passes
[ ] Body is under 500 lines
[ ] Troubleshooting section exists
[ ] Frontmatter uses quoted description, inline phase: [...] / hoen: [...], blank lines between groups (no # Section comments)
[ ] Body uses ## Instructions, blockquote hook, and --- before References/Troubleshooting
[ ] Consistent terminology throughout
[ ] No README.md in the skill folder