[windischb]

What

The Cocoar.Configuration package now carries an Agent Skill so a coding assistant in a consuming project knows the library's API and the mistakes it would otherwise make. The pattern is the one Cocoar.SignalARRR uses: the documentation is the only source.

• website/scripts/sync-skill.mjs generates skills/cocoar-configuration/ from website/guide and website/reference (66 files, ~341 KB). Every page becomes a reference file; the page's frontmatter description — the line that already feeds llms.txt — becomes its entry in the SKILL.md index.
• website/skill/SKILL.header.md is the only hand-written part: trigger description, package table, and "things an assistant gets wrong without the docs".
• Cocoar.Configuration.csproj packs the skill into skills/ at the package root — not contentFiles, so it takes no part in consumers' builds or IDEs.
• 07-verify-agent-skill.yml runs the script with --check. It is its own workflow because the validation workflows only trigger on src/**, and a docs-only change must be caught too.
• Docs: "Agent Skill" section in reference/packages.md, changelog entry, note in CLAUDE.md.

Differences from the SignalARRR script

• Also strips <Badge … /> and {#id} heading anchors, which these docs use, and fails on an unknown ::: container instead of passing it through.
• Does not append .html to links to real files or directories (/llms.txt, /adr/).
• No hardcoded version in the skill header, so it cannot drift.
• srcExclude: ['skill/**'] in the VitePress config keeps the header from being published as a docs page.

Verification

• --check fails when a docs page changes without regenerating, and passes again after reverting.
• No VitePress syntax left in the generated files; every relative link resolves to an existing file.
• Locally packed Cocoar.Configuration nupkg contains all 66 files under skills/cocoar-configuration/, none under contentFiles.
• vitepress build passes; the header is not published and not in llms.txt.

Not verified: agentskills-cli add Cocoar.Configuration against a published package — that is what the next prerelease is for.

Review focus

website/skill/SKILL.header.md is the only new prose. The generated skills/ folder is noise in the diff.

🤖 Generated with Claude Code