Configuration

AI Kit generates configuration automatically from your project’s tech stack. Here’s how to understand and customize what’s generated.

ai-kit.config.json

This file tracks what AI Kit generated and the scan results. It’s created by ai-kit init and updated by ai-kit update.


{
  "version": "1.5.0",
  "scanResult": {
    "framework": "nextjs",
    "nextjsVersion": "15.1.0",
    "routerType": "app",
    "cms": "sitecore-xmc",
    "sitecorejssVersion": "22.3.0",
    "styling": ["tailwind"],
    "tailwindVersion": "4.0.0",
    "typescript": true,
    "typescriptStrict": true,
    "monorepo": false,
    "figma": {
      "detected": true,
      "figmaMcp": true,
      "figmaCodeCli": false,
      "designTokens": true,
      "tokenFormat": "tailwind-v4",
      "visualTests": false
    },
    "designTokens": {
      "detected": true,
      "colors": ["primary", "secondary", "accent"],
      "fonts": ["sans", "mono"],
      "spacing": [],
      "breakpoints": ["sm", "md", "lg", "xl"],
      "source": "tailwind-config"
    },
    "staticSite": {
      "isStatic": true,
      "outputMode": "isr",
      "hasGenerateStaticParams": true,
      "hasRevalidate": true,
      "hasStaticExport": false
    },
    "aiIgnorePatterns": ["legacy/", "*.generated.ts"],
    "packageManager": "npm",
    "projectName": "my-project",
    "scripts": { "dev": "next dev", "build": "next build" }
  },
  "generatedAt": "2026-03-25T10:00:00.000Z",
  "templates": ["CLAUDE.md", ".cursorrules"],
  "commands": ["prompt-help", "review", "fix-bug"],
  "guides": ["getting-started", "prompt-playbook"],
  "agents": ["planner", "code-reviewer"],
  "contexts": ["dev", "review", "research"],
  "hooks": true,
  "hookProfile": "standard",
  "strictness": "standard",
  "customFragments": [],
  "tools": { "claude": true, "cursor": true }
}

Fields

Field	Description
`version`	AI Kit version that generated this config
`scanResult`	Complete tech stack detection results
`generatedAt`	ISO timestamp of last generation
`templates`	Which template files were generated
`commands`	Which slash commands were copied
`guides`	Which guides were copied
`agents`	Which agents were generated
`contexts`	Which context modes were generated
`hooks`	Whether hooks are configured
`hookProfile`	Hook automation profile (minimal/standard/strict)
`strictness`	Rule enforcement level (relaxed/standard/strict)
`tools`	v1.5.0+ Saved tool selection — reused on `ai-kit init` and `ai-kit update`
`customFragments`	User-provided custom rule fragments

Customizing Generated Rules

Adding Custom Rules

The generated CLAUDE.md and .cursorrules files are wrapped in markers:


<!-- AI-KIT:START -->
[auto-generated content]
<!-- AI-KIT:END -->

Add your custom rules outside the markers — above or below:


# My Custom Rules
 
These rules are specific to this project and won't be overwritten by ai-kit update.
 
- Always use the `useTranslation` hook for text strings
- API calls must go through `src/lib/api-client.ts`
- Feature flags are managed via LaunchDarkly — use `useFeatureFlag` hook
 
<!-- AI-KIT:START -->
[auto-generated content]
<!-- AI-KIT:END -->
 
# Additional Notes
 
- The legacy API is at /api/v1 — don't add new endpoints there
- Contact @sarah for design system questions

When you run ai-kit update, only the content between the markers is refreshed. Everything else stays untouched.

Editing Generated Content

You can edit content inside the markers, but those edits will be lost on ai-kit update. If you need to modify a generated rule:

Add your override outside the markers
Or modify the rule inside markers but remember it resets on update

Per-File Rules (Cursor .mdc)

Cursor .mdc files in .cursor/rules/ can be individually edited. Since ai-kit update regenerates all .mdc files, add your custom rules as separate .mdc files:


.cursor/rules/
├── base.mdc              # Generated by ai-kit (will be overwritten)
├── nextjs-app-router.mdc # Generated by ai-kit (will be overwritten)
├── custom-api.mdc        # Your custom rules (preserved)
└── custom-testing.mdc    # Your custom rules (preserved)

Adding Custom Skills

Add your own skills alongside AI Kit’s generated ones. Skills live in subdirectories with a SKILL.md file:


.claude/skills/
├── review/SKILL.md        # AI Kit generated (will be overwritten on update)
├── new-component/SKILL.md # AI Kit generated (will be overwritten on update)
├── deploy/SKILL.md        # Your custom skill (preserved — AI Kit won't touch it)
└── pr-template/SKILL.md   # Your custom skill (preserved)

.cursor/skills/
├── review/SKILL.md        # AI Kit generated
├── deploy/SKILL.md        # Your custom skill (preserved)

AI Kit only overwrites skill directories it originally created. Any skill directory you add manually will be left untouched on ai-kit update.

Legacy slash commands can also still be added to .claude/commands/ — add any .md file there and AI Kit won’t touch it.

Template Fragments

AI Kit selects template fragments based on your scan. Here’s the logic:


base              → Always included
nextjs-app-router → framework === 'nextjs' AND routerType is 'app' or 'hybrid'
nextjs-pages-router → framework === 'nextjs' AND routerType is 'pages' or 'hybrid'
sitecore-xmc      → cms !== 'none'
tailwind          → 'tailwind' in styling array
typescript        → typescript === true
monorepo          → monorepo === true
figma             → figma.detected === true

Templates live in the AI Kit package at templates/claude-md/ and templates/cursorrules/.

Variable Substitution

Templates use {{variable}} placeholders that are replaced during generation:

Variable	Source	Example
`{{projectName}}`	`package.json` name field	`my-web-app`
`{{techStack}}`	Detected technologies joined	`Next.js 15 · Sitecore XM Cloud · TypeScript`
`{{packageManager}}`	Detected package manager	`npm`
`{{routerType}}`	Detected or prompted	`app`
`{{scripts}}`	Filtered scripts from `package.json`	`npm run dev → next dev`
`{{framework}}`	Detected framework	`nextjs`

Git Integration

What to commit


# Commit these — they're project configuration
CLAUDE.md
.cursorrules
.cursor/rules/
.claude/skills/
.cursor/skills/
.claude/commands/
ai-kit.config.json
ai-kit/guides/

# These are scaffolds with your content — definitely commit
docs/mistakes-log.md
docs/decisions-log.md
docs/time-log.md

What to .gitignore

Nothing AI Kit generates needs to be gitignored. All generated files are project configuration that should be shared with the team.

Recommended workflow

Run ai-kit init on a fresh branch
Review generated files
Commit as: chore: add ai-kit configuration
Team members pull and get the same AI context