writing-skills

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
        
 
     
 
     
 []
 [, ]