# agent-skills

An agent-agnostic skill catalog published to Claude Code, Codex, Cursor, Grok,
Copilot, Windsurf, Kiro and Hermes Agent.

## Hard rules

- `catalog/skills.json` is the ONLY source of truth for plugin and skill
  metadata. Everything else is generated.
- NEVER hand-edit a generated file. Generated files carry
  `<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->`.
  Generated: every `plugins/*/.claude-plugin/plugin.json`,
  `.claude-plugin/marketplace.json`, `.cursor-plugin/`, `.grok-plugin/`,
  `adapters/`, `.windsurf/rules/`, `.kiro/steering/`, `.github/prompts/`,
  `.github/copilot-instructions.md`.
- Canonical skill content lives at `plugins/olko-<plugin>/skills/<skill>/SKILL.md`
  and nowhere else.
- After ANY catalog or skill change, run `./scripts/build-adapters.sh` and commit
  the result. CI fails if the generated tree is stale.
- Plugin names are kebab-case and prefixed `olko-`. Skill `name:` frontmatter is
  unprefixed and must match its directory name.
- Every skill belongs to exactly one plugin. Every plugin has at least one skill.
- No em dashes in skill content or generated text.
- Commit messages are conventional (`feat:`, `fix:`, `refactor:`, `docs:`,
  `test:`, `chore:`); semantic-release parses them. Never mention an assistant.

## Adding a skill

1. Create `plugins/olko-<plugin>/skills/<skill>/SKILL.md` with valid frontmatter.
2. Register it under that plugin's `skills` array in `catalog/skills.json`.
3. Add it to `PLUGIN_ASSIGNMENT` in `scripts/lib/catalog.mjs`.
4. Add its row to the README table.
5. Run `./scripts/build-adapters.sh && npm test`.

## Commands

- `npm run build` regenerates every manifest and adapter.
- `npm run validate` checks frontmatter and catalog integrity.
- `npm test` runs the validators plus the bash tests in `tests/`.