How to make your AI agent understand your codebase

/saikit-workflows is the second pass of the SummonAI Kit setup. Where the codebase pass teaches the AI about your code, the workflow pass teaches it about your team, the trackers you ticket in, the platforms you ship to, the comms channels deploys land in, and the conventions that turn a pull request into a release.

It runs in chat, inside Claude Code, Cursor, or Codex. You spend ten minutes answering short questions and walk away with a project that knows how you ship.

//What It Does

In one run, /saikit-workflows:

Asks which of 14 integration categories you care about.
Detects which tools in those categories are present in your repo (deps, env vars, config files).
Confirms detected tools with you, then asks two or three short questions per tool about how you operate it.
Installs the matching ops skill from a catalog of 33 hand-written skills, templated with your answers.
Wires every available MCP server into .mcp.json (or .codex/config.toml for Codex).
If you have both ticketing and code-hosting confirmed, asks seven workflow questions and synthesizes a dev-cycle playbook, a project-level skill that captures branch naming, commit footers, PR title patterns, ticket transitions, and what fires after merge.
Optionally writes cross-tool slash commands (/start-task, /ship, /post-merge) and guardrail hooks (block force-push, block .env edits, block direct push to main).

When it's done it prints a one-line summary of every artifact written.

//The Mental Model

There are two kinds of skills in SummonAI Kit:

| Skill kind | Source | Naming | What it knows | | --- | --- | --- | --- | | Codebase skill | Pass 1, analyzer | <tool> (e.g. stripe, drizzle) | SDK usage patterns, in-repo conventions, file layout | | Ops skill | Pass 2, /saikit-workflows | <tool>-ops (e.g. stripe-ops, drizzle-ops) | CLI commands, runbooks, refunds/disputes/migrations, MCP usage |

They live alongside each other. stripe says "use Stripe.checkout.sessions.create here, idempotency key like this, never log pi_*". stripe-ops says "to issue a refund, run stripe refunds create --charge=ch_... in test mode first, your team's test-vs-live policy is X". Claude picks between them via the description on each.

//The Flow, End to End

code

You          AI in chat                                         summonaikit binary
─────        ─────────────                                      ──────────────────
/saikit-workflows
             → workflow run --json
                                                                {kind: ask, options: [14 cats]}
             AskUserQuestion
ticketing,
payments,
errors
             → workflow run --state=… --json
                                                                {kind: message}        # detection runs
             → workflow run --state=… --json
                                                                {kind: ask, options: [linear, github-issues]}
             AskUserQuestion
linear
             → workflow run --state=… --json
                                                                {kind: ask, options: [stripe]}
…
             AskUserQuestion + free-text (3 short Qs / tool)
             → workflow run …
                                                                {kind: bash, command: install-skill linear}
             Bash
                                                                {kind: bash, command: install-skill stripe}
             Bash
                                                                {kind: ask, options: [linear, sentry, stripe]}   # MCPs
             AskUserQuestion
all
                                                                {kind: write, path: .mcp.json, content: …}
             Write
                                                                {kind: free-text}    # 7 playbook questions
…
                                                                {kind: write, path: .claude/skills/dev-cycle/SKILL.md}
             Write
                                                                {kind: ask, options: [start-task, ship, post-merge]}
             AskUserQuestion
ship
                                                                {kind: write, path: .claude/commands/ship.md}
             Write
                                                                {kind: ask, options: [force-push, env-edit, main-push]}
             AskUserQuestion
all
                                                                {kind: write, path: .claude/settings.json}
             Write
                                                                {kind: done, summary: […]}
             Display summary

The slash command is a thin protocol executor. The binary returns one instruction, the AI executes it, the AI calls back with the new state. State is opaque base64 JSON, the AI never inspects or edits its shape, only merges in user answers at the path the binary specifies.

//What Gets Installed

After a full run, your project picks up:

code

.mcp.json                                      # HTTP MCP servers (Claude/Cursor)
.codex/config.toml                             # MCP servers (Codex)
.claude/settings.json                          # Guardrail hooks (Claude only)
.claude/skills/<tool>-ops/SKILL.md             # 1 per confirmed tool
.claude/skills/dev-cycle/SKILL.md              # if ticketing + code-hosting confirmed
.claude/commands/start-task.md                 # if opted in
.claude/commands/ship.md                       # if opted in
.claude/commands/post-merge.md                 # if opted in

Every artifact is documented in its own page:

Categories & Tools, the 14-category catalog and 110 supported tools
Ops Skills, what the 33 hand-written ops skills look like and how they're templated
MCP Wiring, which MCPs are zero-config HTTP, which need stdio + env vars
Dev-Cycle Playbook, the seven questions and the skill they produce
Slash Commands, /start-task, /ship, /post-merge
Guardrail Hooks, Claude Code hook configs

//Multi-Target Fanout

If you've installed into Claude Code, Cursor, and Codex, every artifact fans out:

| Artifact | Claude Code | Cursor | Codex | | --- | --- | --- | --- | | Ops skills | .claude/skills/<tool>-ops/SKILL.md | .cursor/skills/<tool>-ops/SKILL.md | ~/.codex/skills/<tool>-ops/SKILL.md | | Dev-cycle playbook | .claude/skills/dev-cycle/SKILL.md | .cursor/skills/dev-cycle/SKILL.md | ~/.codex/skills/dev-cycle/SKILL.md | | MCP servers | .mcp.json | .mcp.json | ~/.codex/config.toml (TOML, [mcp_servers.*]) | | Cross-tool commands | .claude/commands/*.md | .cursor/commands/*.md | ~/.codex/prompts/*.md | | Guardrail hooks | .claude/settings.json |, |, |

Hooks are a Claude Code feature. Cursor and Codex have incompatible extensibility models, the kit skips rather than misconfigures.

//Idempotency

/saikit-workflows is safe to re-run. The first thing it does is scan your skills directories for existing <tool>-ops skills. Tools that already have an ops skill are filtered out of the per-category detection step.

That means you can run it now for ticketing + payments, then run it again next week to add error tracking, and the second run won't ask anything about Linear or Stripe.

The dev-cycle playbook is append-only. Re-running with new playbook answers adds sections; it never overwrites the answers you gave the first time. To start over, delete the file at .claude/skills/dev-cycle/SKILL.md and re-run.

//Why the Binary Owns the Prompts

Workflow IP, the question text, the playbook templates, the cross-tool command bodies, the hook configs, all lives compiled into the summonaikit binary. The slash command at .claude/commands/saikit-workflows.md is a 60-line protocol executor with no IP of its own.

That keeps three things true:

Updates ship via summonaikit update. No need to re-install slash commands, no chance of running an old workflow against a new binary or vice versa, the binary is the authoritative source for the current protocol.
The chat surface stays clean. The AI in chat doesn't carry the workflow logic in its context; it carries one short instruction at a time, then forgets.
The same flow runs on Claude Code, Cursor, and Codex. Every target speaks AskUserQuestion + Bash + Write, the only three tools the protocol needs.

Workflows Overview