summonaikit
Back to Docs
// SKILL_GENERATION

Skill Generation

How SummonAI Kit generates Claude Code Skills, analyzer prompts, the SKILL.md spec, naming rules, MCP-aware context, and the difference between codebase, ops, and dev-cycle skills.

A Skill is a single markdown file (with optional supporting files) that teaches Claude Code, Cursor, or Codex how to do a specific kind of work. SummonAI Kit generates three kinds, codebase, ops, and dev-cycle, and each is shaped for a different job.

This page explains how the kit produces them, what the resulting files look like, and the rules they follow.

//What a Skill Is

The Agent Skills spec defines a skill as a directory with a SKILL.md at its root. The file has YAML frontmatter (at minimum name and description) and a Markdown body. The AI loads the name + description of every skill at session start, then loads a skill's full body only when it matches a request.

The benefit is asymmetric:

  • Cheap at startup, only the descriptions are in context.
  • Rich on demand, when a skill matches, the body comes in plus any referenced files.

The kit leans into this. Codebase skills stay under 200 lines each, ops skills reference scripts and references/*.md files via progressive disclosure, and the dev-cycle skill stays compact so it can sit in context for every relevant turn.

//Three Kinds of Skills

| Kind | Generator | Lives at | Captures | | --- | --- | --- | --- | | Codebase | Pass 1, summonaikit | <skills>/<tech>/SKILL.md | SDK patterns, file layout, in-repo conventions for one library / framework / runtime | | Ops | Pass 2, /saikit-workflows | <skills>/<tool>-ops/SKILL.md | CLI commands, runbooks, MCP usage, operational verbs for one tool | | Dev-cycle | Pass 2, /saikit-workflows | <skills>/dev-cycle/SKILL.md | Branch / commit / PR conventions, ticket lifecycle, post-merge motion, autonomous-mode permissions |

The naming convention stripe (codebase) vs. stripe-ops (operational) means both can coexist. The descriptions are written so semantic matching picks the right one, stripe for "wire a checkout session", stripe-ops for "issue a refund". See Ops Skills for the disambiguation rules.

//The SKILL.md Spec

Required frontmatter:

code
---
name: <kebab-case, ≤ 64 chars, lowercase letters/numbers/hyphens only,
       no leading or consecutive hyphens>
description: <what it does and when to use it, max 1024 chars>
---

Optional frontmatter:

code
---
allowed-tools: Read, Grep, Glob       # restrict tool access while active
model: claude-sonnet-4-6              # override per-skill model
license: Proprietary                  # legal note
metadata:
  category: payments
  tool: stripe
  generated_by: summonaikit
  skill_kind: ops                     # ops | codebase | dev-cycle-playbook
compatibility: Requires the `stripe` CLI and STRIPE_SECRET_KEY in env.
---

Body is normal Markdown. Headings, tables, code blocks all render. Reference files live in the same directory and are loaded lazily.

//Naming Rules

The kit validates skill names end-to-end against the Agent Skills spec (tightened in CLI v2.0.25):

  • Lowercase letters, digits, and hyphens only.
  • Maximum 64 characters.
  • No leading hyphen.
  • No consecutive hyphens.

Examples:

| Valid | Invalid | | --- | --- | | react-query | React-Query (uppercase) | | stripe-ops | -stripe-ops (leading hyphen) | | feature-flag-hygiene | feature--flag (consecutive hyphens) | | gsc | google-search-console-ops-with-everything-you-could-possibly-need (over 64) |

The CLI rejects out-of-spec names at the input step in Manual Mode and at the validation step in Analyze Mode. Premade ops skills are fixed to the <tool>-ops form (the binary derives the name; you can't override).

//How the Analyzer Generates Codebase Skills

For each detected technology, the analyzer:

  1. Reads relevant files, package.json, the tech's config (drizzle.config.ts, tailwind.config.ts, …), and a sample of files that import the library.
  2. Composes a system prompt specific to the skill kind ("you are generating a Claude Code Skill that captures Drizzle ORM usage in this repo, focused on schema, migrations, query patterns…").
  3. Cites the version from package.json so the description and body match what the repo actually uses.
  4. Names files in the body so Claude can grep to confirm patterns later.
  5. Writes a description with high-signal keywords, library name, version, and the operational verbs that would activate the skill.

The analyzer model is picked per AI CLI:

| AI CLI | Model | | --- | --- | | Claude Code | Claude Sonnet (latest) | | Cursor | Claude Opus (latest) | | Codex | OpenAI Codex 5.3 |

(Picked automatically, the legacy "choose your model" picker was removed in v2.0.8.)

//MCP-Aware Context

If the analyzer detects MCPs configured in your AI CLI (Context7, Sentry, Stripe, GitHub, etc.), it references them by name in the generated skills. A sentry codebase skill in a project that has the Sentry MCP wired will mention mcp__sentry__* tool names rather than telling Claude to "open the Sentry dashboard".

This was added in v1.2.0. It changes the value of the kit dramatically, generated skills don't pretend the AI is browser-bound when it has direct API access through MCP.

//Context7 Pull-Through

If you have Context7 configured (mcp__context7), generated skills include "Use Context7 to fetch live framework docs" instructions wherever doc lookup matters. This lands library docs into the AI's context fresh, rather than relying on training-data cutoffs.

The kit detects Context7 from your MCP config and adjusts skill bodies automatically. No setup beyond having Context7 installed.

//Progressive Disclosure

For ops skills (and any codebase skill that grows past ~200 lines), the kit follows the progressive-disclosure pattern from the Agent Skills spec:

code
stripe-ops/
├── SKILL.md          # Overview, principles, common operations (loaded on activation)
├── references/
│   ├── refunds.md    # Detailed refund playbook (loaded when needed)
│   ├── webhooks.md   # Webhook event reference
│   └── disputes.md   # Dispute response runbook
└── scripts/
    └── replay.sh     # Webhook replay helper (executed, not loaded into context)

SKILL.md references the supporting files by relative path:

code
For the full webhook event catalog, see [references/webhooks.md](references/webhooks.md).
For the dispute-response runbook, see [references/disputes.md](references/disputes.md).

Claude loads them on demand. Scripts are executed without their source ever entering context, only the output costs tokens.

//Description Quality, The Most Important Field

A skill's description is what determines whether it ever runs. The model picks skills by matching user requests against descriptions semantically; a vague description loses to a specific one.

The kit writes descriptions that:

  • Lead with what the skill does, not what it is.
  • Include verbs the user will say (refund, dispute, transition, deploy, replay, scaffold, debug, query).
  • Mention environment variables the tool uses (STRIPE_*, LINEAR_*).
  • Disambiguate from neighboring skills, stripe-ops ends with "For codebase-level Stripe SDK usage patterns, use the stripe skill instead."

If you write your own skills via Manual Mode or hand-edit a generated one, follow the same rules. A 30-second improvement to the description is worth more than 30 minutes spent on the body.

//Cost Per Skill

Skill generation runs in parallel under a per-CLI concurrency cap (added in v2.0.22). The end-of-run summary breaks cost down by model:

code
Generated 7 skills, 5 subagents in 47s.
  haiku:  $0.04   (lightweight detection passes)
  sonnet: $0.21   (skill bodies)
  opus:   $0.00
Total:    $0.25

A typical mid-size monorepo costs single-digit dollars for a full Analyze Mode run. The workflow pass costs almost nothing, premade skills don't generate, they're fetched and templated.

Skill Generation | SummonAI Kit Docs