Write your AI agent workflow once. Sync it everywhere.
Portable skills for Claude Code, Cursor, Gemini, and Codex — start, review, deploy — across all your projects.
AI coding agents are powerful, but every project reinvents the same workflows: how to create issues, open PRs, run reviews, deploy releases. These instructions live in scattered prompt files, maintained per-project, per-agent, with no consistency and no reuse.
Code Cannon is a repository of portable agent skill groups — each group is a focused, domain-specific bundle of skills written once as plain markdown. A sync script reads your project config, picks the one group you've enabled, and generates agent-specific command files:
skills/<group>/*.md → sync.py + .codecannon.yaml → .claude/commands/*.md
→ .cursor/rules/*.mdc
One source of truth for every project and every agent. Pick the group that matches how you work.
| Group | What it's for |
|---|---|
github-agile |
GitHub-based agile workflow — every change gets an issue, PR reviews required, releases via /deploy |
More groups (lighter solo flows, JIRA variants, RFP tooling, …) are planned. Each project enables exactly one group.
A complete development workflow in five commands:
/start → [code + test] → /submit-for-review → [QA] → /deploy
| Command | What it does |
|---|---|
/start |
Create a GitHub issue, feature branch, and write code |
/submit-for-review |
Check, commit, open PR, run AI review, merge |
/review |
Standalone code review on any PR |
/deploy |
Bump version, create a GitHub Release, promote to production |
/status |
Standup-ready snapshot of PRs, issues, and progress |
Plus /qa for structured QA workflows and /setup for guided onboarding.
Humans stay in the loop. The agent proposes; you approve. /start waits for your sign-off before creating anything. /deploy requires explicit confirmation.
Every change has a ticket. There is no path for code without an issue. The issue is the unit of work — branch, PR, and release all link back to it.
Configure, don't fork. Skills use {{PLACEHOLDER}} tokens. Your .codecannon.yaml fills them in. When upstream improves, pull the submodule and re-sync.
Anyone can write a skill. What separates a good one from a bad one is not how thoroughly it dictates procedure — it is token economy, respect for the developer's attention, and knowing which decisions belong to the workflow versus which belong to the agent.
Early skills, written for weaker models, spelled out not just what outcome to produce but how to produce it: how to parse an argument string, what date format to use, which emoji maps to which CI state. Capable agents do all of that unaided. Over-specification looks rigorous and is actually fragile — it burns context on instructions the model does not need, it breaks whenever the underlying tool changes, and it stops a capable agent from doing something smarter than the author imagined.
Code Cannon holds every instruction to one test:
Prune where model variance produces a different-but-fine result. Keep where model variance produces a wrong result.
Report formatting, argument parsing, and investigation method fall on the prune side — a differently-shaped-but-correct result is harmless. Ordering guarantees, human approval gates, platform behaviour a model cannot derive, and review policy fall on the keep side — variance there is a defect. Pulling back is not the same as removing constraints: everything that encodes a real rule stays exactly as it is. The skill authoring guidance in AGENTS.md applies this test in full, including the two categories — prompt-avoidance instructions and platform-behaviour notes — that read as noise but are load-bearing, and the reminder to calibrate against the weakest supported model, not the strongest.
Requires Python 3.8+ (stdlib only — no pip install needed).
git submodule add https://github.com/LightbridgeLab/CodeCannon.git CodeCannon
cp CodeCannon/templates/codecannon.yaml .codecannon.yaml
# Edit .codecannon.yaml — make sure `skill_group:` names the bundle you want
CodeCannon/sync.pyThen optionally run /setup for a guided walkthrough.
To update to the latest version:
CodeCannon/sync.py --update- Getting started — full quickstart, migration guide, and workflow details
- Branching models — trunk, two-branch, and three-branch workflows
- Customization — tailoring skills, sync.py reference
- Config reference — every
.codecannon.yamlsetting documented - Adapters — supported agents and how to add new ones
- Skill reference: /start · /submit-for-review · /review · /deploy · /qa · /status · /setup