What problem does it solve? A malformed SKILL.md can pass formatting, spell-check, and tree-sync checks yet silently never load in Claude Code or Codex CLI, and hand-edited mirror copies drift from their source. This Skill defines the authoring, mirroring, and validation workflow that keeps skills discoverable and the two skill trees byte-identical. ## Core Features & Use Cases - Single-source authoring workflow: Edit skills only under .agents/skills/, then mirror into .claude/skills/ with pnpm agents:sync, never hand-editing the generated copy. - Frontmatter contract: Enforces exactly two keys (name and description), name matching the directory, English-only text, and a length cap, validated by tests/skills-frontmatter.test.ts. - Layout and drift rules: One directory level per skill, no nested SKILL.md files, no symlinks, with pnpm agents:check and a pre-commit hook comparing both trees byte for byte. - Use Case: When adding a new skill, you write .agents/skills/<name>/SKILL.md with a two-line ownership block, run pnpm agents:sync, pnpm agents:check, and pnpm test, then commit both trees knowing the skill will actually load in both hosts. ## Quick Start Ask the AI to create a new skill named my-workflow under .agents/skills/ following the authoring rules, then sync and validate it with pnpm agents:sync, pnpm agents:check, and pnpm test.
