| name | tooling-skill-authoring |
| description | Skill-authoring discipline for this repo. Local categories.yaml, hooks stamped from agentic-os via agentic-os-kai. Triggers - skill, SKILL.md, frontmatter, categories.yaml, .agents/skills, skill authoring, skill hygiene, add skill, new skill, skill prefix, pre-commit hook fail. |
Skill authoring for galaxy-gen
Discipline document for the .agents/skills/ surface in this repo. The skill content and the categories spec live here. The validator and link checker run as pre-commit hooks stamped from the shared agentic-os hook suite.
Full structural rules are in references/handbook.md.
Layout
galaxy-gen/
├── .agents/skills/
│ ├── categories.yaml # spec consumed by the skill-conventions hook
│ ├── coding-galaxy-gen-*/ # per-skill directories
│ │ └── SKILL.md
│ └── tooling-skill-authoring/ # this skill
│ ├── SKILL.md
│ └── references/handbook.md
└── .pre-commit-config.yaml # managed block stamped by agentic-os-kai
All skills sit flat under .agents/skills/. No nesting. Sub-skill directories are invisible to the harness loader.
Categories
Galaxy-gen's categories.yaml currently allows two families:
coding-galaxy-gen-* - design and reference skills scoped to this repo's procedural galaxy sim. The three current skills (-astrophysics, -cosmology, -references) all live here.tooling-* - agent-ecosystem meta. Only tooling-skill-authoring for now.
Adding a new prefix or exact-name skill: edit categories.yaml, then create the directory. The validator rejects unknown names by design.
SKILL.md frontmatter
Every SKILL.md begins with YAML frontmatter:
---
name: <directory-name>
description: <one paragraph; pack keyword aliases for discoverability>
---
The description field is what the harness keyword-matches for triggering. Lead with the canonical name, then pack 5-10 natural-language phrasings users (and agents) might reach for. Don't be terse.
Authoring loop
- Pick the prefix. If none fits, add to
categories.yaml first.
- Create
.agents/skills/<name>/SKILL.md with frontmatter + body.
- Stage with
git add and commit. The pre-commit hooks run automatically:
skill-conventions - structure, size, prefix taxonomy. Reads .agents/skills/categories.yaml.dead-cross-links - inline [text](path.md) targets inside .agents/skills/ must resolve.commit-closes-issue - commit message must close a same-repo GitHub issue.trufflehog - secret scan (local hook).ward-lockdown - audit-log and permission-boundary hooks generated by ward.
To run the structural checks manually before committing, install pre-commit and run pre-commit run --all-files.
Voice rules
- No italics. Bold only for structural anchors.
- No prose tables. Use flat bullets:
* <anchor> - <category> - <details>.
- No semicolons in prose. Split into separate sentences.
Size cap
SKILL.md is hard-capped at 500 lines and 10 KB by the validator. Past either, the harness loader degrades. Push detail into references/<topic>.md under the same skill directory if a SKILL.md is filling up. Reference files are not capped.
Encode the why, not just the what
Every agent session starts cold. There is no human to ask why a rule was written. Each authoring rule should carry decision context, not just procedure.
Shape: lead with the rule, then a Why: line (incident, constraint, prior failure mode), then a How to apply: line (when the rule fires). Date-stamp the flag where useful so a future read can judge whether the why is still load-bearing.
Skills are flat, not nested
Every skill is a peer directory directly under .agents/skills/. Do not nest sub-skills inside another skill's directory. Nested-skill discovery is poorly supported by the harness.
How to apply: routing tables in a meta-skill name peer-skill names, not paths into the meta's own dir. New routed skills get their own top-level directory.
Design references stay in the repo
The skills here are design or usage reference for the galaxy-gen procedural sim. They are most useful adjacent to the code they describe, surface only in this repo's agent session, and gate through this repo's CI.
If a skill ever grows a runbook role (anti-signals, case library, "what to check when X breaks"), it probably belongs in a centralized investigation surface rather than in this repo. Runbook content benefits from being findable regardless of which repo's session an investigator happens to be in.
Cross-links
Two valid forms for in-prose references to other skills:
- Bare backticks:
`skill-name` - passing mention, not navigable.
- Markdown link:
[`skill-name`](../skill-name/SKILL.md) - navigable.
If the name does not resolve to a real skill in this repo, dead-cross-links flags it. External URLs and paths that escape the repo (../something/...) are out of scope.
Upgrading the hooks
When the canonical scripts in agentic-os change, re-run the shared hook rollout from the appropriate control repo to re-stamp local copies into every consumer repo. Re-run the suite to confirm nothing broke before pushing.
