| name | writing-skills |
| version | 1.0 |
| last_updated | 2026-07-20 |
| id | writing-skills |
| one_line_purpose | Author or maintain a testsuite skill doc within the size and format rules. |
| entry_point | docs/skills/meta/writing-skills/SKILL.md |
| category | meta |
| mcp_compliance_level | partial |
| status | active |
| dependencies | [] |
| tags | ["skills","authoring","docs"] |
| description | How to write, split, and review docs/skills/ files in testsuite. Load when creating, editing, or deleting a skill. |
| metadata | {"type":"meta","audience":"agents","maturity":"stable"} |
Writing skills for testsuite
When to Use
- Creating a new skill in
docs/skills/.
- Splitting an oversized skill into
SKILL.md + references/.
- Updating a skill after discovering a new pattern or workaround.
- Proposing deletion or merge of stale skills.
When NOT to Use
- For root
AGENTS.md or README.md changes — see meta/skill-improvement/SKILL.md for the update trigger.
- For one-off prose that does not describe when an agent should load it.
Directory and file naming
- Path:
docs/skills/<category>/<name>/SKILL.md, where <category> is one of
ci-ops, test-authoring, or meta.
- Directory name must equal the frontmatter
name and id.
name: 1–64 chars, lowercase alphanumerics and hyphens only, no leading/trailing hyphen, no consecutive hyphens.- Optional:
references/, scripts/, assets/ inside the skill directory.
Router and catalog exceptions
docs/SKILL.md is the task router required by the factory onboarding
contract. It carries the same front-matter schema but lives outside
docs/skills/.docs/skills/index.md and docs/skills/index.json are generated by
scripts/generate_skill_index.py. Never hand-edit them.
Frontmatter schema
The schema matches projectbluefin/common's catalog contract so factory tooling
can read either repo. Canonical definition: docs/skills/index.schema.json.
---
name: example
version: "1.0"
last_updated: "2026-08-07"
id: example
[]
[, ]
