# Primer

Auto-generate AI agent instructions from your codebase

## Quick Start

```
# Analyze current project
skillkit primer

# Generate for specific agents
skillkit primer --agent claude,cursor,windsurf

# Generate for all 45 agents
skillkit primer --all-agents

# Preview without writing files
skillkit primer --dry-run
```

## What Primer Detects

### Tech Stack

- **Frameworks**: React, Next.js, Vue, Angular, Svelte, etc.
- **Languages**: TypeScript, JavaScript, Python, Go, Rust, etc.
- **Build Tools**: Vite, Webpack, Turbopack, esbuild
- **Package Managers**: npm, pnpm, yarn, bun

### Project Patterns

- **Architecture**: Monorepo, microservices, serverless
- **Code Style**: Formatting rules, naming conventions
- **Directory Structure**: Feature-based, layer-based, domain-driven
- **Dependencies**: Key libraries and their versions

### Best Practices

- **Testing Setup**: Jest, Vitest, Playwright, Cypress
- **Linting**: ESLint, Prettier, TypeScript strict mode
- **Documentation**: JSDoc, TSDoc, README patterns
- **Git Workflow**: Branch strategy, commit conventions

## Generated Instructions

Primer creates agent-specific instructions for:

### Claude Code

```
.claude/
└── CLAUDE.md          # Full project context
```

### Cursor

```
.cursor/
└── .cursorrules       # IDE-specific rules
```

### GitHub Copilot

```
.github/
└── copilot-instructions.md
```

### All 45 Agents

Each agent gets optimized instructions in their native format.

## Example Output

```
$ skillkit primer

🔍 Analyzing project...

Detected:
  Framework: Next.js 14 (App Router)
  Language: TypeScript (strict mode)
  Styling: Tailwind CSS v3
  Testing: Vitest + Playwright
  Package Manager: pnpm

✅ Generated instructions for:
  - Claude Code (.claude/CLAUDE.md)
  - Cursor (.cursor/.cursorrules)
  - Codex (.codex/instructions.md)
  + 41 more agents

💡 Tip: Run `skillkit sync` to apply changes
```

## Customization

### Configuration File

Create `.skillkit/primer-config.json`:

```
{
  "include": {
    "techStack": true,
    "codeStyle": true,
    "testingPatterns": true,
    "customRules": [
      "Always use async/await over promises",
      "Prefer functional components in React",
      "Use Zod for runtime validation"
    ]
  },
  "exclude": {
    "directories": ["node_modules", "dist", ".next"],
    "patterns": ["*.test.ts", "*.spec.ts"]
  },
  "agents": {
    "priority": ["claude", "cursor", "windsurf"],
    "customize": {
      "claude": {
        "tone": "detailed",
        "examples": true
      },
      "cursor": {
        "tone": "concise",
        "shortcuts": true
      }
    }
  }
}
```

### Template Overrides

Override default templates in `.skillkit/primer-templates/`:

```
.skillkit/primer-templates/
├── claude.template.md
├── cursor.template.md
└── shared/
    ├── header.md
    └── footer.md
```

## Update Strategies

### Incremental Updates

```
# Update only when changes detected
skillkit primer --incremental

# Force regeneration
skillkit primer --force
```

### Git Integration

```
# Auto-generate on git hooks
cat > .git/hooks/post-checkout << 'EOF'
#!/usr/bin/env bash
skillkit primer --incremental
EOF
chmod +x .git/hooks/post-checkout
```

### CI/CD Pipeline

```
# .github/workflows/primer.yml
name: Update Agent Instructions

on:
  push:
    branches: [main]
    paths:
      - 'package.json'
      - 'tsconfig.json'
      - 'src/**'

jobs:
  primer:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npx skillkit primer --all-agents
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "chore: update agent instructions"
```

## Programmatic API

```
import { analyzeProject, generateInstructions } from '@skillkit/core';

// Analyze project
const analysis = await analyzeProject('./my-project');
console.log(analysis.techStack);
// { framework: 'Next.js', language: 'TypeScript', ... }

// Generate instructions
const instructions = await generateInstructions(analysis, {
  agents: ['claude', 'cursor'],
  includeExamples: true,
  tone: 'detailed',
});

// Write to files
for (const [agent, content] of Object.entries(instructions)) {
  await writeAgentFile(agent, content);
}
```

## Best Practices

### When to Run Primer

- **Initial Setup** 
- **Major Changes** 
- **Team Onboarding** 
- **Agent Migration**

### What to Commit

```
# Commit generated instructions
.claude/
.cursor/
.github/copilot-instructions.md

# Don't commit
.skillkit/cache/
.skillkit/primer-temp/
```

### Combining with Skills

Primer generates base instructions. Layer on specific skills:

```
# 1. Generate base instructions
skillkit primer --all-agents

# 2. Install domain-specific skills
skillkit install anthropics/skills --skill pdf,xlsx

# 3. Sync everything
skillkit sync
```

## Comparison

| Method | Setup Time | Accuracy | Maintenance |
| --- | --- | --- | --- |
| **Manual Writing** | Hours | Variable | Manual updates |
| **AI Generation** | Minutes | High | Auto-detect changes |
| **Copy/Paste** | Minutes | Low | Stale quickly |
| **Primer** | Seconds | Very High | Auto-incremental |

## Troubleshooting

### Primer Not Detecting Framework

```
# Specify manually
skillkit primer --framework nextjs --language typescript

# Check detection logs
skillkit primer --verbose
```

### Generated Instructions Too Generic

Customize with `primer-config.json`:

```
{
  "tone": "detailed",
  "includeExamples": true,
  "customRules": [
    "Your specific coding guidelines..."
  ]
}
```

### Instructions Out of Sync

```
# Force regeneration
skillkit primer --force

# Clean cache
rm -rf .skillkit/cache/primer
```

## Next Steps

- Memory System
- Skills
- Translation
- Team Collaboration