Context
.ai-context/skills/*.md currently ships as flat markdown files with no frontmatter, discovered only via a manually-maintained table in the scaffolded project's CLAUDE.md. This predates the Agent Skills specification, an open, vendor-neutral standard (SKILL.md + YAML frontmatter with name/description, optional scripts//references//assets/, progressive disclosure).
Problem with current approach
- No discovery mechanism -> the index (
.ai-context/skills/README.md) has to be kept in sync by hand and has already drifted (files present but unindexed, and vice versa).
- No automatic activation -> relies entirely on the agent reading and following the CLAUDE.md table every time.
Proposal
Restructure .ai-context/skills/*.md into .ai-context/skills/<skill-name>/SKILL.md per the Agent Skills spec: name + description frontmatter, body content, optional references/ for the larger reference docs currently inline. This keeps the cross-agent goal (works for Claude Code, Cursor, etc.) that presumably motivated the original flat-file design, while gaining spec-driven discovery instead of a hand-maintained table.
Open question for maintainers: how many of the target agents (Claude Code, Cursor, Copilot, ...) actually parse SKILL.md today? Worth confirming before a full migration.
Scope: docs/structure only, no code changes.
Context
.ai-context/skills/*.mdcurrently ships as flat markdown files with no frontmatter, discovered only via a manually-maintained table in the scaffolded project's CLAUDE.md. This predates the Agent Skills specification, an open, vendor-neutral standard (SKILL.md+ YAML frontmatter withname/description, optionalscripts//references//assets/, progressive disclosure).Problem with current approach
.ai-context/skills/README.md) has to be kept in sync by hand and has already drifted (files present but unindexed, and vice versa).Proposal
Restructure
.ai-context/skills/*.mdinto.ai-context/skills/<skill-name>/SKILL.mdper the Agent Skills spec:name+descriptionfrontmatter, body content, optionalreferences/for the larger reference docs currently inline. This keeps the cross-agent goal (works for Claude Code, Cursor, etc.) that presumably motivated the original flat-file design, while gaining spec-driven discovery instead of a hand-maintained table.Open question for maintainers: how many of the target agents (Claude Code, Cursor, Copilot, ...) actually parse
SKILL.mdtoday? Worth confirming before a full migration.Scope: docs/structure only, no code changes.