How to make your AI agent understand your codebase

The workflow pass ships with 33 hand-written operational skills. They are the difference between an AI that knows the Stripe SDK and one that knows how your team operates Stripe, what your test-vs-live policy is, which webhook events your code actually handles, and which CLI command to reach for when a customer needs a refund.

//What an Ops Skill Is

An ops skill is a Claude Code Skill (YAML frontmatter + Markdown body) tuned for operational work rather than codebase work. Each one:

Has a name ending in -ops (e.g. stripe-ops, linear-ops).
Lives at <skills-dir>/<tool>-ops/SKILL.md alongside any codebase skill named <tool>.
References the tool's CLI (where one exists) and its MCP server (where one exists).
Includes a "When to invoke this skill" block keyed on operational verbs, refund, dispute, transition, deploy, replay, query, plus the env-var prefixes used by that tool.
Has 2–4 placeholders templated from your answers during /saikit-workflows.

//Codebase vs. Ops Skills

The naming convention is deliberate. The codebase analyzer generates a skill named <tool> that captures SDK patterns inside this repo. The workflow pass generates <tool>-ops that captures operating the tool. Both can be installed at once and Claude picks between them based on your request.

| Skill | Triggered when you say… | Example | | --- | --- | --- | | stripe | "wire up a checkout session", "add a subscription endpoint" | SDK pattern: idempotency keys, type-safe metadata, error handling in this repo | | stripe-ops | "issue a refund", "why is this subscription stuck", "tail webhooks" | CLI: stripe refunds create …, dashboard nav, webhook replay, MRR queries |

Because both descriptions sit in front of the model, the skill that wins is the one whose description best matches the request, and they stay out of each other's way.

//How Templating Works

Each ops skill ships in the catalog with {{placeholders}}. During /saikit-workflows, the binary fetches a questions.json for the tool and asks them in chat. Your answers get substituted into the skill body before it lands on disk.

Stripe's questions:

code

{
  "questions": [
    {
      "id": "primary_workflow",
      "label": "Describe your primary Stripe workflow",
      "placeholder": "subscription billing for SaaS, handle renewals, dunning for failed charges, prorated upgrades.",
      "multiline": true,
      "required": true
    },
    {
      "id": "webhook_events",
      "label": "Which Stripe webhook events does your code handle?",
      "placeholder": "checkout.session.completed, customer.subscription.updated, invoice.payment_failed",
      "required": true
    },
    {
      "id": "test_mode_policy",
      "label": "What's your test-vs-live policy?",
      "placeholder": "All local + staging hits test keys; production uses live. Refunds over $500 require manual review.",
      "multiline": true,
      "required": false
    }
  ]
}

The body of stripe-ops/SKILL.md has matching {{primary_workflow}}, {{webhook_events}}, {{test_mode_policy}} blocks. The binary substitutes them before writing.

Optional questions can be skipped (reply skip), placeholders are removed cleanly when their answer is empty.

//Anatomy: stripe-ops

Frontmatter:

code

---
name: stripe-ops
description: Operate against the Stripe API safely, refunds, disputes, subscription debugging, webhook scaffolding, MRR queries via the `stripe` CLI and Stripe MCP. Use for operational tasks (issuing a refund, tailing webhooks, finding stuck subscriptions, replaying events). For codebase-level Stripe SDK usage patterns in this repo, use the `stripe` skill instead.
license: Proprietary
metadata:
  category: payments
  tool: stripe
  generated_by: summonaikit
  skill_kind: ops
compatibility: Requires the `stripe` CLI and a STRIPE_SECRET_KEY in the environment. Webhook listening requires `stripe listen`.
---

Body sections:

| Section | Purpose | | --- | --- | | Your workflow | {{primary_workflow}}, the user's one-paragraph description | | Webhook events you handle | {{webhook_events}}, the list the code subscribes to | | Test mode policy | {{test_mode_policy}}, the team's rule for when test keys are used | | When to invoke this skill | Operational verbs + env-var hints + filename hints | | Operating principles | Hardcoded principles: test mode first, idempotency keys mandatory, webhooks are source of truth, no secrets in logs | | Common operations | Concrete recipes, refunds, dispute responses, subscription rescue, webhook replay, MRR computation | | References | Files in references/ (loaded on demand via progressive disclosure) |

The "operating principles" and "common operations" sections are hand-written, not generated. They reflect industry best practice for the tool, Claude doesn't need to invent a refund procedure from scratch.

//The 33 Ops Skills

| Category | Skills | | --- | --- | | Ticketing | linear-ops, jira-ops, github-issues-ops, notion-ops | | Documentation | notion-docs-ops, confluence-ops, in-repo-adr-ops | | Communication | slack-ops | | Error Tracking | sentry-ops, datadog-ops | | Analytics | posthog-ops | | Payments | stripe-ops, polar-ops | | Cloud | cloudflare-ops, vercel-ops | | Database | supabase-ops, neon-ops, postgres-ops, drizzle-ops, prisma-ops | | Auth | better-auth-ops, clerk-ops | | Email | resend-ops | | Design | figma-ops | | Marketing (Founder) | hubspot-ops, customer-io-ops, meta-ads-ops | | Product (Founder) | intercom-ops, cal-com-ops, statsig-ops | | SEO (Founder) | gsc-ops, structured-data-ops, profound-ops |

Solo tier gets 24 of these. Founder gets all 33.

//When Claude Picks One

Claude (or Cursor, or Codex) loads the name + description of every skill at session start. When a user request comes in, the model scores each description against the request semantically and picks the highest match.

That makes the description the most important field in an ops skill. The descriptions ship deliberately keyword-dense:

Operational verbs the user will say: refund, dispute, replay, transition, deploy, roll back, invalidate, regenerate.
Tool surface words: CLI, webhook, event, flag, cycle, sprint.
Env-var prefixes: STRIPE_, LINEAR_, SENTRY_, so a request that mentions one of those vars activates the right skill.
Disambiguation: each ops skill explicitly mentions its codebase counterpart so the two don't fight.

//Updating an Ops Skill

Three ways to refresh:

Re-run /saikit-workflows for the same tool. The binary detects the existing skill, asks if you want to update the answers, and re-templates.
Run /saikit-update --scope=skills to refresh every skill (codebase + ops) in place.
Edit the file directly at .claude/skills/<tool>-ops/SKILL.md. The kit treats your edits as authoritative and doesn't blow them away, only /saikit-update rewrites, and only when scoped to skills.