Immutable. This exact content is served forever at /api/v1/blob/078615c33daab697.
# AGENTS.md Instructions for AI coding agents working in the OrchestKit repository. This is the vendor-neutral companion to `CLAUDE.md`; where both exist, they say the same thing. OrchestKit is a plugin for Claude Code (Anthropic's agentic CLI). It packages reusable skills, specialist agents, and lifecycle hooks. It is source-built: you edit `src/` and a build step assembles the installable `plugins/` tree. It is not a hosted service and has no runtime backend. ## The one rule that prevents most broken PRs **Edit `src/` and `manifests/`. Never edit `plugins/` by hand — it is generated.** ``` src/ ← EDIT HERE skills/<name>/SKILL.md # skills (YAML frontmatter + Markdown body, <500 lines) agents/<name>.md # agents (frontmatter: name, description, model, tools, skills) hooks/src/<category>/*.ts # TypeScript lifecycle hooks manifests/ ← EDIT HERE (plugin definitions) plugins/ ← GENERATED by `npm run build` — do not hand-edit ``` After any `src/` change, run `npm run build`, then stage the resulting `plugins/` diff **together with** your `src/` change in the same commit. A `plugins/` diff after a build is expected, not noise. If `plugins/` comes out empty, the build was interrupted — run it again. ## Build and verify ```bash npm run build # assemble plugins/ from src/ — required after editing src/ npm test # full suite (lint + unit + security + integration + e2e) npm test --quick # skip integration/e2e/performance npm run test:skills # skill structure validation npm run test:agents # agent frontmatter validation npm run test:security # security tests — MUST pass, gates push npm run typecheck # TypeScript check (run if hooks changed) ``` Before opening a PR: `npm test` and `npm run test:security` must pass, and `git diff` should show real changes (not no-ops left over from a previous session). ## Adding a component - **Skill** — create `src/skills/<name>/SKILL.md` with frontmatter (`name`, `description`, `tags`, `user-invocable`, `complexity`); body stays under 500 lines. Add it to `manifests/ork.json`, then `npm run build`. See `src/skills/CONTRIBUTING-SKILLS.md`. - **Agent** — create `src/agents/<name>.md` with the required frontmatter, add to the manifest, rebuild. - **Hook** — create `src/hooks/src/<category>/<name>.ts` and register it in **both** `src/hooks/hooks.json` **and** the entries map `src/hooks/src/entries/<event>.ts`. One without the other is a silently-dead hook. Rebuild with `cd src/hooks && npm run build`. Component counts live in three places (`manifests/ork.json`, the CLAUDE.md version section, and the hooks.json description for hooks). Keep them in sync — `npm run test:manifests` catches drift. ## Working conventions - Branch off `main` with a typed prefix (`feat/`, `fix/`, `docs/`, `chore/`). Never commit directly to `main`. - Never bypass hooks with `--no-verify`. Never commit secrets or generated-only diffs. - Conventional Commits for messages and PR titles; keep them plain (no emoji). - Close issues by putting `Closes #N` in the PR body — a PR merge to main closes them via CI. Do not close issues by hand. ## Where to learn more - `README.md` — product overview and quick start. - `CLAUDE.md` — the same rules with Claude-Code-specific detail. - `src/skills/CONTRIBUTING-SKILLS.md` — full skill-authoring standard. - `src/hooks/README.md` — hook architecture and the hook registry. - Docs site: https://orchestkit.yonyon.ai · Repo: https://github.com/yonatangross/orchestkit