# ClaudeKit Documentation (Complete) Generated: 2026-05-19T14:09:06.835Z Total Pages: 306 --- # Changelog Section: changelog Category: N/A URL: https://docs.claudekit.cc/docs/changelog/index # Changelog Track all releases and changes for the ClaudeKit Engineer Kit. --- ## v2.14.0 (Upcoming) ### Highlights - **3-Tier Eval Infrastructure** — Static validation ($0, <5s), E2E via AI CLI (~$3.85/run), LLM judge scoring (~$0.15/run). Run with `bun scripts/eval/run.ts [1|2|3|all]`. Configurable via `CK_EVAL_CMD` env var. - **Cognitive Framing** — All 9 agents enhanced with expert personas (QA Lead, Staff Engineer, Senior SRE, Tech Lead, etc.) for measurably better output. - **Diff-Aware Testing** — Tester agent analyzes git diff, runs only affected tests via 5 mapping strategies. - **`/ck:retro` Skill** — Data-driven sprint retrospectives with git metrics, health indicators, and comparison mode. - **Agent Teams v3.0** — Updated to current Claude Code Agent API. ### New Skills | Skill | Description | |-------|-------------| | `retro` | Data-driven sprint retrospectives | | `stitch` | Google Stitch AI design generation | | `deploy` | Multi-platform deployment with auto-detection | | `llms` | llms.txt generator (llmstxt.org spec) | | `security-scan` | Security vulnerability scanner | | `ship` | Unified ship pipeline (branch → PR) | | `project-organization` | File/directory structure standardizer | ### Improvements - Adversarial code review: scope gate (skip if ≤2 files / ≤30 lines), context anchoring, expanded attack categories - Preview HTML mode: theme toggle, typography floor, improved palette - Frontend-design: taste-skill design intelligence integration - AI Artist: upgraded to Nano Banana 2 as default image generation model - Fix skill: updated references and parallel exploration patterns - Statusline colors: configurable ANSI color control via `.ck.json` - Hook diagnostics: structured logging for hook execution - Manifest: Windsurf global path migration, skills consolidation paths - JSON schema reference in `settings.json` - Attribution API migrated from deprecated `includeCoAuthoredBy` - `ck-debug` / `ck-plan` skill directory renames to avoid built-in `/debug` and `/plan` collisions ### Removals - `ck-help` skill removed (replaced by ClaudeKit Assistant Discord bot) ### Bug Fixes - Eval: type safety fix in `testSkill()` return type, reference validation logic fix - Retro: sentinel file creation, Python test file pattern, `gh issue list` flag - Docs-manager: heading consistency normalization - Project-manager: duplicate role framing removed --- ### CLI v3.36.0 (Upcoming) - **Hook Diagnostics Dashboard** — `ck config` shows hook execution logs, timing, and errors - **Quality Gate Hooks** — Git pre-commit/pre-push hooks enforce lint + test locally - **`ck migrate` UX Overhaul** — Source transparency, unified discovery, path previews - **StatuslineColors Config** — Toggle ANSI color rendering in status line - Migration hardening: TOCTOU race fix, file locks, stale codex config cleanup, Windows compat --- ## v2.13.0 (2026-02-25) ### Highlights - **`ck:` namespace prefix** — All skill names prefixed with `ck:` to avoid collisions with Claude Code built-ins - **`argument-hint` field** — Added to all skills for improved discoverability - Various namespace cleanup and cross-reference fixes - `chrome-devtools` evaluate fix --- ## v2.12.0 (2026-02-05) ### Highlights - **Agent Teams v2.1.0** — Complete rewrite as CK-native imperative execution engine. Templates auto-execute. Event-driven hooks (TaskCompleted, TeammateIdle) for monitoring. Agent memory persistence. - **Portable manifest** — Codex AGENTS.md to `.codex/agents/` path migration support - **`/ck:plan red-team`** — Adversarial plan review command with hostile reviewer lenses - **Command-to-Skill migrations** — `bootstrap`, `plan` modes consolidated into skills ### New Skills | Skill | Description | |-------|-------------| | `team` | Agent Teams orchestration (v2.1.0) | | `plan` | Consolidated planning skill (replaces `/ck:plan --fast`, `/ck:plan --hard`, `/ck:plan --parallel`, `/ck:plan --two`) | | `bootstrap` | Project scaffolding skill (was command) | | `test` | Comprehensive testing skill | | `project-management` | Task tracking and session bridging | | `mintlify` | Mintlify docs site builder (v2.0.0) | ### New Commands - `/ck:plan red-team` — Adversarial plan review with 4 hostile lenses ### New Agents - **Code Simplifier** — Autonomous code refinement agent ### Improvements - Enhanced `skill-creator` with Skillmark benchmark support - Native Task orchestration for `/ck:fix`, `/ck:code-review`, `/ck:scout`, `/ck:debug` skills - `/ck:preview` contextual path resolution and responsive Mermaid scaling - Chrome DevTools OS-based headless detection and interactive OAuth login - Team coordination rules decoupled from default orchestration --- ## v2.11.0 — v2.11.3 (2026-02-20 — 2026-02-21) ### v2.11.3 (Hotfixes) - Discord 25-field embed limit guard - Double-emoji fix in release notification headers - Empty-changelog guard for Discord notifications - Double error log timeout prevention ### v2.11.2 (Hotfixes) - Scout-block: broad glob pattern detection (`**/*.ext`) - Scout-block: context-aware path extraction with heredoc detection - Scout-block: compound command and allowlist edge cases - Scout-block: absolute/relative path normalization - Hooks: absolute paths in `buildRulesSection` (prevents wrong `plans/` directory) - Windows: reduced terminal freeze from excessive process spawning - Session-init: reduced command failures ### v2.11.1 - Added `hotfix:` commit type for distinct release note visibility in CHANGELOG and GitHub releases ### v2.11.0 - **Always-on diagnostics logging** — Crash wrappers on all hooks for automatic error capture --- ## v2.10.0 (2026-02-05) ### Features - **Focused Reader 2.0** — Redesigned markdown-novel-viewer - **Plan validation propagation** — Auto-propagate validation decisions to phase files - **Visual generation modes** — `/ck:preview --explain`, `--slides`, `--diagram`, `--ascii` ### Improvements - `cook-after-plan-reminder` hook for plan-to-implementation flow - `code-review` skill with edge case scouting and token efficiency - `skill-creator` skill with rules and subagent awareness - Language-aware file naming guidance hook - Monorepo-aware worktree paths (`internal worktrees/`) ### Bug Fixes - `/ck:docs init` stall after Phase 1 - Empty local hooks config inheritance - Preview ASCII diagram alignment and unicode handling --- ## Earlier Releases For release notes prior to v2.10.0, see the [GitHub Releases page](https://github.com/claudekit/claudekit-engineer/releases). --- ## Release Channels | Channel | Branch | npm Tag | Description | |---------|--------|---------|-------------| | **Stable** | `main` | `latest` | Production-ready, fully tested | | **Beta** | `dev` | `beta` | Pre-release features, may have rough edges | ```bash # Stable (default) ck update # Beta ck update --beta ``` --- ## Versioning ClaudeKit Engineer follows [Semantic Versioning](https://semver.org/): - **Major** (X.0.0): Breaking changes requiring migration - **Minor** (0.X.0): New features, backward-compatible - **Patch** (0.0.X): Bug fixes and hotfixes Releases are automated via semantic-release on merge to `main`. --- # ClaudeKit CLI Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/index # ClaudeKit CLI > Fast, secure command-line tool for bootstrapping and managing ClaudeKit-powered projects from private GitHub releases. ClaudeKit CLI (`ck`) helps you create and manage ClaudeKit-powered projects. Built with Bun and TypeScript, it provides a beautiful interface for project setup, updates, and maintenance. ## Key Features - Multi-tier GitHub authentication with secure credential storage - Streaming downloads with progress tracking and platform optimization - Smart file merging with conflict detection - Automatic skill directory migration with parallel processing - Automatic system dependency installation - Smart update notifications with 7-day cache - Beautiful CLI interface with interactive prompts ## Quick Install Install the CLI globally using your preferred package manager: ```bash # npm (recommended) npm install -g claudekit-cli # bun bun add -g claudekit-cli # pnpm pnpm add -g claudekit-cli # yarn yarn global add claudekit-cli ``` For detailed installation instructions including prerequisites and verification steps, see [Installation](/docs/cli/installation). ## Verify Installation ```bash ck --version ``` You'll see output like: ``` CLI Version: 3.10.1 Local Kit Version: 1.16.0 (ClaudeKit Engineer) ``` ## Available Commands | Command | Description | |---------|-------------| | [`ck new`](/docs/cli/new) | Create a new ClaudeKit project | | [`ck init`](/docs/cli/init) | Initialize or update ClaudeKit in existing project | | [`ck doctor`](/docs/cli/doctor) | Run health checks and diagnostics | | [`ck versions`](/docs/cli/versions) | List available kit versions | | [`ck update`](/docs/cli/update) | Update CLI to latest version | | [`ck uninstall`](/docs/cli/uninstall) | Remove ClaudeKit installation | | [`ck backups`](/docs/cli/backups) | Manage recovery backups for destructive operations | ## Quick Start ### Create a New Project ```bash # Interactive mode (recommended) ck new # With options ck new --kit engineer --dir my-project # Include beta versions in selection ck new --beta # Auto-install skill dependencies ck new --install-skills ``` [Full documentation](/docs/cli/new) ### Initialize Existing Project ```bash # Add ClaudeKit to your existing project cd my-existing-project ck init # Non-interactive mode with defaults ck init --yes # Global installation (user-level config) ck init --global ``` [Full documentation](/docs/cli/init) ### Health Check ```bash # Run diagnostics ck doctor # Auto-fix issues ck doctor --fix # Generate shareable report ck doctor --report ``` [Full documentation](/docs/cli/doctor) ## Prerequisites Before using ClaudeKit CLI, you need: 1. **Purchase a ClaudeKit Starter Kit** from [ClaudeKit.cc](https://claudekit.cc) 2. **Get Repository Access** - You will receive access to private GitHub repositories after purchase 3. **Install GitHub CLI** and authenticate with `gh auth login` Without a purchased kit and repository access, the CLI cannot download project templates. ## Authentication ClaudeKit CLI uses a multi-tier authentication system: 1. GitHub CLI (`gh auth token`) 2. Environment Variables (`GITHUB_TOKEN`) 3. Config File (`~/.claudekit/config.json`) 4. OS Keychain (secure storage) 5. User Prompt (with save option) For setup instructions, see [Installation - Authentication](/docs/cli/installation#authentication). ## Kit Selection When creating a new project, choose from available kits: | Kit | Best For | Status | |-----|----------|--------| | **Engineer** | Software development, automation, testing | Available | | **Marketing** | Content creation, campaigns, analytics | Coming Soon | ## Global vs Local Installation ClaudeKit supports two installation modes: - **Local** (default): Install to `.claude/` in your project directory - **Global**: Install to the Claude user directory for user-level configuration Global kit location: | Platform | Path | |----------|------| | macOS/Linux | `~/.claude/` | | Windows | `%USERPROFILE%\.claude\` | Use `ck init --global` for global installation, or `ck init` for local (project-specific) installation. ## Configuration Configuration is stored in `~/.claudekit/config.json`: ```json { "github": { "token": "stored_in_keychain" }, "defaults": { "kit": "engineer", "dir": "." } } ``` For full configuration reference, see [Configuration](/docs/cli/configuration). ## Next Steps - [Installation](/docs/cli/installation) - Detailed setup guide - [ck new](/docs/cli/new) - Create your first project - [ck init](/docs/cli/init) - Add to existing project - [ck doctor](/docs/cli/doctor) - Troubleshooting - [Configuration](/docs/cli/configuration) - Customize your settings --- # Installation Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/installation # Installation > Install ClaudeKit CLI globally and set up GitHub authentication to start creating projects. ## Prerequisites Before installing ClaudeKit CLI, ensure you have: ### 1. Node.js ClaudeKit CLI requires Node.js 18.0.0 or higher. **Check your version:** ```bash node --version ``` **Install Node.js:** - **Windows**: [Download from nodejs.org](https://nodejs.org/) - **macOS**: `brew install node` - **Linux**: `sudo apt install nodejs npm` (Ubuntu/Debian) or check your distro's package manager ### 2. Git Required for repository operations. **Check your version:** ```bash git --version ``` **Install Git:** - **Windows**: [Download from git-scm.com](https://git-scm.com/) - **macOS**: `brew install git` (or use Xcode Command Line Tools) - **Linux**: `sudo apt install git` (Ubuntu/Debian) ### 3. Purchase ClaudeKit You must purchase a ClaudeKit Starter Kit from [ClaudeKit.cc](https://claudekit.cc) to access the private GitHub repository containing kit templates. After purchase, you'll receive: - Access to the private GitHub repository - License key (if applicable) - Setup instructions ## Install ClaudeKit CLI Install the CLI globally using your preferred package manager: ### npm (Recommended) ```bash npm install -g claudekit-cli ``` ### Bun ```bash bun add -g claudekit-cli ``` ### pnpm ```bash pnpm add -g claudekit-cli ``` ### Yarn ```bash yarn global add claudekit-cli ``` ## Verify Installation After installation, verify the CLI is working: ```bash ck --version ``` Expected output: ``` CLI Version: 3.10.1 ``` If you see a "command not found" error, ensure your package manager's global bin directory is in your PATH: - **npm**: `npm config get prefix` (should be in PATH) - **bun**: `~/.bun/bin` (add to PATH if needed) - **pnpm**: `pnpm config get global-bin-dir` (add to PATH if needed) - **yarn**: `yarn global bin` (add to PATH if needed) ## Authentication Setup {#authentication} ClaudeKit CLI requires GitHub authentication to download releases from private repositories. ### Install GitHub CLI **Step 1: Install GitHub CLI** - **Windows**: `winget install GitHub.cli` - **macOS**: `brew install gh` - **Linux**: `sudo apt install gh` (Ubuntu/Debian) For other Linux distributions, see [GitHub CLI installation guide](https://github.com/cli/cli#installation). **Step 2: Verify installation** ```bash gh --version ``` ### Authenticate with GitHub CLI **Run the authentication command:** ```bash gh auth login ``` **Follow the prompts:** 1. Select **GitHub.com** 2. Select **HTTPS** (or SSH if you prefer) 3. Authenticate Git? → **Yes** 4. Select **Login with a web browser** (recommended) 5. Copy the one-time code shown 6. Press Enter to open browser 7. Paste the code in the browser 8. Authorize GitHub CLI **Important**: Use "Login with a web browser" option. Do NOT use "Paste an authentication token" as PAT authentication is no longer supported for accessing private repositories. ### Verify Authentication Check your authentication status: ```bash gh auth status ``` Expected output: ``` github.com ✓ Logged in to github.com as your-username (oauth_token) ✓ Git operations for github.com configured to use https protocol. ✓ Token: ******************* ``` ### Accept Repository Invitation After purchasing ClaudeKit, you'll receive an email invitation to access the private GitHub repository. 1. **Check your email** for the GitHub invitation 2. **Accept the invitation** by clicking the link 3. **Wait 2-5 minutes** for permissions to propagate Without accepting the invitation, you'll get "Access denied" errors when running `ck new` or `ck init`. ## Troubleshooting ### "Access denied" Error **Symptoms:** ``` Access denied to repository ``` **Solutions:** 1. Run `ck doctor` to diagnose issues 2. Ensure you've accepted the GitHub repository invitation 3. Re-run `gh auth login` and select "Login with a web browser" 4. Wait 2-5 minutes after accepting invitation for permissions to propagate ### "GitHub CLI not authenticated" Error **Symptoms:** ``` GitHub CLI not authenticated ``` **Solutions:** ```bash # Re-authenticate with web browser method gh auth login ``` Select "Login with a web browser" (NOT "Paste token"). ### Permission Denied During Installation **Symptoms:** ``` EACCES: permission denied ``` **Solutions:** **Option 1: Use sudo (Linux/macOS)** ```bash sudo npm install -g claudekit-cli ``` **Option 2: Fix npm permissions (Recommended)** Follow [npm's guide to fix permissions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). ### Command Not Found **Symptoms:** ```bash ck: command not found ``` **Solutions:** Add your package manager's global bin directory to PATH: **npm:** ```bash # Find npm prefix npm config get prefix # Add to PATH (add to ~/.bashrc or ~/.zshrc) export PATH="$(npm config get prefix)/bin:$PATH" ``` **Bun:** ```bash # Add to ~/.bashrc or ~/.zshrc export PATH="$HOME/.bun/bin:$PATH" ``` **pnpm:** ```bash # Add to ~/.bashrc or ~/.zshrc export PATH="$(pnpm config get global-bin-dir):$PATH" ``` After editing shell config, restart your terminal or run: ```bash source ~/.bashrc # or ~/.zshrc ``` ## Platform-Specific Notes ### Windows - Use PowerShell or Windows Terminal (not Command Prompt) - Path separators use backslash (`\`) but CLI handles this automatically - Some commands may require administrator privileges ### macOS - GitHub CLI can be installed via Homebrew - Global npm packages install to `/usr/local/bin` by default - Requires Xcode Command Line Tools for Git (install via `xcode-select --install`) ### Linux - Package names vary by distribution (use your distro's package manager) - Global npm packages may require sudo or npm permission fixes - WSL (Windows Subsystem for Linux) fully supported ## Next Steps Now that ClaudeKit CLI is installed and authenticated: 1. **Create a new project**: [`ck new`](/docs/cli/new) 2. **Run health check**: [`ck doctor`](/docs/cli/doctor) 3. **Browse available versions**: [`ck versions`](/docs/cli/versions) 4. **Configure defaults**: [Configuration](/docs/cli/configuration) ## Related Commands - [`ck doctor`](/docs/cli/doctor) - Diagnose installation issues - [`ck update`](/docs/cli/update) - Update CLI to latest version - [`ck uninstall`](/docs/cli/uninstall) - Remove ClaudeKit --- # ck new Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/new # ck new > Create a new ClaudeKit project from scratch with interactive prompts and automatic setup. ## Quick Start ```bash # Interactive mode (recommended for beginners) ck new # Specify kit and directory ck new --kit engineer --dir my-project # With beta versions and skill dependencies ck new --beta --install-skills ``` ## What It Does The `ck new` command: 1. Prompts you to select a ClaudeKit kit (Engineer or Marketing) 2. Let you choose a target directory for the project 3. Fetches the latest (or selected) release from GitHub 4. Downloads and extracts project files 5. Optionally installs skill dependencies 6. Creates a ready-to-use ClaudeKit project ## Syntax ```bash ck new [OPTIONS] ``` ### Options | Flag | Description | Default | |------|-------------|---------| | `--kit ` | Kit to install (`engineer` or `marketing`) | Interactive prompt | | `--dir ` | Target directory for project | Interactive prompt | | `--release ` | Specific release version to install | Latest stable | | `--beta` | Include beta/prerelease versions in selection | `false` | | `--refresh` | Force refresh release cache | `false` | | `--force` | Overwrite files in non-empty directory | `false` | | `--exclude ` | Exclude files matching glob pattern (repeatable) | None | | `--prefix` | Move commands to `/ck:` namespace | `false` | | `--opencode` | Install OpenCode package globally | `false` | | `--gemini` | Install Gemini CLI and set up MCP integration | `false` | | `--install-skills` | Auto-install skill dependencies | `false` | | `--docs-dir ` | Custom name for docs folder | `docs` | | `--plans-dir ` | Custom name for plans folder | `plans` | | `--verbose` | Enable verbose logging | `false` | | `--log-file ` | Save logs to file | None | ## Examples ### Basic Project Creation Create a new Engineer kit project in the current directory: ```bash ck new --kit engineer ``` **Expected output:** ``` 🚀 ClaudeKit - Create New Project Selected kit: ClaudeKit Engineer Target directory: /Users/you/my-project ✓ Repository access verified ✓ Found: v1.16.0 Downloading ████████████████████████████████████████ 100% | 2.5 MB Installing ✓ Files merged successfully ✨ Project created successfully at /Users/you/my-project ``` ### Specific Directory Create project in a custom directory: ```bash ck new --kit engineer --dir ~/projects/my-awesome-app ``` ### Include Beta Versions Show and select from beta/prerelease versions: ```bash ck new --beta ``` This includes versions tagged as prereleases in the version selection menu. ### Install with Dependencies Create project and auto-install all skill dependencies: ```bash ck new --kit engineer --install-skills ``` This installs: - Python packages (defined in skill requirements.txt files) - System tools (FFmpeg, ImageMagick via package managers) - Node.js packages (skill dependencies) ### Non-Interactive Mode For CI/CD or scripting (requires all necessary flags): ```bash ck new --kit engineer --dir ./my-project --release v1.16.0 --force ``` **Note**: Without `--release`, non-interactive mode will fail. Interactive version selection requires a TTY. ### Exclude Files Skip specific files or patterns during installation: ```bash ck new --exclude "*.log" --exclude "temp/**" --exclude "node_modules/**" ``` **Glob patterns supported:** - `*` - Any characters - `**` - Recursive directories - `?` - Single character - `[abc]` - Character set - `{a,b}` - Alternatives ### Command Prefix Move ClaudeKit commands to `/ck:` namespace to avoid conflicts: ```bash ck new --prefix ``` This transforms: - `/plan` → `/ck:plan` - `/review` → `/ck:review` - `/debug` → `/ck:debug` Useful when you have custom commands that conflict with ClaudeKit defaults. ### Custom Folder Names Use custom names for docs and plans directories: ```bash ck new --docs-dir documentation --plans-dir planning ``` This creates: - `documentation/` instead of `docs/` - `planning/` instead of `plans/` And updates all references in workflow files automatically. ## Common Patterns ### Full-Featured Setup Create a complete project with all features: ```bash ck new \ --kit engineer \ --dir ~/projects/new-app \ --install-skills \ --gemini \ --prefix ``` ### Beta Testing Try the latest prerelease features: ```bash ck new --beta --kit engineer ``` ### Quick Prototype Minimal setup for quick testing: ```bash ck new --kit engineer --dir ./test-project ``` ### Production Setup Stable version with skill dependencies for production: ```bash ck new \ --kit engineer \ --release v1.16.0 \ --install-skills \ --dir ~/production-app ``` ## Troubleshooting ### "Directory is not empty" **Problem:** Target directory contains files. **Solution:** Use `--force` to overwrite (interactive mode will prompt): ```bash ck new --force --dir ./existing-project ``` Or choose a different directory: ```bash ck new --dir ./new-project ``` ### "Access denied to repository" **Problem:** GitHub authentication failed or repository access not granted. **Solution:** 1. Run health check: ```bash ck doctor ``` 2. Re-authenticate: ```bash gh auth login ``` Select "Login with a web browser" option. 3. Accept repository invitation (check email) 4. Wait 2-5 minutes for permissions to propagate ### "Interactive version selection unavailable in non-interactive mode" **Problem:** Running in CI/CD without TTY and no `--release` flag. **Solution:** Specify version explicitly: ```bash ck new --kit engineer --release v1.16.0 ``` Or set `CI=false` to enable interactive mode (if TTY available). ### Platform-Specific Issues **Windows:** - Use PowerShell or Windows Terminal - Paths with spaces: Use quotes `--dir "C:\My Projects\app"` - Some antivirus software may flag downloads (whitelist `ck` command) **macOS:** - Requires Xcode Command Line Tools for git - Use Homebrew for system dependencies: `brew install gh` **Linux:** - Package manager varies by distro (apt, yum, pacman) - May need sudo for global npm installs - WSL fully supported ## What Gets Created After `ck new` completes successfully, your project structure looks like: ``` my-project/ ├── .claude/ │ ├── agents/ # AI agent definitions │ ├── commands/ # Slash commands │ ├── skills/ # Reusable skills │ ├── workflows/ # Workflow definitions │ ├── hooks/ # Lifecycle hooks │ ├── settings.json # Project settings │ └── metadata.json # Installation metadata ├── docs/ # Documentation ├── plans/ # Planning directory ├── CLAUDE.md # Claude Code instructions ├── .env.example # Environment variables template └── README.md # Project readme ``` ## Next Steps After creating a project: 1. **Navigate to project:** ```bash cd my-project ``` 2. **Review configuration:** ```bash cat .claude/settings.json ``` 3. **Set up environment variables:** ```bash cp .env.example .env # Edit .env with your API keys ``` 4. **Start coding with Claude Code** - Open project in Claude Code and start using commands 5. **Update later:** ```bash ck init # Update to latest version ``` ## Related Commands - [`ck init`](/docs/cli/init) - Update existing project - [`ck versions`](/docs/cli/versions) - Browse available versions - [`ck doctor`](/docs/cli/doctor) - Troubleshoot issues - [Configuration](/docs/cli/configuration) - Customize defaults --- # ck init Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/init # ck init > Initialize or update ClaudeKit in existing projects with smart file merging and automatic customization preservation. ## Quick Start ```bash # Interactive mode (recommended) ck init # Non-interactive with sensible defaults ck init --yes # Global installation (user-level config) ck init --global # Fresh installation (creates a recovery backup, then resets CK-managed files) ck init --fresh ``` **Important**: Run `ck init` from your project's root directory. ## What Happens The `ck init` command: 1. Detects existing ClaudeKit installation (local or global) 2. Prompts for kit and version selection 3. Downloads selected release 4. Merges new files while preserving your customizations 5. Migrates skills directory if structure changed 6. Updates installation metadata 7. Optionally installs skill dependencies ## Syntax ```bash ck init [OPTIONS] ``` ### Options | Flag | Description | Default | |------|-------------|---------| | `--kit ` | Kit to install (`engineer` or `marketing`) | Interactive prompt | | `--dir ` | Target directory | Current directory | | `--release ` | Specific release version | Latest stable | | `--beta` | Include beta versions in selection | `false` | | `--refresh` | Force cache refresh for releases | `false` | | `--global` / `-g` | Install to user directory (`~/.claude/`) | `false` (local) | | `--yes` / `-y` | Non-interactive mode with defaults | `false` | | `--fresh` | Create a recovery backup, remove CK-managed files, then reinstall | `false` | | `--exclude ` | Exclude files matching pattern (repeatable) | None | | `--only ` | Only update specific directories (repeatable) | All | | `--prefix` | Apply `/ck:` namespace to commands | `false` | | `--install-skills` | Auto-install skill dependencies | `false` | | `--skip-setup` | Skip API key setup wizard | `false` | | `--force-overwrite-settings` | Completely overwrite settings.json | `false` | | `--docs-dir ` | Custom docs directory name | `docs` | | `--plans-dir ` | Custom plans directory name | `plans` | | `--dry-run` | Preview changes without applying | `false` | | `--force-overwrite` | Overwrite modified files (use with caution) | `false` | | `--verbose` | Enable detailed logging | `false` | ## Examples ### Update Existing Project Update your project to latest version: ```bash cd my-project ck init ``` **Expected output:** ``` 🔧 ClaudeKit - Initialize/Update Project Selected kit: ClaudeKit Engineer Target directory: /Users/you/my-project ✓ Repository access verified ✓ Found: v1.17.0 Downloading ████████████████████████████████████████ 100% | 2.5 MB Scanning for custom .claude files... ✓ Protected 3 custom .claude file(s) Installing ✓ Files merged successfully ✓ Tracked 245 files ✨ Project initialized successfully ``` ### Non-Interactive Mode Update with defaults (use latest version, skip all prompts): ```bash ck init --yes ``` **Default behavior with `--yes`:** | Prompt | Default Value | |--------|---------------| | Kit selection | `engineer` (first available) | | Target directory | `.` (current directory) | | Version | Latest stable release | | Gemini setup | Skip | | Optional features | Skip | ### Global Installation Install ClaudeKit at user level (`~/.claude/`): ```bash ck init --global ``` **Platform-specific paths:** - **macOS/Linux**: `~/.claude/` - **Windows**: `%USERPROFILE%\.claude\` Global mode is useful for: - Sharing configuration across projects - Using ClaudeKit commands everywhere - Centralized skill management ### Fresh Installation Create a recovery backup, remove existing ClaudeKit-managed files, and reinstall: ```bash ck init --fresh ``` ClaudeKit first writes a scoped recovery backup under `~/.claudekit/backups/`, then removes the CK-managed files targeted by the fresh install. To inspect or restore those backups later: ```bash ck backups list ck backups restore ``` Protected files are still preserved: - `.env`, `.env.local` - `*.key`, `*.pem`, `*.p12` - `settings.json`, `CLAUDE.md` ### Selective Update Only update specific directories: ```bash ck init --only commands --only workflows ``` Available directories: - `commands` - `agents` - `skills` - `workflows` - `hooks` ### Dry Run Preview what will change without applying: ```bash ck init --dry-run ``` Shows: - Files that will be added - Files that will be updated - Files that will be preserved - Ownership status of each file ### Combined Flags Common combinations: ```bash # Global + non-interactive ck init -g -y # Beta version + skill installation ck init --beta --install-skills # Fresh install + specific version ck init --fresh --release v1.16.0 --yes ``` ## Local vs Global Mode ### Local Mode (Default) Install to `.claude/` in project directory: ```bash cd my-project ck init ``` **Structure:** ``` my-project/ ├── .claude/ │ ├── agents/ │ ├── commands/ │ ├── skills/ │ └── ... └── ... ``` **Use when:** - Working on a single project - Need project-specific configuration - Collaborating with team (commit to git) ### Global Mode Install to `~/.claude/` (user directory): ```bash ck init --global ``` **Structure:** ``` ~/.claude/ ├── agents/ ├── commands/ ├── skills/ └── ... ``` **Use when:** - Using ClaudeKit across multiple projects - Want centralized configuration - Need globally available skills **Note**: Local installations take precedence over global if both exist. ## Common Patterns ### Update to Latest Beta Get latest prerelease features: ```bash ck init --beta ``` ### Specific Version Pin to known stable version: ```bash ck init --release v1.16.0 ``` ### Commands-Only Update Refresh commands while keeping other customizations: ```bash ck init --only commands ``` ### Full Reinstall Nuclear option - start fresh: ```bash ck init --fresh --yes --install-skills ``` ### CI/CD Update Automated update in CI pipelines: ```bash ck init --yes --release v1.16.0 --skip-setup ``` ## Customization Preservation `ck init` intelligently preserves customizations across updates. ### Protected by Default Always preserved during updates: - `.env`, `.env.local`, `.env.*.local` - `*.key`, `*.pem`, `*.p12`, `*.pfx` - `settings.json`, `settings.local.json` - `CLAUDE.md` (in global mode) - Files in `node_modules/`, `.git/`, `dist/`, `build/` ### Custom File Detection Automatically detected and preserved: - Custom slash commands (not in release manifest) - Personal workflows - User-created skills - Modified ClaudeKit files (checksum-based detection) ### Ownership Tracking Files are tracked with ownership: - **ck-owned**: Original ClaudeKit files, unmodified (can be updated) - **ck-modified**: ClaudeKit files you've edited (preserved by default) - **user-created**: Your custom files (always preserved) ### Skill Migration Automatically migrates when directory structure changes: **Example:** ``` Before (flat): .claude/skills/ ├── gemini-vision/ ├── postgresql-psql/ └── cloudflare-dns/ After (categorized): .claude/skills/ ├── ai-multimodal/ │ └── gemini-vision/ ├── databases/ │ └── postgresql-psql/ └── devops/ └── cloudflare-dns/ ``` Customizations in any skills are detected and preserved during migration. ## Troubleshooting ### "Directory does not exist" **Issue:** Target directory not found. **Solution:** Use `ck new` to create new project: ```bash ck new --kit engineer --dir ./my-project ``` Or create directory first: ```bash mkdir my-project && cd my-project ck init ``` ### "Local .claude/settings.json detected" (Global Mode) **Issue:** Local installation exists when trying to install globally. **Solution:** Choose one of the prompted options: 1. **Remove local** - Delete `.claude/` and use global 2. **Keep both** - Local installation will take precedence 3. **Cancel** - Abort installation Or use flag to force: ```bash # Remove local before global install rm -rf .claude ck init --global ``` ## Next Steps After initialization: 1. **Verify installation:** ```bash ck --version ``` 2. **Run health check:** ```bash ck doctor ``` 3. **Review updated files:** ```bash ls -la .claude/ ``` 4. **Test a command:** Open your project in Claude Code and try a slash command like `/ck:plan`. 5. **Install skill dependencies (if not done):** ```bash ck init --install-skills ``` ## Related Commands - [`ck new`](/docs/cli/new) - Create new project - [`ck doctor`](/docs/cli/doctor) - Diagnose issues - [`ck versions`](/docs/cli/versions) - Browse versions - [`ck uninstall`](/docs/cli/uninstall) - Remove installation - [Configuration](/docs/cli/configuration) - Configure defaults --- # ck doctor Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/doctor # ck doctor > Run comprehensive health checks, diagnose issues, and auto-fix common problems with ClaudeKit installations. ## Quick Start ```bash # Full health check (interactive) ck doctor # Auto-fix all fixable issues ck doctor --fix # Generate shareable diagnostic report ck doctor --report # CI mode (JSON output, exit code on failure) ck doctor --check-only --json ``` ## What It Does The `ck doctor` command performs comprehensive health checks across: 1. **System**: Node.js, npm, Python, pip, git, gh CLI 2. **ClaudeKit**: Global/local installation, versions, metadata 3. **Auth**: GitHub CLI authentication, repository access 4. **Project**: package.json, node_modules, lock files 5. **Skills**: Dynamic skill dependency resolution After running checks, it can: - Display results with color-coded status - Auto-fix fixable issues - Generate shareable diagnostic reports - Output machine-readable JSON for CI/CD ## Syntax ```bash ck doctor [OPTIONS] ``` ### Options | Flag | Description | Default | |------|-------------|---------| | `--fix` | Auto-fix all fixable issues | `false` | | `--report` | Generate shareable diagnostic report (prompts for gist upload) | `false` | | `--check-only` | CI mode: no prompts, exit 1 on failures | `false` | | `--json` | Output results as JSON | `false` | | `--full` | Run extended checks (slower but more thorough) | `false` | | `--verbose` | Enable verbose logging | `false` | ## Health Checks Performed ### System Checks Verifies development environment dependencies: - **Node.js**: Version 18.0.0+ - **npm**: Installed and working - **Python**: Version 3.8+ (for skill dependencies) - **pip**: Python package manager - **git**: Version control - **gh**: GitHub CLI for authentication - **Claude CLI**: Claude Code CLI (if installed) ### ClaudeKit Checks Validates ClaudeKit installation: - **Global installation**: `~/.claude/` exists and valid - **Local installation**: `./.claude/` exists and valid - **Metadata**: Installation metadata is valid - **Version**: Installed version is current - **Skills**: Skills directory structure is correct ### Auth Checks Validates GitHub authentication: - **GitHub CLI auth**: `gh auth status` passes - **Token validity**: Token has required scopes - **Repository access**: Can access ClaudeKit repositories - **Permissions**: Read access to releases ### Project Checks Validates project configuration (if in project directory): - **package.json**: Exists and valid - **node_modules**: Installed and not corrupted - **Lock files**: Present and consistent - **Dependencies**: All required packages installed ### Module Checks Dynamically resolves skill dependencies: - **Python packages**: From `requirements.txt` in skills - **System tools**: FFmpeg, ImageMagick, etc. - **Node packages**: Skill-specific npm dependencies ## Examples ### Basic Health Check Run all checks interactively: ```bash ck doctor ``` **Example output:** ``` ClaudeKit Health Check System Checks: ✓ Node.js (v20.11.0) ✓ npm (v10.2.4) ✓ Python (v3.11.5) ✓ pip (v23.3.1) ✓ git (v2.42.0) ✓ GitHub CLI (v2.40.1) ⚠ Claude CLI (not installed) ClaudeKit Checks: ✓ Local installation (v1.16.0) ✓ Global installation (v1.16.0) ✓ Metadata valid Auth Checks: ✓ GitHub CLI authenticated ✓ Repository access granted Project Checks: ✓ package.json valid ✓ node_modules installed ✓ Lock file present Module Checks: ✓ All skill dependencies installed Summary: 17 passed, 1 warning, 0 failed All checks passed! ``` ### Auto-Fix Issues Automatically fix all fixable issues: ```bash ck doctor --fix ``` **What gets fixed:** - Missing npm dependencies → `npm install` - Missing gh auth → `gh auth login` prompt - Corrupted node_modules → Reinstall - Missing global install → `ck init --global` prompt - Missing skill deps → Install in skill directory **Example output:** ``` ClaudeKit Health Check ...checks run... Auto-fixing issues... ✓ Installed missing dependencies (npm install) ✓ Fixed GitHub CLI authentication ✓ Installed skill dependencies (3 packages) Healing Summary: 3 issues fixed 0 issues failed 2 issues not fixable All fixable issues resolved! ``` ### Generate Diagnostic Report Create a shareable text report for troubleshooting: ```bash ck doctor --report ``` **What it does:** 1. Runs all checks 2. Generates detailed text report 3. Prompts to upload to GitHub Gist (public) 4. Prints gist URL for sharing **Example output:** ``` ClaudeKit Health Check - Diagnostic Report System Information: OS: macOS 14.2.1 (darwin) Node.js: v20.11.0 npm: v10.2.4 ... Check Results: [PASS] Node.js version [FAIL] GitHub CLI authentication ... Detailed Errors: 1. GitHub CLI not authenticated Fix: Run 'gh auth login' ... --- Upload report to GitHub Gist? (y/n) Report uploaded: https://gist.github.com/abc123 ``` Share the gist URL when asking for support. ### CI/CD Mode Run in CI pipeline with JSON output and exit codes: ```bash ck doctor --check-only --json ``` **Exit codes:** - `0`: All checks pass - `1`: One or more checks failed **JSON output example:** ```json { "summary": { "passed": 15, "failed": 2, "warnings": 1 }, "checks": [ { "category": "System", "name": "Node.js", "status": "pass", "message": "v20.11.0" }, { "category": "Auth", "name": "GitHub CLI", "status": "fail", "message": "Not authenticated", "autoFixable": true, "fix": "gh auth login" } ] } ``` ### Full Extended Checks Run thorough checks (slower): ```bash ck doctor --full ``` Includes: - Network connectivity tests - Deeper dependency verification - Extended permission checks - Performance benchmarks ## Auto-Fix Capabilities Issues that can be automatically fixed: | Issue | Fix Action | |-------|------------| | Missing npm dependencies | `npm install` | | Missing gh authentication | Prompt `gh auth login` | | Corrupted node_modules | `rm -rf node_modules && npm install` | | Missing global install | Prompt `ck init --global` | | Missing skill dependencies | Install packages in skill directories | | Invalid cache | Clear cache and refresh | Issues that require manual intervention: | Issue | Manual Fix | |-------|------------| | Node.js version too old | Update Node.js from nodejs.org | | Python not installed | Install Python from python.org | | Repository access denied | Accept GitHub invitation email | | Incompatible OS | Use supported OS (Windows/macOS/Linux) | ## Interpreting Results ### Status Icons - `✓` Green checkmark: Passed - `⚠` Yellow warning: Warning (non-critical) - `✗` Red X: Failed (critical) ### Common Issues #### "GitHub CLI not authenticated" **Status:** `✗ Failed` **Fix:** ```bash gh auth login ``` Select "Login with a web browser" option. #### "Repository access denied" **Status:** `✗ Failed` **Causes:** 1. Haven't accepted GitHub invitation 2. Permissions haven't propagated (wait 2-5 minutes) 3. Token expired (re-run `gh auth login`) **Fix:** 1. Check email for GitHub invitation 2. Accept invitation 3. Wait 2-5 minutes 4. Re-run `ck doctor` #### "Node.js version too old" **Status:** `✗ Failed` **Fix:** Update Node.js to 18.0.0 or higher: - **Windows**: Download from [nodejs.org](https://nodejs.org/) - **macOS**: `brew install node` - **Linux**: Use your package manager or [nvm](https://github.com/nvm-sh/nvm) #### "Claude CLI not installed" **Status:** `⚠ Warning` **Fix (optional):** ```bash npm install -g @claude/cli ``` Not required for ClaudeKit, but useful for Claude Code integration. ## Common Patterns ### Troubleshooting Workflow Step-by-step debugging: ```bash # 1. Run diagnostics ck doctor # 2. Auto-fix what we can ck doctor --fix # 3. Re-check ck doctor # 4. If still failing, generate report ck doctor --report ``` ### Pre-Installation Check Before installing ClaudeKit: ```bash ck doctor --full ``` Ensures your system is ready. ### CI Pipeline Integration Add to your CI workflow: ```yaml # .github/workflows/test.yml - name: Health Check run: ck doctor --check-only --json > health-report.json continue-on-error: true - name: Upload Report uses: actions/upload-artifact@v3 with: name: health-report path: health-report.json ``` ### Regular Maintenance Periodic health checks: ```bash # Weekly cron job 0 9 * * 1 ck doctor --fix --json > ~/claudekit-health.log ``` ## Platform-Specific Notes ### Windows - Use PowerShell or Windows Terminal - Some checks may require administrator privileges - Path separators handled automatically ### macOS - Requires Xcode Command Line Tools for git - Homebrew recommended for installing dependencies - Native unzip used for performance ### Linux - Package manager varies by distro (apt, yum, pacman) - WSL fully supported - May need sudo for system dependencies ## Output Formats ### Interactive (Default) Color-coded terminal output with checkmarks and details. ### JSON (`--json`) Machine-readable structured output: ```json { "summary": { ... }, "checks": [ ... ], "timestamp": "2025-01-15T10:30:00Z" } ``` ### Report (`--report`) Detailed text report with: - System information - Check results - Error details - Recommended fixes - Optional gist upload ## Next Steps After running `ck doctor`: 1. **Fix any failed checks** using provided solutions 2. **Update ClaudeKit** if version is outdated: ```bash ck init ``` 3. **Install missing dependencies:** ```bash ck init --install-skills ``` 4. **Test your setup:** ```bash ck new --dir test-project ``` ## Related Commands - [`ck new`](/docs/cli/new) - Create new project - [`ck init`](/docs/cli/init) - Update installation - [`ck update`](/docs/cli/update) - Update CLI itself - [Installation](/docs/cli/installation) - Setup guide - [Configuration](/docs/cli/configuration) - Configure defaults --- # ck versions Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/versions # ck versions > List all available ClaudeKit release versions from GitHub with filtering by kit, limit, and prerelease status. ## Quick Start ```bash # Show all available versions for all kits ck versions # Filter by specific kit ck versions --kit engineer # Show more versions ck versions --limit 50 # Include prereleases and drafts ck versions --all ``` ## What It Does The `ck versions` command: 1. Fetches release information from GitHub 2. Filters by kit, prerelease status, and limit 3. Displays versions in a formatted table with: - Version tag - Release name - Published date (relative time) - Asset count - Prerelease/draft badges ## Syntax ```bash ck versions [OPTIONS] ``` ### Options | Flag | Description | Default | |------|-------------|---------| | `--kit ` | Filter by specific kit (`engineer` or `marketing`) | All kits | | `--limit ` | Maximum number of versions to show | 30 | | `--all` | Include prereleases and drafts | `false` (stable only) | | `--verbose` | Enable verbose logging | `false` | ## Examples ### List All Versions Show latest 30 stable versions for all kits: ```bash ck versions ``` **Example output:** ``` 📦 ClaudeKit - Available Versions ClaudeKit Engineer - Available Versions: v1.17.0 Add multi-kit support and ownership 2 days ago (1 asset) v1.16.0 Skills migration improvements 1 week ago (1 asset) v1.15.0 Global installation support 2 weeks ago (1 asset) v1.14.2 Fix file merging edge cases 3 weeks ago (1 asset) ... Showing 30 releases ✨ Done ``` ### Filter by Kit Show versions for a specific kit: ```bash ck versions --kit engineer ``` Only displays releases for ClaudeKit Engineer. ### Show More Versions Increase the default limit: ```bash ck versions --limit 50 ``` Shows up to 50 versions instead of the default 30. ### Include Prereleases Display beta versions and drafts: ```bash ck versions --all ``` **Example output:** ``` ClaudeKit Engineer - Available Versions: v1.18.0-beta.1 New feature testing 1 day ago (1 asset) [prerelease] v1.17.0 Add multi-kit support 2 days ago (1 asset) v1.17.0-rc.2 Release candidate 4 days ago (1 asset) [prerelease] v1.16.0 Skills migration 1 week ago (1 asset) ... ``` Prereleases are marked with `[prerelease]` badge, drafts with `[draft]` badge. ### Combine Filters Show 100 engineer releases including prereleases: ```bash ck versions --kit engineer --limit 100 --all ``` ## Output Format Each version entry shows: ``` v1.17.0 Release name 2 days ago (1 asset) ^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ Version tag Release title Relative time Asset count ``` ### Badges - `[prerelease]` - Beta or prerelease version (yellow) - `[draft]` - Draft release, not published (gray) ### Relative Time Human-readable time since release: - `Today` - Released today - `Yesterday` - Released yesterday - `N days ago` - Within last week - `N weeks ago` - Within last month - `N months ago` - Within last year - `N years ago` - Over a year old ## Common Patterns ### Check Latest Version See what's new: ```bash ck versions --limit 1 ``` Shows only the most recent stable release. ### Find Beta Versions Look for upcoming features: ```bash ck versions --all --limit 10 ``` Shows latest 10 versions including betas. ### Compare Kits See versions across both kits: ```bash ck versions --limit 5 ``` Displays latest 5 versions for each available kit. ### Full Version History Get complete release timeline: ```bash ck versions --all --limit 999 ``` Shows all releases ever published (up to API limit). ## Use Cases ### Before Installing Check available versions before creating a project: ```bash # Browse versions ck versions --kit engineer # Install specific version ck new --kit engineer --release v1.16.0 ``` ### Version Pinning Find a stable version for production: ```bash ck versions --kit engineer --limit 10 ``` Avoid prereleases by not using `--all` flag. ### Beta Testing Find latest beta for testing: ```bash ck versions --all --limit 5 ``` Look for `[prerelease]` badge, then: ```bash ck new --kit engineer --release v1.18.0-beta.1 ``` ### Release Notes Research Identify version with specific features: ```bash ck versions --limit 50 ``` Check release names/titles for feature mentions. ## Troubleshooting ### "No releases found" **Causes:** 1. Repository access denied 2. Kit has no releases yet 3. Network connection issue **Solution:** ```bash # Check authentication ck doctor # Re-authenticate gh auth login # Verify repository access ck versions --verbose ``` ### "Error fetching releases" **Causes:** 1. GitHub API rate limit exceeded 2. Network timeout 3. Invalid authentication **Solution:** ```bash # Wait and retry (rate limit resets hourly) sleep 60 ck versions # Check auth status gh auth status # Use verbose mode for details ck versions --verbose ``` ### Empty Output **Causes:** 1. All releases filtered out (using `--kit` with wrong kit) 2. No stable releases (need `--all` flag) **Solution:** ```bash # Include prereleases ck versions --all # Try different kit ck versions --kit marketing # Check all kits ck versions ``` ## Version Naming Convention ClaudeKit versions follow [Semantic Versioning](https://semver.org/): ``` v1.17.0 ^ ^ ^ ^ │ │ │ └─ Patch (bug fixes) │ │ └─── Minor (new features, backward compatible) │ └────── Major (breaking changes) └──────── Prefix 'v' ``` ### Prerelease Tags - `v1.18.0-alpha.1` - Alpha (early testing) - `v1.18.0-beta.1` - Beta (feature complete, testing) - `v1.18.0-rc.1` - Release Candidate (final testing) ## Caching Release data is cached locally to improve performance. ### Cache Location `~/.claudekit/cache/releases/` ### Cache TTL Default: 1 hour (3600 seconds) ### Configure Cache Set custom TTL via environment variable: ```bash # Cache for 2 hours CK_CACHE_TTL=7200 ck versions # Disable caching (always fetch fresh) CK_CACHE_TTL=0 ck versions # Permanent configuration (add to ~/.bashrc or ~/.zshrc) export CK_CACHE_TTL=1800 # 30 minutes ``` ## Platform-Specific Notes ### Windows - Output encoding: UTF-8 (colors and badges display correctly) - Cache location: `%USERPROFILE%\.claudekit\cache\` ### macOS - Colors and badges display correctly in Terminal.app - Cache location: `~/.claudekit/cache/` ### Linux - Fully supported on all major distributions - Cache location: `~/.claudekit/cache/` - WSL supported ## Next Steps After browsing versions: 1. **Install specific version:** ```bash ck new --release v1.16.0 ``` 2. **Update to specific version:** ```bash ck init --release v1.17.0 ``` 3. **Try beta version:** ```bash ck new --release v1.18.0-beta.1 ``` 4. **Check for CLI updates:** ```bash ck update --check ``` ## Related Commands - [`ck new`](/docs/cli/new) - Create project with specific version - [`ck init`](/docs/cli/init) - Update to specific version - [`ck update`](/docs/cli/update) - Update CLI itself - [`ck doctor`](/docs/cli/doctor) - Diagnose version issues --- # ck update Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/update # ck update > Update the ClaudeKit CLI package itself to the latest version using your package manager. ## Quick Start ```bash # Check for updates ck update --check # Update to latest version ck update # Update to specific version ck update --release 3.11.0 # Update to beta version ck update --beta # Non-interactive update ck update --yes ``` **Note**: This command updates the ClaudeKit CLI tool itself, NOT your ClaudeKit project. To update your project, use [`ck init`](/docs/cli/init). ## What It Does The `ck update` command: 1. Detects your package manager (npm, bun, pnpm, yarn) 2. Fetches latest version from npm registry 3. Compares current version with target version 4. Prompts for confirmation (unless `--yes`) 5. Executes package manager update command 6. Verifies installation ## Syntax ```bash ck update [OPTIONS] ``` ### Options | Flag | Description | Default | |------|-------------|---------| | `--check` | Only check for updates, don't install | `false` | | `--release ` | Update to specific version | Latest stable | | `--beta` | Update to latest beta version | `false` | | `--yes` / `-y` | Skip confirmation prompt | `false` | | `--registry ` | Custom npm registry URL | https://registry.npmjs.org | | `--verbose` | Enable verbose logging | `false` | ## Examples ### Check for Updates See if a newer version is available without installing: ```bash ck update --check ``` **Example output:** ``` [>] ClaudeKit CLI - Update Current CLI version: 3.10.1 Latest version: 3.11.0 [^] upgrade: 3.10.1 -> 3.11.0 Update Check Update available: 3.10.1 -> 3.11.0 Run 'ck update' to install Check complete ``` ### Update to Latest Update to the newest stable version: ```bash ck update ``` **Example output:** ``` [>] ClaudeKit CLI - Update Current CLI version: 3.10.1 Using npm v10.2.4 Latest version: 3.11.0 [^] upgrade: 3.10.1 -> 3.11.0 Update CLI from 3.10.1 to 3.11.0? (y/n) y Updating CLI... ✓ Update completed ✓ Installed version: 3.11.0 [+] Successfully updated ClaudeKit CLI to 3.11.0 ``` ### Update to Specific Version Downgrade or install a specific version: ```bash ck update --release 3.9.0 ``` Useful for: - Rolling back to a known stable version - Testing specific version behavior - Matching team's CLI version ### Update to Beta Get the latest prerelease version: ```bash ck update --beta ``` **Example output:** ``` Current CLI version: 3.10.1 Latest beta version: 3.11.0-beta.2 [^] upgrade: 3.10.1 -> 3.11.0-beta.2 Update CLI from 3.10.1 to 3.11.0-beta.2? (y/n) ``` If no beta version exists, falls back to latest stable. ### Non-Interactive Update Skip confirmation prompt (useful for scripts): ```bash ck update --yes ``` Or short form: ```bash ck update -y ``` ### Combine Flags Update to latest beta without confirmation: ```bash ck update --beta --yes ``` ## Package Manager Detection The CLI automatically detects which package manager you used for installation: ### Detected Managers - **npm** - Default Node.js package manager - **bun** - Fast all-in-one JavaScript runtime - **pnpm** - Fast, disk space efficient - **yarn** - Alternative to npm ### Detection Order 1. Checks for global installation path patterns 2. Verifies package manager is installed 3. Falls back to npm if detection fails ### Update Commands Used The CLI uses the appropriate command for your package manager: | Manager | Update Command | |---------|----------------| | npm | `npm update -g claudekit-cli` | | bun | `bun update -g claudekit-cli` | | pnpm | `pnpm update -g claudekit-cli` | | yarn | `yarn global upgrade claudekit-cli` | ## Update Notifications The CLI automatically checks for updates when you run: ```bash ck --version ``` **Example with update available:** ``` CLI Version: 3.10.1 Local Kit Version: 1.16.0 (ClaudeKit Engineer) ⚠ Update available: 3.10.1 -> 3.11.0 Run 'ck update' to install ``` ### Notification Caching Update checks are cached for 7 days to minimize API calls. **Cache location:** - **macOS/Linux**: `~/.claudekit/cache/version-check.json` - **Windows**: `%USERPROFILE%\.claudekit\cache\version-check.json` ### Disable Notifications Set environment variable to disable update notifications: ```bash # Temporary (current session) NO_UPDATE_NOTIFIER=1 ck --version # Permanent (add to ~/.bashrc or ~/.zshrc) export NO_UPDATE_NOTIFIER=1 ``` **Windows (PowerShell):** ```powershell [System.Environment]::SetEnvironmentVariable("NO_UPDATE_NOTIFIER", "1", [System.EnvironmentVariableTarget]::User) ``` ## Common Patterns ### Regular Update Routine Keep CLI up to date: ```bash # Weekly check ck update --check # If update available, install it ck update ``` ### Team Version Sync Ensure team uses same CLI version: ```bash # In team docs, specify version ck update --release 3.10.1 ``` ### Beta Testing Test upcoming features: ```bash # Install beta ck update --beta # Try new features ck new --help # Roll back to stable if issues ck update --release 3.10.1 ``` ### Automated Updates Add to cron job or scheduled task: ```bash # Auto-update weekly (add to crontab) 0 9 * * 1 ck update --yes ``` **Windows Task Scheduler:** ```powershell schtasks /create /tn "ClaudeKit Update" /tr "ck update --yes" /sc weekly /d MON /st 09:00 ``` ## Troubleshooting ### "Permission denied" Error **Symptoms:** ``` EACCES: permission denied ``` **Cause:** Insufficient permissions for global package directory. **Solutions:** **Option 1: Use sudo (Linux/macOS)** ```bash sudo ck update ``` Or manually: ```bash sudo npm update -g claudekit-cli ``` **Option 2: Fix npm Permissions (Recommended)** Follow [npm's guide to fix permissions](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). **Option 3: Use a Node Version Manager** - **nvm** (Linux/macOS): [nvm installation](https://github.com/nvm-sh/nvm) - **nvm-windows** (Windows): [nvm-windows](https://github.com/coreybutler/nvm-windows) ### "Version X does not exist" **Symptoms:** ``` Version 3.99.0 does not exist on npm registry ``` **Cause:** Specified version not published or typo. **Solutions:** ```bash # Check available versions npm view claudekit-cli versions # Or use CLI versions command (won't work for CLI itself, but shows pattern) # Then install correct version ck update --release 3.11.0 ``` ### "Already on the latest version" **Symptoms:** ``` [+] Already on the latest version (3.11.0) ``` **Meaning:** You're up to date. No action needed. **To force reinstall:** ```bash npm uninstall -g claudekit-cli npm install -g claudekit-cli ``` ### Update Fails Silently **Symptoms:** No error, but version doesn't change. **Cause:** Package manager cache issue. **Solutions:** ```bash # Clear npm cache npm cache clean --force # Retry update ck update # Or reinstall npm uninstall -g claudekit-cli npm install -g claudekit-cli@latest ``` ### "Please restart your terminal" **Symptoms:** Update succeeds but `ck --version` shows old version. **Cause:** Shell hasn't reloaded PATH. **Solutions:** **Option 1: Restart terminal** (easiest) **Option 2: Reload shell config** ```bash source ~/.bashrc # or ~/.zshrc ``` **Option 3: Use full path** ```bash $(npm config get prefix)/bin/ck --version ``` ## Platform-Specific Notes ### Windows - Use PowerShell or Windows Terminal - May require administrator privileges - Antivirus may interfere with update ### macOS - Homebrew users: If installed via Homebrew, use `brew upgrade` - System Integrity Protection may require sudo ### Linux - Package manager varies by distro - WSL fully supported - May need sudo for global installs ## Version Verification After updating, verify the new version: ```bash ck --version ``` Expected output: ``` CLI Version: 3.11.0 ``` If old version still shows, restart terminal or reload shell config. ## Rollback To rollback to a previous version: ```bash # Install specific older version ck update --release 3.10.0 # Verify ck --version ``` ## Next Steps After updating the CLI: 1. **Update your projects** to latest kit versions: ```bash cd my-project ck init ``` 2. **Check for breaking changes** in release notes 3. **Test commands** to ensure compatibility 4. **Run health check:** ```bash ck doctor ``` ## Related Commands - [`ck --version`](/docs/cli#verify-installation) - Check current version - [`ck init`](/docs/cli/init) - Update ClaudeKit project (not CLI) - [`ck doctor`](/docs/cli/doctor) - Diagnose CLI issues - [`ck versions`](/docs/cli/versions) - List kit versions (not CLI versions) - [Installation](/docs/cli/installation) - Initial setup --- # ck uninstall Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/uninstall # ck uninstall > Remove ClaudeKit installations from your system with intelligent customization preservation and ownership-aware file management. ## Quick Start ```bash # Interactive mode (prompts for scope and confirmation) ck uninstall # Uninstall local installation only ck uninstall --local # Uninstall global installation only ck uninstall --global # Uninstall both without confirmation ck uninstall --yes # Preview what would be removed ck uninstall --dry-run ``` ## What It Does The `ck uninstall` command: 1. Detects ClaudeKit installations (local `.claude/` and/or global `~/.claude/`) 2. Prompts you to choose scope (local, global, or both) 3. Analyzes files using ownership tracking 4. Shows preview of files to delete and preserve 5. Creates a scoped recovery backup under `~/.claudekit/backups/` 6. Removes ClaudeKit-owned files 6. Preserves user customizations and configurations 7. Cleans up empty directories ## Syntax ```bash ck uninstall [OPTIONS] ``` ### Options | Flag | Description | Default | |------|-------------|---------| | `--local` / `-l` | Uninstall only local installation (`.claude/`) | Prompt | | `--global` / `-g` | Uninstall only global installation (`~/.claude/`) | Prompt | | `--all` | Uninstall both local and global | Prompt | | `--yes` / `-y` | Skip confirmation prompt | `false` | | `--kit ` | Uninstall specific kit only (multi-kit installations) | All kits | | `--dry-run` | Preview changes without removing files | `false` | | `--force-overwrite` | Delete modified files (use with caution) | `false` | | `--verbose` | Enable verbose logging | `false` | After uninstall creates a recovery backup, you can inspect or restore it with [`ck backups`](/docs/cli/backups). ## Installation Scopes ### Local Installation Located in project's `.claude/` directory: ``` my-project/ └── .claude/ ├── agents/ ├── commands/ ├── skills/ └── ... ``` **When to uninstall:** - Removing ClaudeKit from specific project - Switching to global installation - Project no longer needs ClaudeKit ### Global Installation Located in user's home directory: **macOS/Linux:** `~/.claude/` **Windows:** `%USERPROFILE%\.claude\` **When to uninstall:** - No longer using ClaudeKit - Switching to local-only installations - Clean reinstall needed ### Multi-Kit Installations If multiple kits are installed (Engineer + Marketing), you can: - Uninstall specific kit: `ck uninstall --kit engineer` - Uninstall all kits: `ck uninstall` ## Examples ### Interactive Uninstall Let the CLI guide you through the process: ```bash ck uninstall ``` **Example output:** ``` ClaudeKit Uninstaller Detected ClaudeKit installations (both) Local : /Users/you/my-project/.claude Global: /Users/you/.claude [!] This will permanently delete ClaudeKit files from the above paths. Which installation(s) do you want to uninstall? > Local only Global only Both Local only selected Continue with uninstalling local ClaudeKit installation? (y/n) y Removing local ClaudeKit files... ✓ Removed 245 files, cleaned 15 empty directories, preserved 8 customizations Preserved customizations: - .env (user-created) - commands/custom-cmd/ (user-created) - workflows/my-workflow.md (modified by user) ... ClaudeKit uninstalled successfully! ``` ### Local Installation Only Remove ClaudeKit from current project: ```bash ck uninstall --local ``` Equivalent short form: ```bash ck uninstall -l ``` ### Global Installation Only Remove ClaudeKit from user directory: ```bash ck uninstall --global ``` Equivalent short form: ```bash ck uninstall -g ``` ### Non-Interactive Uninstall Skip all prompts (useful for scripts): ```bash # Local only, no confirmation ck uninstall --local --yes # Global only, no confirmation ck uninstall --global --yes # Both, no confirmation ck uninstall --yes ``` ### Dry Run Preview what would be removed without actually deleting: ```bash ck uninstall --dry-run ``` **Example output:** ``` DRY RUN MODE - No files will be deleted DRY RUN - Preview for local installation: Files to DELETE (245): ✖ agents/planner/ ✖ commands/plan/ ✖ skills/ai-multimodal/ ... ... and 235 more Files to PRESERVE (8): ✓ .env (user-created) ✓ commands/custom-cmd/ (user-created) ✓ workflows/my-workflow.md (modified by user) ... Dry-run complete. No changes were made. ``` ### Uninstall Specific Kit For multi-kit installations, remove one kit while keeping others: ```bash ck uninstall --kit engineer ``` **Example output:** ``` Kit-scoped uninstall: engineer kit only Removing local engineer kit files... ✓ Removed 150 files, marketing kit preserved Remaining kits after uninstall: marketing ``` ### Force Overwrite Modified Files Delete even files you've modified (use with caution): ```bash ck uninstall --force-overwrite --yes ``` **Warning:** This permanently deletes your customizations. Use only when: - You want a completely clean slate - Customizations are backed up elsewhere - Starting fresh installation ## File Ownership and Preservation The CLI uses ownership tracking to intelligently preserve your work. ### Ownership Categories | Ownership | Description | Default Action | |-----------|-------------|----------------| | **ck-owned** | Original ClaudeKit files, unmodified | DELETE | | **ck-modified** | ClaudeKit files you've edited | PRESERVE | | **user-created** | Files you created | PRESERVE | ### Always Preserved Regardless of ownership: - `.env`, `.env.local`, `.env.*.local` - `*.key`, `*.pem`, `*.p12`, `*.pfx` - `settings.json`, `settings.local.json` - `CLAUDE.md` (in global mode) - Files in `node_modules/`, `.git/`, `dist/`, `build/` ### Customization Detection The CLI detects customizations via: 1. **Manifest comparison** - Files not in release manifest are user-created 2. **Checksum verification** - Modified files detected via SHA-256 hash 3. **Pattern matching** - Known user config files preserved ## Common Patterns ### Clean Project Uninstall Remove ClaudeKit from project while keeping configs: ```bash cd my-project ck uninstall --local ``` Preserves: - `.env` files - Custom commands - Modified workflows ### Complete Removal Remove all ClaudeKit installations system-wide: ```bash ck uninstall --yes ``` When prompted, select "Both" to remove local and global. ### Safe Uninstall with Preview Check what will be removed before confirming: ```bash ck uninstall --dry-run ck uninstall # Proceed if satisfied ``` ### Switch from Local to Global ```bash # Remove local installation cd my-project ck uninstall --local --yes # Install globally ck init --global ``` ### Switch from Global to Local ```bash # Remove global installation ck uninstall --global --yes # Install locally cd my-project ck init ``` ## Troubleshooting ### "No ClaudeKit installations found" **Cause:** No valid ClaudeKit installations detected. **Explanation:** The CLI only uninstalls directories that: - Contain `metadata.json` (ClaudeKit installation marker) - Are valid ClaudeKit installations Regular `.claude` directories from Claude Desktop are NOT affected. **Solution:** If you believe ClaudeKit is installed: ```bash # Check for metadata cat .claude/metadata.json cat ~/.claude/metadata.json # Run doctor to diagnose ck doctor ``` ### "Kit engineer is not installed" **Cause:** Specified kit not found in installation. **Solution:** ```bash # Check installed kits ck doctor # Uninstall all kits ck uninstall # Don't use --kit flag ``` ### Files Still Exist After Uninstall **Expected:** User customizations are intentionally preserved. **To view what was preserved:** ```bash ck uninstall --dry-run ``` **To force complete deletion:** ```bash # WARNING: Deletes ALL customizations ck uninstall --force-overwrite --yes ``` Or manually: ```bash rm -rf .claude/ # Local rm -rf ~/.claude/ # Global ``` ### Permission Denied **Symptoms:** ``` Failed to remove files from /path: EACCES: permission denied ``` **Solutions:** **Linux/macOS:** ```bash sudo ck uninstall ``` **Windows:** Run PowerShell as Administrator, then: ```powershell ck uninstall ``` ## What Gets Removed After uninstalling, ClaudeKit-owned files are deleted: ### Deleted - `agents/` directory (ClaudeKit-owned agents) - `commands/` directory (ClaudeKit-owned commands) - `skills/` directory (ClaudeKit-owned skills) - `workflows/` directory (ClaudeKit-owned workflows) - `hooks/` directory - `metadata.json` - Empty parent directories ### Preserved - `.env` files - Custom commands (not in manifest) - Modified workflows - User-created skills - `settings.json`, `CLAUDE.md` ## Reinstallation To reinstall ClaudeKit after uninstalling: ### Fresh Install ```bash ck init --fresh ``` Or for new projects: ```bash ck new --kit engineer ``` ### With Preserved Customizations After uninstall (which preserves customizations), simply: ```bash ck init ``` Your preserved files will be merged with new installation. ## Platform-Specific Notes ### Windows - Global path: `%USERPROFILE%\.claude\` - Use PowerShell or Windows Terminal - May require administrator privileges ### macOS - Global path: `~/.claude/` - Preserved files shown in Finder - Uses native file operations ### Linux - Global path: `~/.claude/` - WSL fully supported - May need sudo for system directories ## Alternative: Manual Removal If CLI uninstall fails, manually remove: ### Local Installation ```bash rm -rf .claude/ ``` ### Global Installation ```bash # macOS/Linux rm -rf ~/.claude/ # Windows (PowerShell) Remove-Item -Recurse -Force $env:USERPROFILE\.claude ``` **Warning:** Manual removal bypasses ownership tracking and deletes everything, including customizations. ## Next Steps After uninstalling: 1. **Reinstall if needed:** ```bash ck init ``` 2. **Install different kit:** ```bash ck new --kit marketing ``` 3. **Uninstall CLI itself:** ```bash npm uninstall -g claudekit-cli ``` ## Related Commands - [`ck init`](/docs/cli/init) - Reinstall ClaudeKit - [`ck new`](/docs/cli/new) - Create fresh project - [`ck doctor`](/docs/cli/doctor) - Diagnose installation - [Installation](/docs/cli/installation) - Setup guide --- # Configuration Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/configuration # Configuration > Customize ClaudeKit CLI behavior with config files, environment variables, and project-specific settings. ## Configuration Files ClaudeKit CLI uses multiple configuration files at different levels. ### Global CLI Config **Location:** `~/.claudekit/config.json` **Purpose:** Store CLI defaults and authentication **Structure:** ```json { "github": { "token": "stored_in_keychain" }, "defaults": { "kit": "engineer", "dir": "." } } ``` **Auto-created:** Yes, on first run **Fields:** | Field | Type | Description | |-------|------|-------------| | `github.token` | string | GitHub authentication token (stored in OS keychain) | | `defaults.kit` | string | Default kit for `ck new` and `ck init` | | `defaults.dir` | string | Default target directory | ### Project Config **Location (Local):** `.claude/.ck.json` **Location (Global):** `~/.claude/.ck.json` **Purpose:** Store project-specific folder configuration **Structure:** ```json { "folders": { "docs": "documentation", "plans": "planning" } } ``` **Auto-created:** When using custom folder names **Fields:** | Field | Type | Description | |-------|------|-------------| | `folders.docs` | string | Custom name for docs directory | | `folders.plans` | string | Custom name for plans directory | ### ClaudeKit Metadata **Location (Local):** `.claude/metadata.json` **Location (Global):** `~/.claude/metadata.json` **Purpose:** Track installation version and ownership **Structure (Single Kit):** ```json { "name": "ClaudeKit Engineer", "version": "1.17.0", "installedAt": "2025-01-15T10:30:00.000Z", "mode": "local", "files": [ { "path": "agents/planner/agent.json", "hash": "sha256-abc123...", "ownership": "ck", "installedVersion": "1.17.0" } ] } ``` **Structure (Multi-Kit):** ```json { "version": "1.17.0", "installedAt": "2025-01-15T10:30:00.000Z", "mode": "local", "kits": { "engineer": { "name": "ClaudeKit Engineer", "version": "1.17.0", "installedAt": "2025-01-15T10:30:00.000Z", "files": [ /* file tracking */ ] }, "marketing": { "name": "ClaudeKit Marketing", "version": "1.5.0", "installedAt": "2025-01-16T14:20:00.000Z", "files": [ /* file tracking */ ] } } } ``` **Auto-created:** Yes, by `ck new` or `ck init` **Fields:** | Field | Type | Description | |-------|------|-------------| | `name` | string | Kit name (single-kit only) | | `version` | string | Installed version | | `installedAt` | string | ISO 8601 timestamp | | `mode` | string | `"local"` or `"global"` | | `files` | array | File ownership tracking (single-kit) | | `kits` | object | Multi-kit installations (contains kit-specific data) | ## Environment Variables Configure CLI behavior via environment variables. ### Authentication #### GITHUB_TOKEN **Purpose:** GitHub personal access token for API authentication **Fallback order:** 1. GitHub CLI (`gh auth token`) 2. `GITHUB_TOKEN` environment variable 3. Config file (`~/.claudekit/config.json`) 4. OS keychain 5. User prompt **Usage:** ```bash export GITHUB_TOKEN=ghp_abc123... ck new ``` **Note:** GitHub CLI (`gh auth login`) is recommended over PAT. ### Behavior #### CI **Purpose:** Detect CI/CD environment, enable non-interactive mode **Values:** `"true"` or `"false"` **Usage:** ```bash CI=true ck init --release v1.16.0 ``` **Effect:** - Disables interactive prompts - Requires explicit `--release` flag for version selection - Skips confirmation prompts #### NON_INTERACTIVE **Purpose:** Force non-interactive mode **Values:** `"true"` or `"false"` **Usage:** ```bash NON_INTERACTIVE=true ck new --kit engineer --dir ./project ``` **Effect:** Same as `CI=true` #### NO_UPDATE_NOTIFIER **Purpose:** Disable update notifications **Values:** `"1"` or any truthy value **Usage:** ```bash export NO_UPDATE_NOTIFIER=1 ck --version # No update notification shown ``` **Permanent:** ```bash # Add to ~/.bashrc or ~/.zshrc echo 'export NO_UPDATE_NOTIFIER=1' >> ~/.bashrc ``` #### CLAUDEKIT_VERBOSE **Purpose:** Enable verbose logging globally **Values:** `"1"` or `"true"` **Usage:** ```bash CLAUDEKIT_VERBOSE=1 ck new ``` **Effect:** Same as `--verbose` flag on all commands ### Caching #### CK_CACHE_TTL **Purpose:** Set cache time-to-live in seconds **Default:** `3600` (1 hour) **Usage:** ```bash # Cache for 2 hours CK_CACHE_TTL=7200 ck versions # Disable caching (always fetch fresh) CK_CACHE_TTL=0 ck versions # Cache for 30 minutes (permanent) export CK_CACHE_TTL=1800 ``` **What's cached:** - GitHub release data - Version check results **Cache locations:** - **Releases:** `~/.claudekit/cache/releases/` - **Version checks:** `~/.claudekit/cache/version-check.json` ## Command-Line Defaults Set defaults to avoid repetitive flags. ### Kit Default Set default kit for `ck new` and `ck init`: **Via config file:** Edit `~/.claudekit/config.json`: ```json { "defaults": { "kit": "engineer" } } ``` **Via command:** ```bash # First run with --kit flag ck new --kit engineer # Saves to config, future runs use it ck new # Uses engineer by default ``` ### Directory Default Set default target directory: **Via config file:** ```json { "defaults": { "dir": "~/projects" } } ``` **Effect:** ```bash ck new # Creates project in ~/projects instead of current dir ``` ## Custom Folder Names Use custom names for `docs/` and `plans/` directories. ### Per-Project Configuration **Set during creation:** ```bash ck new --docs-dir documentation --plans-dir planning ``` **Set during update:** ```bash ck init --docs-dir documentation --plans-dir planning ``` **What happens:** 1. Folder names changed in file system 2. All references updated in workflow files 3. Configuration saved to `.claude/.ck.json` 4. Future updates preserve custom names ### Configuration File **Location:** `.claude/.ck.json` **Structure:** ```json { "folders": { "docs": "documentation", "plans": "planning" } } ``` **Read by:** `ck init` during updates ## Protected File Patterns Files matching these patterns are never overwritten during updates. ### Environment Files - `.env` - `.env.local` - `.env.*.local` (e.g., `.env.production.local`) ### Credential Files - `*.key` (private keys) - `*.pem` (certificates) - `*.p12`, `*.pfx` (PKCS12 files) ### User Configuration - `settings.json` - `settings.local.json` - `CLAUDE.md` (global mode only) ### Build Artifacts - `node_modules/**` - `.git/**` - `dist/**` - `build/**` ### Custom Exclude Patterns Add your own patterns: ```bash ck new --exclude "*.log" --exclude "temp/**" ck init --exclude "secrets/**" ``` ## Platform-Specific Paths Configuration locations vary by platform. ### macOS/Linux | Type | Path | |------|------| | CLI Config | `~/.claudekit/config.json` | | Release Cache | `~/.claudekit/cache/releases/` | | Version Cache | `~/.claudekit/cache/version-check.json` | | Global Kit | `~/.claude/` | | Local Kit | `./.claude/` | ### Windows | Type | Path | |------|------| | CLI Config | `%USERPROFILE%\.claudekit\config.json` | | Release Cache | `%USERPROFILE%\.claudekit\cache\releases\` | | Version Cache | `%USERPROFILE%\.claudekit\cache\version-check.json` | | Global Kit | `%USERPROFILE%\.claude\` | | Local Kit | `.\.claude\` | ## Configuration Examples ### Minimal Setup Basic configuration for quick start: ```json { "defaults": { "kit": "engineer" } } ``` ### Team Configuration Shared settings for team projects: ```json { "defaults": { "kit": "engineer", "dir": "." } } ``` **Team workflow:** 1. Team lead sets defaults 2. Team members use same config 3. Consistent project structure ### CI/CD Configuration Optimized for automation: ```bash # .github/workflows/setup.yml env: CI: true NO_UPDATE_NOTIFIER: 1 CK_CACHE_TTL: 0 steps: - name: Install ClaudeKit run: ck init --yes --release v1.16.0 --skip-setup ``` ### Development vs Production **Development:** ```bash # Use beta versions ck new --beta --install-skills ``` **Production:** ```bash # Pin stable version ck new --release v1.16.0 ``` ## Debugging Configuration ### View Current Config ```bash # View global config cat ~/.claudekit/config.json # View project config cat .claude/.ck.json # View metadata cat .claude/metadata.json ``` ### Validate Configuration ```bash # Run health check ck doctor # Verbose mode for details ck doctor --verbose ``` ### Reset Configuration **Reset CLI config:** ```bash rm ~/.claudekit/config.json ck new # Will recreate with prompts ``` **Reset project config:** ```bash rm .claude/.ck.json ck init # Will use defaults ``` ## Best Practices ### Version Pinning For production projects: ```bash # Pin to specific stable version ck new --release v1.16.0 # Document in README echo "ClaudeKit Version: 1.16.0" >> README.md ``` ### Team Synchronization Keep team on same CLI version: ```bash # In team docs npm install -g claudekit-cli@3.10.1 # Or package.json (local install) { "devDependencies": { "claudekit-cli": "3.10.1" } } ``` ### Credentials Security Never commit credentials: ```bash # Add to .gitignore echo ".env" >> .gitignore echo ".env.local" >> .gitignore echo "*.key" >> .gitignore # Use environment variables in CI # Set GITHUB_TOKEN in CI secrets ``` ### Cache Management Clear cache periodically: ```bash # Clear release cache rm -rf ~/.claudekit/cache/releases/ # Clear version check cache rm -rf ~/.claudekit/cache/version-check.json # Or set lower TTL export CK_CACHE_TTL=1800 # 30 minutes ``` ## Troubleshooting Configuration ### "Config file not found" **Normal behavior** - Config is created on first run. **To pre-create:** ```bash mkdir -p ~/.claudekit echo '{"defaults":{"kit":"engineer"}}' > ~/.claudekit/config.json ``` ### "Invalid JSON in config file" **Fix:** ```bash # Validate JSON cat ~/.claudekit/config.json | jq . # If invalid, recreate rm ~/.claudekit/config.json ck new # Recreates with valid JSON ``` ### "Permission denied" on config file **Linux/macOS:** ```bash chmod 600 ~/.claudekit/config.json ``` **Windows:** Run as administrator or check file permissions in Properties. ## New in v3.36.0 ### StatuslineColors Enable or disable ANSI color rendering in the Claude Code status line. Add to `.claude/.ck.json` (or `~/.claude/.ck.json` for global): ```json { "statuslineColors": true } ``` | Value | Effect | |-------|--------| | `true` (default) | ANSI colors enabled in status line | | `false` | Plain ASCII status line (useful for terminals without color support) | ### Hook Diagnostics Dashboard `ck config` now includes a hook diagnostics panel showing: - Execution logs for all registered hooks - Timing data per hook run - Error history and failure details Use this to debug hook configuration issues or verify hooks are firing as expected. ### Config Dashboard Access By default, `ck config` binds the dashboard to `127.0.0.1`, which keeps access local to the machine running the CLI. Use `--host` when you intentionally want to reach the dashboard from another device on the same trusted network: ```bash # Expose to your LAN/Tailscale ck config --host 0.0.0.0 --no-open # Bind to a specific interface or hostname ck config --host 100.88.12.4 --no-open ck config --host dashboard.local --no-open ``` The dashboard still enforces same-origin browser access. Remote access works when the browser opens the UI from the same host or origin that reaches the server. ### Quality Gate Hooks ClaudeKit automatically installs git pre-commit and pre-push hooks during `ck init`: - **pre-commit** — Runs linter before every commit. Blocks commit if lint fails. - **pre-push** — Runs test suite before every push. Blocks push if tests fail. These hooks enforce code quality locally, preventing broken code from reaching CI. Hooks are idempotent — safe to re-run `ck init` without duplicating them. To skip hooks in an emergency (not recommended): ```bash git commit --no-verify git push --no-verify ``` ## Next Steps After configuring: 1. **Test configuration:** ```bash ck doctor ``` 2. **Create a project:** ```bash ck new ``` 3. **Verify settings:** ```bash cat .claude/metadata.json ``` ## Related Commands - [`ck doctor`](/docs/cli/doctor) - Validate configuration - [`ck new`](/docs/cli/new) - Create project with config - [`ck init`](/docs/cli/init) - Update project preserving config - [Installation](/docs/cli/installation) - Initial setup --- # ck backups Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/backups # ck backups > Manage the scoped recovery backups ClaudeKit creates before destructive operations such as `ck init --fresh` and `ck uninstall`. ## Quick Start ```bash # List newest backups ck backups list # Restore a specific backup ck backups restore 2026-04-06T21-53-01-706-byrf # Keep only the newest 10 backups ck backups prune --keep 10 ``` ## What Gets Backed Up ClaudeKit does **not** back up the full `~/.claude/` directory. Each destructive-operation backup contains only the files ClaudeKit is about to: - delete - rewrite Typical contents include: - CK-owned tracked command/agent/skill/rule files - CK-modified tracked files when a destructive flow will replace them - `metadata.json` when the operation deletes or mutates it User-owned files that ClaudeKit preserves are not copied into these backups. ## Storage Location Backups live under: ```text ~/.claudekit/backups// ``` Each backup directory contains: ```text manifest.json snapshot/ ``` - `manifest.json` describes the operation, source root, and backed-up items - `snapshot/` stores only the scoped payload for that operation The backup directory name is also the backup ID used by `ck backups restore` and `ck backups prune`. ## Automatic Retention ClaudeKit automatically prunes old destructive-operation backups after a new backup is written successfully. - Default policy: keep the newest `10` backups - Manual cleanup: `ck backups prune --keep ` - Delete everything: `ck backups prune --all` ## Commands ### List Backups ```bash ck backups list ck backups list --limit 5 ck backups list --json ``` This shows backup IDs, operation type, creation time, item count, size, and whether the manifest is valid. ### Restore A Backup ```bash ck backups restore ck backups restore --yes ck backups restore --json ``` Restore writes the backup back to the original `sourceRoot` recorded in the manifest. Safety behavior: - requires confirmation unless `--yes` is used - validates that the backup manifest is well-formed - validates that restore targets stay inside the original installation root - blocks restore through symlinked parent directories - serializes restore against install/uninstall using the same installation lock ### Prune Backups ```bash ck backups prune --keep 10 ck backups prune --yes ck backups prune --all --yes ck backups prune --json ``` Prune can: - delete one backup by ID - delete all backups - keep the newest `N` and delete the rest ## Related Commands - [`ck init`](/docs/cli/init) — destructive `--fresh` flow creates recovery backups - [`ck uninstall`](/docs/cli/uninstall) — uninstall creates recovery backups before deleting files --- # ck migrate Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/migrate # ck migrate > One-shot migration of all ClaudeKit portable content (agents, commands, skills, config, rules, hooks) to other AI coding providers with intelligent reconciliation and conflict resolution. ## Quick Start ```bash # Interactive mode (auto-detects installed providers) ck migrate # Migrate to specific providers ck migrate --agent cursor --agent codex # Migrate to all supported providers globally ck migrate --all --global # Preview migration plan without writing files ck migrate --dry-run # Force ASCII borders for legacy terminals CK_FORCE_ASCII=1 ck migrate --agent codex --dry-run # Non-interactive with sensible defaults ck migrate --yes ``` ## Terminal Flow The current CLI flow is optimized to answer the two questions users actually ask during migration: 1. **Where will the files go?** 2. **What changed?** Before any write happens, `ck migrate` now renders: - A **source/destination intro panel** showing discovered Claude Code content and the target provider paths - A **pre-flight summary** with one row per portable type (`Agents`, `Skills`, `Commands`, `Config`, `Rules`, `Hooks`) - Inline scope notes such as `merge` when a provider does not map 1:1 After execution, the command ends with a boxed footer: - **WHERE** — destination paths that were actually touched - **WHAT** — item counts by type - **NEXT** — follow-up commands such as `ck doctor` or provider-specific inspection commands `--dry-run` uses the same structure, but reports what **would** change instead of writing files. ## Scope Behavior - **Default scope**: project-level - **Global scope**: pass `-g` or `--global` - **Provider quirks still apply**: for example, Codex commands migrate as skills, so project scope writes `.agents/skills/source-command-*/SKILL.md` and global scope writes `~/.agents/skills/source-command-*/SKILL.md` If you are migrating in older Windows terminals, set `CK_FORCE_ASCII=1` to force the ASCII fallback border set. ## What Happens The `ck migrate` command: 1. **Discovers** all portable items from your `.claude/` directory (agents, commands, skills, config, rules, hooks) 2. **Detects** installed AI coding providers on your system 3. **Computes** a reconciliation plan comparing source vs target states 4. **Resolves** conflicts interactively (or auto-resolves with `--yes`) 5. **Installs** converted content to each target provider's format 6. **Merges** hook settings into provider-specific `settings.json` 7. **Cleans up** stale registry entries and deprecated paths > **Generated hook cleanup (v4.3.0+):** `ck migrate` does not migrate ClaudeKit's generated session/subagent/usage context hooks by default. It also removes stale registrations and hook files for those generated hooks from existing migrated providers, including Codex and Claude Code, while preserving safety hooks such as privacy and scout blocking. ## Supported Providers Each column indicates how well `ck migrate` can transfer that content type to the target provider: - **Yes** — Provider has a native equivalent. Content migrates 1:1 with full functionality. - **Partial** — Content is copied/converted, but the provider has no native equivalent for this concept. It may work as context or rules, but not as a first-class feature (e.g., agents merged into a flat context file). - **-** — Not supported. Content is not migrated to this provider. | Provider | Agents | Commands | Skills | Config | Rules | Hooks | |----------|--------|----------|--------|--------|-------|-------| | Claude Code | Yes | Yes | Yes | Yes | Yes | Yes | | OpenCode | Yes | Yes | Yes | Yes | Yes | - | | GitHub Copilot | Yes | - | Yes | Yes | Yes | - | | Codex | Yes | Yes | Yes | Yes | Yes | Yes | | Droid | Yes | Yes | Yes | Yes | Yes | Yes | | Cursor | Partial | - | Yes | Yes | Yes | - | | Roo Code | Yes | - | Yes | Yes | Yes | - | | Kilo Code | Yes | - | Yes | Yes | Yes | - | | Windsurf | Partial | Yes | Yes | Yes | Yes | - | | Goose | Partial | - | Yes | Yes | Yes | - | | Gemini CLI | Partial | Yes | Yes | Yes | Yes | - | | Amp | Partial | - | Yes | Yes | Yes | - | | Antigravity | - | Yes | Yes | Yes | Yes | - | | Cline | Partial | - | Yes | Yes | Yes | - | | OpenHands | Partial | - | Yes | Yes | Yes | - | ## Options ### Target Options | Flag | Description | |------|-------------| | `-a, --agent ` | Target provider(s), can be specified multiple times | | `--all` | Migrate to all supported providers | | `-g, --global` | Install globally instead of project-level | | `-y, --yes` | Skip confirmation prompts | | `-f, --force` | Force reinstall deleted/edited items | | `--dry-run` | Preview migration plan without writing files | ### Content Selection | Flag | Description | |------|-------------| | `--config` | Migrate CLAUDE.md config only | | `--rules` | Migrate `.claude/rules/` only | | `--hooks` | Migrate `.claude/hooks/` only | | `--skip-config` | Skip config migration | | `--skip-rules` | Skip rules migration | | `--skip-hooks` | Skip hooks migration | | `--source ` | Custom CLAUDE.md source path | ## Content Selection Logic The content selection flags follow a precise truth table: **"Only" mode** — when any of `--config`, `--rules`, `--hooks` are specified: - `--config` — only config (no agents/commands/skills/rules/hooks) - `--rules` — only rules - `--hooks` — only hooks - `--config --rules` — only config AND rules - `--config --hooks` — only config AND hooks - `--config --rules --hooks` — only config, rules, AND hooks **"Skip" mode** — when any of `--skip-*` flags are used: - `--skip-config` — everything except config - `--skip-rules` — everything except rules - `--skip-hooks` — everything except hooks **Default** (no flags) — migrates everything. ## Reconciliation Engine The migrate command uses a sophisticated reconciliation engine that: 1. **Computes checksums** for both source items and target files 2. **Compares states** against the portable registry to detect: - New items to install - Updated items needing refresh - Unchanged items to skip - Deleted items to clean up - Conflicts requiring resolution 3. **Generates a plan** showing all actions before execution ### Conflict Resolution When a target file has been modified externally, the command offers: - **Overwrite** — replace with source content - **Smart merge** — attempt to merge changes - **Skip** — keep existing content - **View diff** — see the differences before deciding ## Examples ### Migrate everything to Cursor ```bash ck migrate --agent cursor ``` ### Migrate config and rules to all providers ```bash ck migrate --all --config --rules ``` ### Force re-migrate hooks globally ```bash ck migrate --all --global --hooks --force ``` ### Preview what would change ```bash ck migrate --dry-run ``` ### Migrate to multiple specific providers ```bash ck migrate --agent droid --agent codex --agent cursor ``` ### Skip hooks during migration ```bash ck migrate --all --skip-hooks ``` ### Use custom CLAUDE.md source ```bash ck migrate --agent cursor --source ./custom/CLAUDE.md ``` ## Migration Phases ### Phase 1: Discovery Scans `.claude/agents/`, `.claude/commands/`, `.claude/skills/`, `.claude/rules/`, `.claude/hooks/`, and `CLAUDE.md` for portable content. ### Phase 2: Provider Selection Auto-detects installed providers or prompts for selection. Use `--agent` or `--all` to skip detection. ### Phase 3: Scope Selection Choose between project-level (`.claude/` in CWD, the default) or global (`~/.claude/`) installation. ### Phase 4: Reconciliation Computes a migration plan using checksums and registry state. Displays actions (install, update, skip, delete, conflict). ### Phase 5: Execution Installs items, merges hook settings, processes metadata deletions, and cleans up stale entries. ### Phase 6: Summary Displays a destination-aware `WHERE / WHAT / NEXT` footer and offers rollback on partial failures. ## Provider Notes ### OpenCode `ck migrate --agent opencode` writes a **default model** to `opencode.json` so migrated agents resolve at invocation. The migration: 1. Reads your authenticated providers from `~/.local/share/opencode/auth.json`. 2. Picks a sensible default model from the [models.dev](https://models.dev) catalog. When **OpenCode Zen** (provider id `opencode`) is authenticated — the most common case — the migration prefers a free-tier model (`*-free`), sorted newest first. 3. In interactive mode, you can accept the suggestion, type a custom `provider/model` string, or skip. In `--yes` / non-interactive mode, the suggestion is auto-accepted. 4. If `opencode` is **not** authenticated (no `auth.json` or empty), `--yes` mode exits with a clear hint: `Run: opencode auth login`. The migration does NOT write a guessed default that would later fail. 5. If your `opencode.json` already has a `model` field, the migration validates it against the live `models.dev` catalog. A valid existing model is preserved untouched. An **invalid** existing model (e.g. left over from an older release) triggers an interactive rewrite/keep prompt; in non-interactive mode, the invalid value is left in place with a loud warning so you can fix it manually. The catalog is fetched once per 24 hours and cached at `~/.config/claudekit/cache/models-dev.json`. #### Why the default isn't `anthropic/...` anymore Earlier releases hardcoded an Anthropic default (`anthropic/claude-sonnet-4-6`). For users authenticated only with OpenCode Zen (qwen, glm, kimi, etc.), that default triggered `ProviderModelNotFoundError` at sub-agent invocation because the user has no Anthropic provider configured. The migration now derives the default from your actual auth state instead of guessing. #### Override via `.ck.json` If you want to pin a specific default: ```json { "taxonomy": { "opencode": { "default": { "model": "opencode/glm-4.7-free" } } } } ``` This wins over auto-detection. ## Rollback on Failure If some items fail while others succeed, the command offers a rollback option: - **New writes** are removed - **Overwritten files** are preserved (cannot be rolled back) - Registry entries are cleaned up ## Related Commands - [ck init](/docs/cli/init) — Initialize or update ClaudeKit - [ck uninstall](/docs/cli/uninstall) — Remove ClaudeKit installations - [ck doctor](/docs/cli/doctor) — Diagnose installation issues --- # Content Automation Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/content-automation # Content Automation > Daemon that monitors git repositories, generates AI-powered social media content, and publishes to X (Twitter) and Facebook automatically. ## Quick Start ```bash # Interactive onboarding setup ck content setup # Start the daemon ck content start # Check daemon status ck content status # View recent logs ck content logs --tail # Approve pending content ck content approve # Stop the daemon ck content stop ``` ## Subcommands | Subcommand | Purpose | Key Options | |------------|---------|-------------| | `start` | Launch the scan→create→review→publish cycle | `--force`, `--verbose`, `--dry-run` | | `stop` | Graceful shutdown via SIGTERM | — | | `status` | Show running state, config, last scan time | — | | `logs` | View or follow today's log file | `--tail` | | `setup` | Interactive onboarding — platforms, credentials, schedule | — | | `queue` | List content items pending review | — | | `approve ` | Approve content item for publishing | — | | `reject ` | Reject content item | `--reason ` | ## Architecture The daemon runs a six-phase loop on each poll cycle: 1. **Git Scanner** — Detects commits, merged PRs, tags, releases, and plan completions across monitored repos 2. **Content Creator** — Sends event details to Claude CLI, parses JSON response with 4-strategy fallback 3. **Review Manager** — Applies review mode (auto/manual/hybrid) and checks daily post limits 4. **Publisher** — Posts to X via `xurl` CLI or Facebook via Graph API v21.0 5. **Engagement Tracker** — Polls likes, shares, comments, and impressions on published posts 6. **Self-Improvement** — Extracts patterns from top-performing posts to refine future prompts State is persisted to `~/.claudekit/content.state.json` after each phase and on shutdown. ## Configuration Configure via `.ck.json` in your project root: ```json { "content": { "enabled": true, "pollIntervalMs": 60000, "reviewMode": "hybrid", "maxContentPerDay": 10, "platforms": { "x": { "enabled": true, "maxPostsPerDay": 5, "threadMaxParts": 6 }, "facebook": { "enabled": true, "pageId": "YOUR_PAGE_ID", "maxPostsPerDay": 3 } }, "schedule": { "timezone": "UTC", "quietHoursStart": "23:00", "quietHoursEnd": "06:00" }, "selfImprovement": { "enabled": true, "engagementCheckIntervalHours": 6, "topPerformingCount": 10 } } } ``` ## Review Modes ### Auto Publishes immediately after generation. Useful for testing: ```bash ck content start # Content publishes without approval ``` ### Manual Requires explicit approval for every item: ```bash ck content queue # List pending items ck content approve 42 # Approve item ck content reject 42 --reason "Too promotional" ``` ### Hybrid (Recommended) Auto-publishes high-confidence content (score > 85%), holds uncertain items for manual review. Confidence is scored on keyword relevance, length, and grammar. ## Platform Adapters ### X / Twitter **Requirements:** `xurl` CLI installed and authenticated. - Checks daily post limit and quiet hours before publishing - Supports threads: splits long content into up to 6 reply-chained parts - Captures post ID and URL, stores in `publications` table ### Facebook **Requirements:** Page Access Token with `pages_manage_metadata` scope, Page ID in config. - Posts via Graph API v21.0 (`POST /me/feed`) - Supports message, picture URL, and link - Rate limited to configured `maxPostsPerDay` with exponential backoff on 429s ## Git Events Detected | Event Type | Trigger | |------------|---------| | `commit` | New commits since last scan | | `pr_merged` | Pull requests merged (GitHub API) | | `plan_completed` | Updates to `.claude/plans/` directory | | `tag` | New git tags | | `release` | GitHub releases published | Events are scored for content-worthiness using keywords (`feature`, `fix`, `breaking`, `release`), PR size, and author reputation. Already-processed event IDs are tracked to prevent duplicates. ## Security - **PID lock** at `~/.claudekit/locks/ck-content.lock` prevents multiple daemon instances - **No token logging** — platform credentials never written to logs or CLI output - **Database** at `~/.claudekit/content.db` uses WAL mode and `0600` permissions - **State writes** are atomic to prevent partial updates on crash ## Troubleshooting ```bash # Daemon won't start — check stale lock ls ~/.claudekit/locks/ck-content.lock ck content start --force # Content not generating — verify Claude CLI which ck echo "Hello" | ck --stream # Publishing failures — check platform CLIs which xurl && xurl status # X/Twitter # Facebook: verify token has pages_manage_metadata scope ``` ## Related - [Watch - Issue Auto-Responder](/docs/cli/watch) — GitHub issue automation - [System Architecture](/docs/cli/architecture) — CLI technical design - [Configuration](/docs/cli/configuration) — Global CLI config reference --- # ck watch Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/watch # ck watch Autonomous long-running GitHub issue monitor. Polls issues, brainstorms with Claude, generates plans, waits for owner approval, then auto-implements via PR. ## Overview `ck watch` turns your terminal into an overnight AI assistant. It continuously monitors GitHub issues for a repository (or multiple repos), uses Claude to analyze and plan solutions, posts the plan as a comment, and — once the repo owner approves — creates a branch, implements the fix, and opens a PR. Designed for 6-8+ hour unattended operation. ## Syntax ```bash ck watch [options] ``` ### Options | Flag | Default | Description | |------|---------|-------------| | `--interval ` | `30000` | Poll interval in milliseconds | | `--dry-run` | `false` | Detect issues and log actions, but never post to GitHub | | `--force` | `false` | Kill any existing `ck watch` process and start fresh | | `--verbose` | `false` | Enable debug output | ## Prerequisites - **GitHub CLI** (`gh`) installed and authenticated - **Git** repository (or directory containing git repos for multi-repo mode) - **Node.js 18+** / Bun runtime - **ClaudeKit Engineer** installed in the project ## How It Works ### Issue Lifecycle Every issue goes through a defined lifecycle: ``` new → brainstorming → clarifying → planning → plan_posted → awaiting_approval → implementing → completed ``` ### Step-by-Step Flow 1. **Poll** — Fetches open issues from GitHub via `gh` CLI 2. **Brainstorm** — Invokes Claude to analyze the issue, ask clarifying questions 3. **Clarify** — If Claude needs more info, posts questions as a comment and waits for the author's reply 4. **Plan** — Once the problem is understood, Claude generates an implementation plan 5. **Post Plan** — Posts the plan as a GitHub comment, transitions to `awaiting_approval` 6. **Approval** — Monitors for the repo owner's approval comment (uses Claude to detect approval intent) 7. **Implement** — Creates a branch, runs `ck cook` with the plan, pushes code 8. **PR** — Opens a pull request linking the original issue 9. **Complete** — Posts a completion comment with the PR link ### Single-Repo vs Multi-Repo - **Single-repo**: Run `ck watch` inside a git repository. Monitors that repo's issues. - **Multi-repo**: Run `ck watch` in a parent directory containing multiple git repos. Discovers and monitors all sub-repos. ## Configuration Stored in `.ck.json` under the `watch` key: ```json { "watch": { "pollIntervalMs": 30000, "maxTurnsPerIssue": 10, "maxIssuesPerHour": 10, "excludeAuthors": [], "showBranding": true, "logMaxBytes": 0, "timeouts": { "brainstormSec": 300, "planSec": 600, "implementSec": 18000 } } } ``` | Key | Default | Description | |-----|---------|-------------| | `pollIntervalMs` | `30000` | How often to check for new issues (min 10s) | | `maxTurnsPerIssue` | `10` | Max conversation turns before giving up | | `maxIssuesPerHour` | `10` | Rate limit for new issue processing | | `excludeAuthors` | `[]` | GitHub usernames to ignore | | `showBranding` | `true` | Include ClaudeKit branding in posted comments | | `logMaxBytes` | `0` | Log file size limit (0 = unlimited) | | `timeouts.brainstormSec` | `300` | Brainstorm phase timeout (5 min) | | `timeouts.planSec` | `600` | Plan generation timeout (10 min) | | `timeouts.implementSec` | `18000` | Implementation timeout (5 hours) | ## Examples ### Basic Usage ```bash # Start watching current repo ck watch # Custom poll interval (60 seconds) ck watch --interval 60000 # Test without posting to GitHub ck watch --dry-run # Restart if already running ck watch --force ``` ### Overnight Workflow ```bash # Start watch before leaving for the night ck watch --verbose 2>&1 | tee watch-session.log # Next morning: check what happened cat ~/.claudekit/logs/ck-watch-*.log ``` ### Multi-Repo Setup ```bash # Directory structure: # ~/projects/ # ├── api-server/ (git repo) # ├── web-frontend/ (git repo) # └── shared-utils/ (git repo) cd ~/projects ck watch # Monitors all 3 repos simultaneously ``` ## Security Features - **Process Lock** — Only one `ck watch` instance can run at a time (`~/.claudekit/locks/ck-watch.lock`) - **Credential Scanning** — Blocks posting if secrets are detected in generated content - **Input Sanitization** — Truncates input to 8K characters, strips injection patterns - **Own-Comment Detection** — Uses HTML markers (``) to avoid responding to its own comments - **Mention Stripping** — Removes `@mentions` from AI output to prevent unwanted notifications - **stdin-Only Claude** — Passes prompts via stdin, never as command-line arguments ## State Persistence Runtime state is saved to `.ck.json` under `watch.state`: - Active issues with their current lifecycle status - Conversation history (capped at 10 messages per issue) - Implementation queue (approved issues waiting to be implemented) - Processed issues list (capped at 500 to prevent unbounded growth) On graceful shutdown (`Ctrl+C`), in-progress issues revert to safe states so they can be resumed on next run. ## Logging Log files are written to `~/.claudekit/logs/`: ``` ~/.claudekit/logs/ck-watch-20260327.log ``` Logs include timestamps, log levels, and structured context for each action. ## Troubleshooting ### "Watch daemon already running" Another `ck watch` process is active. Use `--force` to kill it and restart: ```bash ck watch --force ``` ### Issues not being picked up - Verify `gh` authentication: `gh auth status` - Check the repo has open issues: `gh issue list` - Review excluded authors in `.ck.json` ### Implementation fails - Check `timeouts.implementSec` — complex issues may need more than 5 hours - Review the log file for error details - The issue will revert to `awaiting_approval` so you can retry ### Comments not posted - Ensure `gh` has write permissions to the repository - Check `--dry-run` is not enabled - Review logs for credential scanning blocks ## When to Use - **Overnight processing** — Queue up issues before bed, wake up to PRs - **Continuous triage** — Let Claude brainstorm and plan while you focus on other work - **Multi-repo monitoring** — Watch all your team's repos from a single terminal - **Hackathon mode** — Rapid prototyping with AI-assisted implementation ## Limitations - Sequential implementation only (one issue at a time) - Requires repo owner approval for each implementation - GitHub API rate limits apply via `gh` CLI - Claude CLI must be available and authenticated ## Related - [CLI Overview](/docs/cli) - [ck content](/docs/cli/content) — Autonomous content creation from git activity --- # ck content Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/content # ck content Autonomous content creation daemon. Scans git activity (commits, PRs, releases), generates platform-specific social media posts with Claude, and publishes to X/Twitter and Facebook. ## Overview `ck content` is a background daemon that turns your development activity into social media content. It monitors git events across your repositories, uses Claude to craft engaging posts tailored to each platform, and publishes them on a configurable schedule. Supports review workflows (auto, manual, hybrid) and tracks engagement metrics for self-improvement. ## Syntax ```bash ck content [options] ``` ### Subcommands | Command | Description | |---------|-------------| | `ck content start` | Launch the content daemon | | `ck content stop` | Stop a running daemon | | `ck content status` | Show daemon state, config summary, and last scan time | | `ck content logs` | Print today's content log | | `ck content setup` | Interactive onboarding wizard for platform configuration | | `ck content queue` | List pending review items | | `ck content approve ` | Approve a content item for publishing | | `ck content reject [reason]` | Reject a content item | ### Global Options | Flag | Default | Description | |------|---------|-------------| | `--dry-run` | `false` | Generate content but never publish | | `--verbose` | `false` | Enable debug output | | `--force` | `false` | Kill existing daemon and start fresh | | `--tail` | `false` | Follow log output in real-time (for `logs` subcommand) | ## Prerequisites - **GitHub CLI** (`gh`) installed and authenticated - **Git** repository (or directory containing git repos) - **Platform API credentials** configured via `ck content setup`: - X/Twitter: API key, API secret, access token, access secret - Facebook: Page access token, Page ID ## How It Works ### Content Pipeline ``` Git Scan → Event Classification → Content Creation → Review → Publish → Engage ``` ### Step-by-Step Flow 1. **Git Scan** — Scans repositories for new commits, merged PRs, tags, releases, and completed plans 2. **Event Classification** — Filters noise, classifies events by importance (high/medium/low) 3. **Content Creation** — Claude generates platform-specific posts with hashtags, hook lines, and CTAs 4. **Review** — Based on `reviewMode`: - `auto` — Publishes immediately if quality checks pass - `manual` — Queues for human approval via `ck content queue/approve/reject` - `hybrid` — Auto-publishes high-confidence content, queues borderline items 5. **Publish** — Posts to enabled platforms respecting rate limits and quiet hours 6. **Engagement Tracking** — Periodically checks post performance and feeds insights back into content generation ### Supported Git Events | Event Type | Trigger | Example | |-----------|---------|---------| | `commit` | New commits on default branch | Feature commits, bug fixes | | `pr_merged` | Pull request merged | Feature PRs, dependency updates | | `tag` | New git tag created | Version releases | | `release` | GitHub release published | Major releases | | `plan_completed` | ClaudeKit plan marked done | Milestone completions | ### Supported Platforms | Platform | Post Types | Limits | |----------|-----------|--------| | **X/Twitter** | Single posts, threads (up to 6 parts) | 280 chars/post, configurable max posts/day | | **Facebook** | Page posts | Configurable max posts/day | ## Configuration Stored in `.ck.json` under the `content` key: ```json { "content": { "enabled": false, "pollIntervalMs": 60000, "platforms": { "x": { "enabled": false, "maxPostsPerDay": 5, "threadMaxParts": 6 }, "facebook": { "enabled": false, "maxPostsPerDay": 3 } }, "reviewMode": "auto", "schedule": { "timezone": "UTC", "quietHoursStart": "23:00", "quietHoursEnd": "06:00" }, "selfImprovement": { "enabled": true, "engagementCheckIntervalHours": 6, "topPerformingCount": 10 }, "firstScanLookbackDays": 30, "maxContentPerDay": 10, "contentDir": "~/.claudekit/content/", "dbPath": "~/.claudekit/content.db" } } ``` ### Key Configuration Options | Key | Default | Description | |-----|---------|-------------| | `enabled` | `false` | Master switch (set via `ck content setup`) | | `pollIntervalMs` | `60000` | Git scan interval (1 minute) | | `reviewMode` | `auto` | Content approval mode: `auto`, `manual`, `hybrid` | | `schedule.timezone` | `UTC` | Timezone for quiet hours | | `schedule.quietHoursStart` | `23:00` | No publishing after this time | | `schedule.quietHoursEnd` | `06:00` | Resume publishing after this time | | `firstScanLookbackDays` | `30` | Days to scan on first run | | `maxContentPerDay` | `10` | Global daily post limit across all platforms | | `selfImprovement.enabled` | `true` | Learn from engagement metrics | ## Examples ### Getting Started ```bash # Interactive setup — configure platforms and API keys ck content setup # Start the daemon ck content start # Check status ck content status ``` ### Manual Review Workflow ```bash # Set reviewMode to "manual" in .ck.json, then: ck content start # Check pending content ck content queue # Approve or reject ck content approve 42 ck content reject 43 "Too promotional" ``` ### Monitoring ```bash # View today's logs ck content logs # Follow logs in real-time ck content logs --tail # Test without publishing ck content start --dry-run --verbose ``` ### Daemon Management ```bash # Stop the daemon ck content stop # Force restart ck content start --force ``` ## Content Lifecycle Each piece of content flows through these states: ``` draft → scheduled → reviewing → approved → publishing → published → failed (retries up to 3x within 24h) ``` ## Database Content data is stored in a SQLite database at `~/.claudekit/content.db`: - **git_events** — Tracked git activity with importance classification - **content_items** — Generated posts with platform, text, hashtags, status - **publications** — Published post references (post ID, URL, timestamp) Data retention cleanup runs automatically every 24 hours. ## Security - **Process Lock** — Only one daemon instance at a time (`~/.claudekit/locks/ck-content.lock`) - **Credential Isolation** — Platform API keys stored separately, never in git - **Rate Limiting** — Per-platform daily limits and configurable quiet hours - **Retry Protection** — Failed content creation retries max 3 times, failed publishing retries within 24h window ## Troubleshooting ### "Content engine not enabled" Run the setup wizard first: ```bash ck content setup ``` ### "Content daemon already running" Stop or force-restart: ```bash ck content stop # or ck content start --force ``` ### Posts not publishing - Verify platform API credentials via `ck content setup` - Check quiet hours in config — posts won't publish during quiet hours - Review `maxPostsPerDay` limits - Check logs: `ck content logs --tail` ### No content generated - Ensure the repo has recent git activity - Check `firstScanLookbackDays` if this is the first run - Review event classification in logs — some events may be filtered as noise ## When to Use - **Developer advocacy** — Auto-share your team's shipping velocity - **Open source projects** — Keep followers updated on releases and features - **Changelog broadcasting** — Turn releases into social announcements - **Content marketing** — Generate draft posts from development activity ## Limitations - Platforms currently limited to X/Twitter and Facebook - Requires platform API keys (developer accounts) - Content quality depends on git commit message quality - Self-improvement requires sufficient published post history ## Related - [CLI Overview](/docs/cli) - [ck watch](/docs/cli/watch) — Autonomous GitHub issue monitor --- # System Architecture Section: cli Category: N/A URL: https://docs.claudekit.cc/docs/cli/architecture # System Architecture > ClaudeKit CLI uses modular domain-driven design with facade patterns. Concerns are separated into CLI infrastructure, phase-handler commands, domain business logic, cross-domain services, and pure utilities. ## Layer Overview ``` ┌────────────────────────────────────┐ │ User Interface (CLI/Terminal) │ └───────────────┬────────────────────┘ │ ┌───────────────▼────────────────────┐ │ CLI Layer (config, registry) │ └───────────────┬────────────────────┘ │ ┌───────────────▼────────────────────┐ │ Commands (init, new, skills, etc.) │ │ + 3–8 phase handlers per command │ └───────────────┬────────────────────┘ │ ┌───────────────▼────────────────────┐ │ Domains (config, github, skills, │ │ health-checks, installation, ui, │ │ versioning, help) │ └───────────────┬────────────────────┘ │ ┌───────────────▼────────────────────┐ │ Services (file-ops, pkg-installer, │ │ transformers, manifest operations) │ └───────────────┬────────────────────┘ │ ┌───────────────▼────────────────────┐ │ Shared Utils (logger, path- │ │ resolver, safe-prompts, terminal) │ └────────────────────────────────────┘ ``` ## Architectural Patterns ### Facade Pattern Each domain exposes a single facade file that re-exports its public API, hides internal submodules, and provides a backward-compatible interface as the domain grows. ### Phase Handler Pattern Complex commands use an orchestrator coordinating discrete phase handlers. Each handler owns one responsibility (~50–100 LOC) and is independently testable. - **`init`** — 8 phases: options-resolver, selection-handler, download-handler, migration-handler, merge-handler, conflict-handler, transform-handler, post-install-handler - **`new`** — 3 phases: directory-setup, project-creation, post-setup ### Context-Driven Flow Each command maintains a context object threaded through all phases. Shared state enables atomic operations and rollback on failure. ## Domains | Domain | Responsibility | |--------|---------------| | `config/` | Config generator, manager, validator; settings merger with conflict resolution | | `github/` | Octokit wrapper for releases and auth (GitHub CLI only); asset selection with fallback | | `health-checks/` | Parallel checkers for system, auth, GitHub API, ClaudeKit, platform, network; auto-healer | | `installation/` | Streaming downloader; ZIP/TAR extraction with path-traversal and 500MB bomb protection; selective merger | | `skills/` | Detection, customization scanning, migration with backup and rollback | | `ui/` | Prompts for kit/version selection; ownership display for multi-kit installs | | `versioning/` | Version checker with 7-day cache; kit version UI with beta filtering | | `help/` | Custom renderer with theme support and `NO_COLOR` compliance | ## Services | Service | Responsibility | |---------|---------------| | `file-operations/` | Manifest reader/writer with multi-kit support; file ownership tracker | | `package-installer/` | Node, Python, and system dependency installation; Gemini MCP linker | | `transformers/` | `/ck:` command prefix applier; folder path transformer for directory renaming | ## Idempotent Migration (`ck migrate`) Migration follows a 3-phase reconciliation pipeline safe for repeated execution: 1. **RECONCILE** — Pure function (`reconciler.ts`), zero I/O. Produces a `ReconcilePlan` from source items + registry + target state + manifest. 8-case decision matrix: install, update, skip, conflict, delete, rename, path-migration, shared-skip. 2. **EXECUTE** — Applies plan actions. Interactive conflict resolution with diff preview. Updates Registry v3.0 with new SHA-256 checksums. 3. **REPORT** — Terraform-style plan display. Dashboard summary via API. **Key invariants:** Reconciler is pure — all I/O stays in callers. Registry tracks both source and target checksums. Skills are directory-based and excluded from file-level orphan detection. Manifest paths validated via `safeRelativePath` (no traversal, no empty strings). Migration lock (30s timeout) prevents concurrent registry corruption. ## Security Model ### Path Traversal Prevention - Canonical path resolution on all archive extraction - Reject paths containing `..` - Verify resolved target is within expected base directory ### Archive Bomb Prevention - Maximum extraction size: 500MB - Path validation during streaming extraction - Size checked incrementally, not post-extract ### Authentication - GitHub CLI only — no raw token prompts - OS keychain integration for secure storage - Token sanitization in all log output - Format validation (`ghp_*`, `github_pat_*`) ### Protected Files (always skipped) `.env`, `.env.local`, `*.key`, `*.pem`, `node_modules/`, `.git/`, `dist/`, `build/`, `CLAUDE.md`, `.mcp.json` ## Multi-Kit Architecture The installer supports side-by-side Engineer + Marketing kit installs: - **Selective Merger** — Hybrid size+checksum comparison. Detects shared files, prevents overwriting newer cross-kit versions. - **Copy Executor** — Tracks shared files across kits via `setMultiKitContext()`. - **Manifest Reader** — `findFileInInstalledKits()` locates any file across all installed kits; `getUninstallManifest()` handles kit-scoped removal with shared-file detection. ## Shared Utilities | Module | Purpose | |--------|---------| | `logger.ts` | Structured logging with automatic token sanitization | | `environment.ts` | Platform detection and concurrency tuning | | `path-resolver.ts` | XDG-compliant cross-platform path resolution | | `process-lock.ts` | PID locking with 1-min stale timeout and global exit handler | | `safe-prompts.ts` | CI-safe prompt wrappers (non-TTY detection) | | `safe-spinner.ts` | Non-TTY safe spinner output | ## Performance - **Streaming downloads** — no full-file memory buffering - **Parallel release fetching** and version checks - **In-memory token caching** across requests - **SHA-256 hashing** for change detection without full file reads - **Release cache** — 1hr TTL (configurable via `CK_CACHE_TTL`) - **Version check cache** — 7-day TTL - **Max extraction** — 500MB enforced during streaming ## Error Handling Structured error classes with user-friendly messages and stack traces in `--verbose` mode. Recovery mechanisms: - Asset download failure → fallback to tarball - Migration failure → restore from backup - Temp directory cleaned on any error path - Non-TTY detection prevents hanging prompts ## Integration Points - **GitHub API** (Octokit) — releases and repositories - **GitHub CLI** (`gh`) — authentication - **OS Keychain** — secure token storage - **npm Registry** — package distribution **File system paths:** - Local config: `~/.claudekit/config.json` - Global kits: `~/.claude/` - Skills manifest: `.claude/skills/.skills-manifest.json` - Skills backups: `.claude/backups/skills/` ## Related - [Installation](/docs/cli/installation) — Setup guide - [Configuration](/docs/cli/configuration) — Config reference - [Content Automation](/docs/cli/content-automation) — Content daemon architecture - [Watch - Issue Auto-Responder](/docs/cli/watch) — Watch daemon architecture --- # API Keys Management Section: docs Category: keys URL: https://docs.claudekit.cc/docs/keys/api-keys # API Keys Management Manage your API keys for authenticating with ClaudeKit services. ## Create API Key ``` POST /api/keys ``` **Auth:** Session cookie (logged-in user) **Request:** ```json { "name": "My API Key" } ``` **Response (201):** ```json { "id": "uuid", "key": "ck_live_xxxx...", "name": "My API Key", "message": "Save this key securely. It will not be shown again." } ``` **Errors:** 400 (name required, 1-100 chars), 401 (unauthorized), 403 (license required) ## List API Keys ``` GET /api/keys ``` **Auth:** Session cookie. Admin can use `?viewAs={userId}`. **Response (200):** ```json { "keys": [{ "id": "uuid", "name": "My API Key", "prefix": "ck_live", "keyPreview": "ck_live...****", "rateLimit": 1000, "isActive": true, "lastUsedAt": "2024-01-01T00:00:00Z", "usageCount": 150, "expiresAt": null, "createdAt": "2024-01-01T00:00:00Z" }] } ``` ## Get API Key Details ``` GET /api/keys/{id} ``` **Response (200):** ```json { "key": { "id": "uuid", "name": "My API Key", "prefix": "ck_live", "rateLimit": 1000, "isActive": true, "rotatedAt": null, "gracePeriodEndsAt": null, "lastUsedAt": "2024-01-01T00:00:00Z", "usageCount": 150, "expiresAt": null, "createdAt": "2024-01-01T00:00:00Z" } } ``` ## Delete API Key ``` DELETE /api/keys/{id} ``` **Response (200):** ```json { "success": true } ``` ## Rotate API Key ``` POST /api/keys/{id}/rotate ``` Generates a new key with a 24-hour grace period for the old key. **Response (200):** ```json { "key": "ck_live_new_xxxx...", "message": "New key created. Old key valid for 24 hours (grace period).", "gracePeriodHours": 24 } ``` **Errors:** 400 (cannot rotate inactive key), 404 (key not found) ## Revoke API Key ``` POST /api/keys/{id}/revoke ``` Immediately invalidates the key with no grace period. **Response (200):** ```json { "success": true, "message": "API key revoked immediately. No grace period." } ``` ## Get Usage Statistics ``` GET /api/keys/{id}/usage?days=7 ``` **Query:** `days` (1-30, default 7) **Response (200):** ```json { "dailyUsage": [{ "date": "2024-01-01", "count": 50 }], "totalUsageCount": 500, "rateLimit": { "limit": 1000, "used": 25, "remaining": 975, "windowHours": 1 } } ``` ## Validate API Key ``` POST /api/keys/validate ``` **Headers:** `X-API-Key` or `Authorization: Bearer` **Response (200):** ```json { "valid": true, "userId": "uuid", "rateLimit": 1000, "isActive": true } ``` **Response (401):** ```json { "valid": false, "error": "Invalid or expired API key" } ``` ## Key Security - Keys are stored as SHA-256 hashes with AES-256-GCM encryption - Key prefix `ck_live_` is stored separately for display - Full key is shown only once at creation time - Use [key rotation](/docs/api/keys/api-keys#rotate-api-key) for zero-downtime key cycling - Rate limits are enforced via Redis sliding window (1-hour window) ## Next Steps - [Authentication](/docs/api/overview/authentication) - Auth methods and error codes - [VidCap API](/docs/api/vidcap/youtube-processing) - Video processing - [ReviewWeb API](/docs/api/reviewweb/web-scraping) - Web scraping --- # API Introduction Section: docs Category: overview URL: https://docs.claudekit.cc/docs/overview/introduction # ClaudeKit API > AI-powered API services through a unified proxy layer. Access video processing and web scraping/SEO capabilities via two integrated services. ## Overview ClaudeKit API provides access to two powerful services: | Service | Description | Capabilities | |---------|-------------|-------------| | **VidCap** | YouTube video processing | Metadata, captions, AI summaries, screenshots, search | | **ReviewWeb** | Web scraping & SEO | Scraping, content extraction, markdown conversion, SEO analysis | ## Base URL ``` https://claudekit.cc ``` All API requests go through the unified proxy layer at `/api/proxy/{service}/{path}`. ## Available Services ### VidCap - Video Processing AI-powered YouTube video analysis: - **Video Info** - Get metadata (title, duration, thumbnail) - **Captions** - Extract transcripts in multiple languages - **AI Summaries** - Generate summaries with custom prompts - **Screenshots** - Capture frames at specific timestamps - **Search** - Search YouTube videos programmatically - **Comments** - Retrieve video comments ### ReviewWeb - Web Scraping & SEO Comprehensive web scraping and SEO toolkit: - **Web Scraping** - Scrape single or multiple URLs - **Content Extraction** - Extract main content from pages - **Markdown Conversion** - Convert webpages to markdown - **AI Summaries** - Summarize web content with AI - **SEO Insights** - Backlinks, keyword analysis, traffic metrics - **URL Utilities** - Check URL status, resolve redirects ## Quick Start ### 1. Get Your API Key Create an API key from the [API Keys Dashboard](https://claudekit.cc/dashboard/api-keys). ### 2. Make Your First Request ```bash curl -H "X-API-Key: ck_live_your_key" \ "https://claudekit.cc/api/proxy/vidcap/v1/youtube/info?url=https://youtube.com/watch?v=dQw4w9WgXcQ" ``` ### 3. Explore the Docs - [Authentication & Error Codes](/docs/api/overview/authentication) - Auth methods, errors, rate limits - [API Keys Management](/docs/api/keys/api-keys) - Create, rotate, revoke keys - [VidCap API](/docs/api/vidcap/youtube-processing) - YouTube video processing - [ReviewWeb API](/docs/api/reviewweb/web-scraping) - Web scraping & extraction ## Proxy Service Format ``` GET/POST /api/proxy/{service}/{path} ``` **Headers:** `X-API-Key: your_key` or `Authorization: Bearer your_key` **List available services:** ```bash GET /api/proxy/services ``` ```json { "services": [ { "id": "vidcap", "name": "VidCap.xyz", "baseUrl": "https://vidcap.xyz/api", "timeout": 120000 }, { "id": "reviewweb", "name": "ReviewWeb.site", "baseUrl": "https://reviewweb.site/api", "timeout": 120000 } ] } ``` ## Next Steps - [Authentication](/docs/api/overview/authentication) - Set up authentication - [API Keys](/docs/api/keys/api-keys) - Manage your API keys - [VidCap](/docs/api/vidcap/youtube-processing) - Start processing videos - [ReviewWeb](/docs/api/reviewweb/web-scraping) - Start scraping the web --- # Authentication & Error Codes Section: docs Category: overview URL: https://docs.claudekit.cc/docs/overview/authentication # Authentication & Error Codes ## Authentication All API requests require authentication via one of two methods: ### API Key Header (Preferred) ```bash curl -H "X-API-Key: ck_live_your_key" \ "https://claudekit.cc/api/proxy/vidcap/v1/youtube/info?url=..." ``` ### Bearer Token ```bash curl -H "Authorization: Bearer ck_live_your_key" \ "https://claudekit.cc/api/proxy/vidcap/v1/youtube/info?url=..." ``` ### Getting an API Key 1. Log in to [ClaudeKit](https://claudekit.cc) 2. Go to [API Keys Dashboard](https://claudekit.cc/dashboard/api-keys) 3. Click "Create API Key" 4. Save the key securely (shown only once) API keys use the format `ck_live_` followed by 32 random characters. ## Error Codes | Code | HTTP Status | Description | |------|-------------|-------------| | `MISSING_API_KEY` | 401 | No API key provided in request headers | | `INVALID_API_KEY` | 401 | API key is invalid or expired | | `KEY_EXPIRED` | 401 | API key has expired | | `KEY_REVOKED` | 401 | API key has been revoked | | `LICENSE_REQUIRED` | 403 | Active ClaudeKit license required | | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests, retry after cooldown | | `INVALID_PATH` | 400 | Invalid proxy path format | | `UNKNOWN_SERVICE` | 404 | Requested service not found | ### Error Response Format ```json { "error": "INVALID_API_KEY", "message": "The provided API key is invalid or has expired" } ``` ## Rate Limits API requests are rate-limited per API key. Limits are communicated via response headers. ### Response Headers | Header | Description | |--------|-------------| | `X-RateLimit-Limit` | Maximum requests per hour | | `X-RateLimit-Remaining` | Requests remaining in current window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | ### Rate Limit Exceeded When rate limited, you receive a `429` response: ```json { "error": "RATE_LIMIT_EXCEEDED", "retryAfter": 120 } ``` The `retryAfter` field indicates seconds to wait before retrying. ### Default Limits | Plan | Requests/Hour | |------|--------------| | Standard | 1,000 | | Premium | 10,000 | ### Best Practices - **Cache responses** when possible to reduce API calls - **Implement exponential backoff** for retries on rate limit errors - **Monitor usage** via the [API Keys Dashboard](https://claudekit.cc/dashboard/api-keys) - **Use key rotation** to cycle keys without downtime ## Next Steps - [API Keys Management](/docs/api/keys/api-keys) - Create and manage keys - [VidCap API](/docs/api/vidcap/youtube-processing) - Video processing endpoints - [ReviewWeb API](/docs/api/reviewweb/web-scraping) - Web scraping endpoints --- # ReviewWeb - Web Scraping Section: docs Category: reviewweb URL: https://docs.claudekit.cc/docs/reviewweb/web-scraping # ReviewWeb - Web Scraping & Extraction Comprehensive web scraping, content extraction, and conversion service. **Base path:** `/api/proxy/reviewweb/v1` ## Health Check ``` GET /api/proxy/reviewweb/v1/healthz ``` ## Account Profile ``` GET /api/proxy/reviewweb/v1/profile ``` Get account profile and usage statistics. ## Web Scraping ### Scrape Single URL ``` POST /api/proxy/reviewweb/v1/scrape ``` ```json { "url": "https://example.com", "waitFor": "networkidle", "timeout": 30000 } ``` Returns raw HTML content of the page. ### Scrape Multiple URLs ``` POST /api/proxy/reviewweb/v1/scrape/urls ``` ```json { "urls": ["https://example.com", "https://another.com"] } ``` ### Links Map ``` POST /api/proxy/reviewweb/v1/scrape/links-map ``` ```json { "url": "https://example.com", "depth": 1 } ``` Extract all links from a page with configurable crawl depth. ## Content Extraction ### Extract Content ``` POST /api/proxy/reviewweb/v1/extract ``` ```json { "url": "https://example.com" } ``` Extract main content (title, text, images) from a page. ### Extract Multiple ``` POST /api/proxy/reviewweb/v1/extract/urls ``` ```json { "urls": ["https://example.com", "https://another.com"] } ``` ## Markdown Conversion ### Convert to Markdown ``` POST /api/proxy/reviewweb/v1/convert/markdown ``` ```json { "url": "https://example.com" } ``` Convert any webpage to clean, LLM-friendly markdown. ### Convert Multiple ``` POST /api/proxy/reviewweb/v1/convert/markdown/urls ``` ```json { "urls": ["https://example.com", "https://another.com"] } ``` ## Screenshots ### Take Screenshot ``` POST /api/proxy/reviewweb/v1/screenshot ``` ```json { "url": "https://example.com", "fullPage": false, "width": 1920, "height": 1080 } ``` ### Get Screenshot ``` GET /api/proxy/reviewweb/v1/screenshot/{id} ``` Retrieve a previously taken screenshot by ID. ## Website Review ### Create Review ``` POST /api/proxy/reviewweb/v1/review ``` ```json { "url": "https://example.com" } ``` Generate a comprehensive website review. ### Get Review ``` GET /api/proxy/reviewweb/v1/review/{reviewId} ``` ## Next Steps - [SEO Analysis](/docs/api/reviewweb/seo-analysis) - Backlinks, keywords, traffic - [VidCap API](/docs/api/vidcap/youtube-processing) - Video processing - [API Keys](/docs/api/keys/api-keys) - Manage keys --- # ReviewWeb - SEO Analysis Section: docs Category: reviewweb URL: https://docs.claudekit.cc/docs/reviewweb/seo-analysis # ReviewWeb - SEO & AI Analysis AI-powered content summarization, SEO insights, and URL utilities. **Base path:** `/api/proxy/reviewweb/v1` ## AI Summaries ### Summarize URL ``` POST /api/proxy/reviewweb/v1/summarize/url ``` ```json { "url": "https://example.com", "model": "gemini-1.5-flash" } ``` AI-summarize a single URL's content. ### Summarize Website ``` POST /api/proxy/reviewweb/v1/summarize/website ``` ```json { "url": "https://example.com", "depth": 2, "model": "gemini-1.5-flash" } ``` Summarize an entire website by crawling pages up to the specified depth. ### Summarize Multiple URLs ``` POST /api/proxy/reviewweb/v1/summarize/urls ``` ```json { "urls": ["https://example.com", "https://another.com"], "model": "gemini-1.5-flash" } ``` ### Available AI Models ``` GET /api/proxy/reviewweb/v1/ai/models ``` List available AI models for summaries. ## SEO Insights ### Backlinks Analysis ``` POST /api/proxy/reviewweb/v1/seo-insights/backlinks ``` ```json { "domain": "example.com" } ``` Analyze domain backlink profile including referring domains, anchor text distribution, and link quality. ### Keyword Ideas ``` POST /api/proxy/reviewweb/v1/seo-insights/keyword-ideas ``` ```json { "keyword": "ai tools", "country": "US" } ``` Generate keyword suggestions based on a seed keyword with search volume and competition data. ### Keyword Difficulty ``` POST /api/proxy/reviewweb/v1/seo-insights/keyword-difficulty ``` ```json { "keyword": "ai tools", "country": "US" } ``` Get difficulty score for ranking on a specific keyword (0-100 scale). ### Traffic Analysis ``` POST /api/proxy/reviewweb/v1/seo-insights/traffic ``` ```json { "domain": "example.com" } ``` Analyze domain traffic metrics including estimated monthly visits, traffic sources, and trends. ## URL Utilities ### Check URL Status ``` POST /api/proxy/reviewweb/v1/url/is-alive ``` ```json { "url": "https://example.com" } ``` Check if a URL is accessible and returns a valid response. ### Resolve Redirects ``` POST /api/proxy/reviewweb/v1/url/get-url-after-redirects ``` ```json { "url": "https://bit.ly/xxx" } ``` Follow redirects and return the final destination URL. ## Example: Full SEO Audit ```bash # 1. Analyze backlinks curl -X POST -H "X-API-Key: ck_live_xxx" \ -H "Content-Type: application/json" \ -d '{"domain": "example.com"}' \ "https://claudekit.cc/api/proxy/reviewweb/v1/seo-insights/backlinks" # 2. Research keywords curl -X POST -H "X-API-Key: ck_live_xxx" \ -H "Content-Type: application/json" \ -d '{"keyword": "your product", "country": "US"}' \ "https://claudekit.cc/api/proxy/reviewweb/v1/seo-insights/keyword-ideas" # 3. Check traffic curl -X POST -H "X-API-Key: ck_live_xxx" \ -H "Content-Type: application/json" \ -d '{"domain": "example.com"}' \ "https://claudekit.cc/api/proxy/reviewweb/v1/seo-insights/traffic" ``` ## Next Steps - [Web Scraping](/docs/api/reviewweb/web-scraping) - Scraping & extraction APIs - [VidCap API](/docs/api/vidcap/youtube-processing) - Video processing - [API Introduction](/docs/api/overview/introduction) - Getting started --- # VidCap - YouTube Processing Section: docs Category: vidcap URL: https://docs.claudekit.cc/docs/vidcap/youtube-processing # VidCap - YouTube Video Processing AI-powered YouTube video processing service. Extract metadata, captions, AI summaries, screenshots, and more. **Base path:** `/api/proxy/vidcap/v1` ## Health Check ``` GET /api/proxy/vidcap/v1/healthz ``` Returns service status. ## AI Models ``` GET /api/proxy/vidcap/v1/ai/models ``` List available AI models for summaries and analysis. ## Video Info ``` GET /api/proxy/vidcap/v1/youtube/info?url={youtube_url} ``` Returns video metadata including title, duration, thumbnail, channel info. ```bash curl -H "X-API-Key: ck_live_xxx" \ "https://claudekit.cc/api/proxy/vidcap/v1/youtube/info?url=https://youtube.com/watch?v=dQw4w9WgXcQ" ``` ## Media Formats ``` GET /api/proxy/vidcap/v1/youtube/media?url={youtube_url} ``` Returns available video/audio quality options and formats. ## Download ``` GET /api/proxy/vidcap/v1/youtube/download?url={youtube_url}&format={format} ``` Returns download URL. `format` parameter is optional. ## Captions ``` GET /api/proxy/vidcap/v1/youtube/caption?url={youtube_url}&lang={lang} ``` Extract video captions/transcripts. `lang` defaults to `en`. ```bash curl -H "X-API-Key: ck_live_xxx" \ "https://claudekit.cc/api/proxy/vidcap/v1/youtube/caption?url=https://youtube.com/watch?v=xxx&lang=vi" ``` ## AI Summary ``` GET /api/proxy/vidcap/v1/youtube/summary?url={youtube_url} ``` Generate AI-powered video summary using default model. ### Custom Summary ``` POST /api/proxy/vidcap/v1/youtube/summary-custom ``` **Body:** ```json { "url": "https://youtube.com/watch?v=...", "prompt": "Summarize the key technical points", "model": "gemini-1.5-flash" } ``` Generate custom AI summary with your own prompt and model selection. ## Article ``` GET /api/proxy/vidcap/v1/youtube/article?url={youtube_url} ``` Convert video content into article format. ## Screenshots ### Single Screenshot ``` GET /api/proxy/vidcap/v1/youtube/screenshot?url={youtube_url}×tamp={seconds} ``` Capture a frame at a specific timestamp. `timestamp` defaults to 0. ### Multiple Screenshots ``` GET /api/proxy/vidcap/v1/youtube/screenshot-multiple?url={youtube_url}&count={count} ``` Capture multiple screenshots at evenly distributed intervals. ## Comments ``` GET /api/proxy/vidcap/v1/youtube/comments?url={youtube_url}&limit={limit} ``` Retrieve video comments. `limit` is optional. ## Search ``` GET /api/proxy/vidcap/v1/youtube/search?q={query}&limit={limit} ``` Search YouTube videos programmatically. ```bash curl -H "X-API-Key: ck_live_xxx" \ "https://claudekit.cc/api/proxy/vidcap/v1/youtube/search?q=claude+ai+tutorial&limit=10" ``` ## Next Steps - [ReviewWeb API](/docs/api/reviewweb/web-scraping) - Web scraping & SEO - [API Keys](/docs/api/keys/api-keys) - Manage your API keys - [Authentication](/docs/api/overview/authentication) - Auth and rate limits --- # Agents Overview Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/index # Agents Overview 14 specialized agents that handle every aspect of software development—automatically orchestrated through predefined workflows. ## Quick Reference ### Development & Implementation | Agent | Purpose | |-------|---------| | [planner](/docs/engineer/agents/planner) | Research, analyze, create implementation plans before coding | | [fullstack-developer](/docs/engineer/agents/fullstack-developer) | Execute implementation phases with strict file ownership | | [debugger](/docs/engineer/agents/debugger) | Root cause analysis, log investigation, issue diagnosis | | [tester](/docs/engineer/agents/tester) | Test execution, coverage analysis, quality validation | ### Quality & Review | Agent | Purpose | |-------|---------| | [code-reviewer](/docs/engineer/agents/code-reviewer) | Security audits, performance analysis, code quality | | [code-simplifier](/docs/engineer/agents/code-simplifier) | Autonomous code refinement for clarity and maintainability | ### Documentation & Management | Agent | Purpose | |-------|---------| | [docs-manager](/docs/engineer/agents/docs-manager) | Technical documentation, API docs, architecture guides | | [project-manager](/docs/engineer/agents/project-manager) | Progress tracking, cross-agent coordination, status reports | | [journal-writer](/docs/engineer/agents/journal-writer) | Document failures and setbacks with brutal honesty | | [git-manager](/docs/engineer/agents/git-manager) | Conventional commits, security scanning, token-optimized | ### Creative & Research | Agent | Purpose | |-------|---------| | [ui-ux-designer](/docs/engineer/agents/ui-ux-designer) | Award-winning UI with Three.js, responsive layouts | | [brainstormer](/docs/engineer/agents/brainstormer) | Explore approaches, challenge assumptions, debate decisions | | [researcher](/docs/engineer/agents/researcher) | Multi-source research, documentation analysis | ## How to Use **Automatic (recommended):** Commands orchestrate agents automatically ```bash /ck:bootstrap [feature] # planner → fullstack-developer → tester → code-reviewer /ck:plan [task] # planner + researcher /ck:debug [issue] # debugger → analysis and diagnosis ``` **Explicit:** Request specific agents in prompts ``` "Use debugger agent to investigate login failures, then planner to create fix strategy" ``` ## Under the Hood ### Orchestration Patterns **Sequential** (default): Agents run in order, each building on previous output ``` planner → fullstack-developer → tester → code-reviewer → git-manager ``` **Parallel**: Independent agents run simultaneously ``` researcher (topic1) ┐ researcher (topic2) ├─→ Aggregate → planner researcher (topic3) ┘ ``` **Hybrid**: Mix of sequential and parallel for complex tasks ### Agent Communication Agents share context through: - **Shared files**: `docs/`, `plans/`, code standards - **Handoff protocols**: Each agent receives previous output, performs task, passes results - **TodoWrite**: Real-time progress tracking visible to user ### Handoff Example ``` planner output → plans/auth-feature.md ↓ fullstack-developer reads plan → implements → creates files + tests ↓ tester runs tests → validates coverage ↓ code-reviewer audits → security + quality report ↓ git-manager commits → conventional commit + push ``` ### Troubleshooting **Agent not activating?** - Check command matches task type - Verify workflow files exist in `.claude/agents/` - Try explicit invocation: "Use [agent] to..." **Slow response?** - Use parallel orchestration when tasks are independent - Scope tasks more specifically - Use simpler commands for simple tasks **Conflicts?** - Review orchestration order in workflow files - Check handoff protocols between agents ## Key Takeaway 15 agents work together automatically—use commands to orchestrate them, or invoke explicitly for specific tasks. No manual coordination needed. --- # Researcher Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/researcher # Researcher Agent Multi-source technology intelligence that explores docs, videos, GitHub repos, and articles in parallel to deliver production-ready implementation insights. ## Cognitive Framing This agent operates as a **Technical Analyst synthesizing information from multiple sources into actionable intelligence** — separating signal from noise across documentation, community discussions, and real-world implementations. ## Behavioral Checklist Before completing any research report, this agent verifies: - Multiple sources consulted: no single-source conclusions; at least 3 independent references for key claims - Source credibility assessed: official docs, maintainer blogs, and production case studies weighted above tutorials - Trade-off matrix included: each option evaluated across relevant dimensions (performance, complexity, maintenance, cost) - Adoption risk stated: maturity, community size, breaking-change history, and abandonment risk noted - Architectural fit evaluated: recommendation accounts for existing stack, team skill, and project constraints - Concrete recommendation made: research ends with a ranked choice, not a list of options - Limitations acknowledged: what this research did not cover and why it matters ## When to Use - **New tech evaluation** - Before adopting frameworks, libraries, or tools - **Pre-implementation research** - Finding official docs, security concerns, best practices - **Technical comparison** - Evaluating multiple approaches with pros/cons analysis - **Deep dive validation** - Cross-checking implementation patterns across 10+ sources ## Key Capabilities | Capability | Description | Tools Used | |-----------|-------------|-----------| | **Parallel Search** | Query fan-out across Google, YouTube, websites, GitHub simultaneously | SearchAPI MCP, search_youtube, WebFetch | | **Video Analysis** | Extract technical insights from tutorials with timestamps | VidCap MCP, Gemini Vision | | **Repo Analysis** | Find implementation patterns in popular libraries | repomix, GitHub search | | **Doc Synthesis** | Structured markdown reports with security/performance sections | Multi-source validation | ## Common Use Cases **Who**: Product teams choosing payment gateway **Prompt**: `/ck:plan research Stripe vs PayPal integration for SaaS billing` **Output**: 15-page comparison report with security audit, pricing, code examples **Who**: DevOps engineer evaluating container orchestration **Prompt**: `/ck:plan investigate Kubernetes vs Docker Swarm for microservices` **Output**: Architecture analysis, scaling patterns, operational complexity breakdown **Who**: Frontend dev implementing real-time features **Prompt**: `/ck:plan research WebSocket best practices for chat app` **Output**: Library comparison, connection handling patterns, production configs **Who**: Security-focused startup **Prompt**: `/ck:plan research OAuth2 implementation vulnerabilities and mitigations` **Output**: Security audit, common pitfalls, hardening checklist with sources **Who**: Tech lead architecting data pipeline **Prompt**: `/ck:plan compare Apache Kafka vs RabbitMQ for event streaming` **Output**: Performance benchmarks, use case fit, operational considerations ## How It Works ```bash # Trigger research via planning command /ck:plan [add Stripe payment integration] ``` **What happens**: 1. **Query Fan-Out** - Spawns parallel searches: - Google: "Stripe Node.js production best practices" - YouTube: "Stripe integration tutorial 2025" - GitHub: "stripe-samples" repositories - Official docs: stripe.com/docs 2. **Multi-Source Analysis** - Researcher validates findings across: - 5+ documentation sites - 4+ video tutorials with transcripts - 6+ GitHub repos (popular implementations) - 10+ articles/discussions 3. **Synthesis** - Generates structured markdown report: - Executive summary with recommendation - Security considerations (CRITICAL section) - Performance implications - Implementation guide with code - 15+ cited sources for verification **Output**: `./plans/research/YYMMDD-stripe-integration.md` ## Report Structure ```markdown # Research Report: [Technology] ## Executive Summary - Key recommendation with confidence level - 3-5 critical takeaways ## Integration Approaches - Option A vs B vs C comparison - Pros/cons table - "Best for" recommendations ## Security Best Practices ✅ Critical requirements ⚠ Common vulnerabilities ## Performance Considerations - Metrics: load time, processing speed - Optimization strategies ## Implementation Guide - Minimal working example (TypeScript) - Step-by-step setup ## Sources (15+) - Docs, videos, repos, articles ## Next Steps - 5-step action plan with time estimates ``` ## Pro Tips **Be specific in research requests** - "Stripe with Next.js App Router" beats "payment integration" **Leverage security sections** - Researcher surfaces CVEs and common vulnerabilities automatically **Check source dates** - Report includes "Last Updated" for each source; flag outdated info **Use for architecture decisions** - Research 2-3 alternatives before committing to stack **Share with planner** - Feed research reports directly to planner agent for implementation plans ## Related Agents - [Planner Agent](/docs/engineer/agents/planner) - Converts research findings into step-by-step implementation plans - [Brainstormer Agent](/docs/engineer/agents/brainstormer) - Debates technical trade-offs discovered in research - [Scout Agent](/docs/engineer/skills/scout) - Locates existing implementations in your codebase ## Key Takeaway Researcher eliminates "tutorial hell" by validating 15+ sources in parallel, surfacing security risks, and delivering production-ready intelligence before you write a single line of code. Part of ClaudeKit $99 toolkit. --- # Planner Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/planner # Planner Agent Researches best practices, analyzes your codebase, and generates step-by-step implementation plans with code examples, timelines, and rollback procedures. ## Cognitive Framing This agent operates as a **Tech Lead locking architecture before code** — thinking in systems: data flows, failure modes, edge cases, and migration paths. No code is written until the plan is solid. ## Behavioral Checklist Before completing any plan, this agent verifies: - Data flows documented for all affected components - Dependency graph complete with no missing integrations - Risk assessment included for each phase - Backwards compatibility strategy defined - Test matrix covers happy paths, edge cases, and failure modes - Rollback plan specified for each major change - File ownership clearly assigned to prevent conflicts - Success criteria are measurable and objectively verifiable ## When to Use - **Before major features** - Break down complex work into clear steps - **Technical decisions** - Evaluate multiple approaches with pros/cons - **Large refactors** - Map dependencies and impact before touching code - **CI/CD failures** - Analyze logs and create systematic fix plans ## Key Capabilities | Capability | What It Does | |-----------|--------------| | **Research** | Searches industry standards, official docs, proven solutions | | **Analysis** | Reads codebase, evaluates dependencies, identifies integration points | | **Planning** | Breaks work into tasks, lists file changes, estimates timeline | | **Risk Management** | Includes rollback plans, security checks, performance considerations | ## Common Use Cases **Feature Planning** - **Who**: Backend dev adding real-time notifications - **Prompt**: `/ck:plan [add WebSocket notifications with Socket.io and Redis]` - **Output**: Plan with setup steps, auth integration, database schema, test strategy **Architecture Review** - **Who**: Tech lead evaluating database migration - **Prompt**: `/ck:plan [migrate from MongoDB to PostgreSQL]` - **Output**: Migration strategy, data transformation steps, zero-downtime approach **Bug Investigation** - **Who**: Developer fixing complex race condition - **Prompt**: `/ck:plan --hard [fix checkout race condition causing double charges]` - **Output**: Root cause analysis, reproduction steps, fix plan with test cases **Optimization Planning** - **Who**: DevOps engineer improving performance - **Prompt**: `/ck:plan [optimize API response time from 2s to 200ms]` - **Output**: Profiling strategy, bottleneck analysis, optimization steps with benchmarks **CRO Implementation** - **Who**: Growth engineer improving conversion - **Prompt**: `/ck:plan [improve checkout abandonment rate]` - **Output**: A/B test plan, UX improvements, tracking implementation ## What You Get Every plan includes: ```markdown # Implementation Plan: [Feature Name] ## Approach Why this solution + alternatives considered ## Steps 1. Install Dependencies (5 min) - Commands to run 2. Core Implementation (20 min) - Files to create: src/feature/service.ts - Files to modify: src/server.ts - Code snippets showing structure 3. Integration (15 min) - Where to hook into existing code 4. Testing (20 min) - Test files to create - Coverage requirements ## Timeline Total: 1 hour ## Rollback Plan Step-by-step recovery if issues occur ## Security Checklist - Auth validation - Input sanitization - Rate limiting ## Next Steps Ready to implement? Run: /ck:cook @plans/your-plan.md ``` Plans saved to: `plans/[feature-name]-YYYYMMDD-HHMMSS.md` ## Pro Tips **Review before coding**: Plans catch design flaws before you write code. Check the approach section first. **Use plans as specs**: Reference the plan during code review. "Did we implement step 3?" ensures nothing is missed. **Multiple approaches**: Use `/ck:plan --two [description]` to generate two different solutions with trade-off comparison. **Link from issues**: Save plans to git, link from GitHub issues. Future devs understand *why* decisions were made. **Update after implementation**: Mark completed steps, note deviations. Plans become living documentation. ## Example Commands ```bash # Basic planning /ck:plan [add OAuth2 authentication] # Compare approaches /ck:plan --two [use Redis vs PostgreSQL for caching] # Fix planning /ck:plan --hard [memory leak in job processor] # CRO planning /ck:plan [improve signup conversion] # CI/CD fix /ck:plan [github-actions-url] # Execute plan /ck:cook @plans/oauth2-auth-20241020.md ``` ## Integration with Commands | Phase | Command | Purpose | |-------|---------|---------| | Research | `/ck:plan` | Generate implementation plan | | Review | `cat plans/latest.md` | Review plan before coding | | Execute | `/ck:cook @plans/plan.md` | Implement following plan | | Test | `/ck:test` | Validate implementation | | Document | Update plan with actuals | Create decision record | ## Related Agents - [Fullstack Developer](/docs/engineer/agents/fullstack-developer) - Executes implementation plans - [Researcher Agent](/docs/engineer/agents/researcher) - Deep dives on specific topics - [Scout](/docs/engineer/skills/scout) - Explores codebase for context ## Key Takeaway Planning prevents waste. 10 minutes of research and analysis saves hours of refactoring when you discover you picked the wrong approach halfway through implementation. --- # Tester Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/tester # Tester Agent Automated test execution with 80%+ coverage targets, failure diagnosis, and build verification across all major frameworks. ## Cognitive Framing This agent operates as a **QA Lead performing systematic verification** — hunting untested code paths, coverage gaps, and edge cases that slip through normal development cycles. ## Behavioral Checklist Before completing any task, this agent verifies: - All changed files have corresponding test coverage - Coverage gaps on critical code paths identified and flagged - Edge cases for boundary conditions covered - Error scenarios and exception paths tested - Flaky tests detected and isolated - Build verification passes (typecheck, lint, compile) - Coverage targets met (80%+ overall) ## Diff-Aware Mode By default, the tester agent analyzes the git diff and runs only the tests affected by recent changes. Five mapping strategies determine which tests to run: | Strategy | Trigger | |----------|---------| | **Co-located** | Test file sits next to source file (`foo.ts` → `foo.test.ts`) | | **Mirror directory** | Tests mirror source structure (`src/api/` → `tests/api/`) | | **Import graph** | File is imported by a tested module (transitive impact) | | **Config detection** | Config/infra files changed (`tsconfig`, `jest.config`, `package.json`) → full suite | | **High fan-out** | File imported by many modules — runs broader suite | **Auto-escalation to full suite** occurs when: - More than 70% of total tests are mapped by the diff (overhead not worth it) - Configuration files are modified (`package.json`, `tsconfig.json`, CI workflows, etc.) — config changes always trigger full suite This keeps CI fast on small PRs while ensuring correctness on large changes. ## When to Use - `/ck:test` - Run full test suite with coverage - `/ck:fix [issue]` - Fix failing tests automatically - Pre-commit/pre-push validation - CI/CD pipeline verification ## Key Capabilities | Category | Tools | Coverage Target | |----------|-------|-----------------| | **Unit Tests** | Jest, Vitest, pytest, cargo test, go test | 80%+ | | **Integration** | API testing, DB interactions, service layers | Critical paths | | **E2E** | Playwright, Cypress, Flutter integration tests | Critical paths | | **Coverage** | Line, branch, function, statement analysis | 80%+ overall | | **Build Check** | TypeScript, linting, bundle size, compilation | 100% pass | ## Common Use Cases **Solo Dev - Pre-commit validation** ``` /ck:test Validates all changes before commit with coverage report ``` **QA Engineer - Bug regression prevention** ``` /ck:test Then review: Which areas have <80% coverage? ``` **Team Lead - PR validation** ``` /ck:test Verify: All tests pass + coverage targets met ``` **DevOps - CI/CD integration** ``` /ck:test Output: JSON report for pipeline integration ``` **Full-Stack Dev - Multi-framework testing** ``` /ck:test Runs: Flutter analyze + Jest + pytest in sequence ``` ## Pro Tips **Coverage-first approach**: Always check coverage gaps after test runs - uncovered code = untested risk **Fail fast**: Use `/ck:test` before starting new work to catch environment issues early **Fix atomically**: Use `/ck:fix [specific failure]` for targeted repairs instead of batch fixes **Performance baseline**: Track test execution time - >60s indicates need for optimization **Docker isolation**: Run tests in containers for consistency across team environments ## Related Agents - [Debugger](/docs/engineer/agents/debugger) - Investigate test failures - [Code Reviewer](/docs/engineer/agents/code-reviewer) - Pre-test code quality - [Fullstack Developer](/docs/engineer/agents/fullstack-developer) - Post-test build verification ## Key Takeaway Test execution isn't about 100% coverage - it's about 80%+ on critical paths with zero flaky tests. The tester agent finds failures, diagnoses root causes, and ensures your coverage targets before any commit goes through. --- # Debugger Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/debugger # Debugger Agent Systematic root cause analysis for production incidents, API failures, and complex technical issues. ## Cognitive Framing This agent operates as a **Senior SRE performing incident root cause analysis** — correlating logs, traces, code paths, and system state to prove what happened. Never guesses; always proves with evidence. ## Behavioral Checklist Before completing any investigation, this agent verifies: - Evidence collected before forming any hypothesis - At least 2-3 competing hypotheses considered - Each hypothesis tested systematically, not assumed - Eliminated hypotheses documented with reasoning - Incident timeline constructed from logs and events - Environmental factors checked (deploys, config changes, traffic spikes) - Root cause supported by concrete evidence, not inference - Prevention strategy proposed to stop recurrence ## When to Use - API endpoints returning 500 errors or unexpected responses - CI/CD pipeline failures blocking deployments - Database connection pools exhausted or queries timing out - Production incidents requiring immediate diagnosis ## Key Capabilities | Area | What It Does | |------|-------------| | **Issue Investigation** | Structured problem-solving: assess severity, collect logs, identify patterns, trace timeline | | **Database Analysis** | Schema inspection (`psql \d`), query plans (EXPLAIN), connection monitoring, lock detection | | **Log Analysis** | Parse server logs, CI/CD output, GitHub Actions failures, container logs, system errors | | **Performance** | Response times, resource usage (CPU/memory/disk), bottleneck identification, cache analysis | | **Root Cause** | Error tracing, dependency failures, config issues, code bugs, infrastructure problems | ## Common Use Cases ### Backend Engineer: API 500 Errors **Prompt**: `/ck:debug [POST /api/orders returning 500, started after v2.3.4 deploy]` Gets root cause (missing req.user, connection leak), fix plan, rollback steps, validation commands. ### DevOps: Database Connection Exhaustion **Prompt**: `/ck:debug [PostgreSQL pool exhausted, 47/20 connections active]` Identifies leaked transactions, long-running queries, table locks. Provides kill commands, query timeouts, code fixes. ### Full-Stack Dev: GitHub Actions Failing **Prompt**: `/ck:debug [CI build failing on test step, error "Module not found"]` Analyzes workflow logs, identifies missing dependency or broken import, suggests package.json fix. ### Site Reliability Engineer: Performance Degradation **Prompt**: `/ck:debug [API latency increased from 200ms to 3s after deploy]` Profiles endpoints, finds N+1 queries or missing indexes, provides EXPLAIN ANALYZE output and optimization plan. ## Pro Tips **Collect context first**: Before running `/ck:debug`, gather error messages, timestamps, recent changes (deploys/commits), and environment details. **Check the usual suspects**: Recent deployments, config changes, dependency updates, database migrations often cause issues. **Use parallel investigation**: Combine with scout agents for broad searches: `scout('Find all database transaction usage', 3)` while analyzing logs. **Validate fixes in staging**: Test proposed solutions in non-production before applying to prod. **Document for next time**: Debugger reports become runbooks - save them for similar future incidents. ## Related Agents - [Tester](/docs/engineer/agents/tester) - Validate fixes with comprehensive tests - [Code Reviewer](/docs/engineer/agents/code-reviewer) - Review fix quality before merge - [Fullstack Developer](/docs/engineer/agents/fullstack-developer) - Implement suggested fixes ## Key Takeaway Debugger agent systematically investigates technical issues from symptoms to root cause, providing actionable solutions with validation steps and prevention measures - turning hours of troubleshooting into 30-minute structured analysis. --- # Brainstormer Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/brainstormer # Brainstormer Agent Your technical advisor who challenges assumptions, debates approaches, and provides brutally honest assessments before code is written. ## Cognitive Framing This agent operates as a **CTO-level technical advisor evaluating solutions with brutal honesty** — quantifying trade-offs, surfacing hidden complexity, and preventing over-engineering before it becomes technical debt. ## Behavioral Checklist Before completing any brainstorming session, this agent verifies: - Assumptions challenged: at least one core assumption of the user's approach was questioned explicitly - Alternatives surfaced: 2-3 genuinely different approaches presented, not variations on the same idea - Trade-offs quantified: each option compared on concrete dimensions (complexity, cost, latency, maintainability) - Second-order effects named: downstream consequences of each approach stated, not implied - Simplest viable option identified: the option with least complexity that still meets requirements is clearly named - Decision documented: agreed approach recorded in a summary report before session ends ## When to Use - Evaluating multiple architectural approaches with competing trade-offs - Challenging assumptions about requirements and feasibility - Debating technical decisions before committing resources - Need a "second opinion" on complex problems requiring creative solutions ## Key Capabilities | Capability | Description | |-----------|-------------| | Multi-approach analysis | Explores 3-5 valid solutions with detailed pros/cons | | Assumption challenging | Questions requirements to ensure solving real problems | | Trade-off evaluation | Assesses complexity, maintenance, performance, cost, technical debt | | Brutal honesty | Unfiltered assessment: overengineering alerts, risk identification, simpler alternatives | | YAGNI/KISS/DRY | Applies principles to prevent premature optimization | | Contextual recommendations | Considers team skills, timeline, budget constraints | ## Common Use Cases **Startup CTO**: Evaluating API architecture ```bash /ck:brainstorm [should we use REST API or GraphQL for our mobile app? Team has REST experience, need to ship MVP in 6 weeks] ``` **Tech Lead**: Debating caching strategies ```bash /ck:brainstorm [API responses are slow. Evaluating Redis cache vs database optimization vs CDN. Current p95 is 800ms, need <200ms] ``` **Product Engineer**: Challenging feature requests ```bash /ck:brainstorm [stakeholder wants real-time dashboard with WebSockets. Is this necessary or can we use polling?] ``` **Solo Developer**: Planning refactoring ```bash /ck:brainstorm [monolith is getting messy. Should I split into microservices or improve modular monolith structure first?] ``` **Team Lead**: Assessing feasibility ```bash /ck:brainstorm [client wants offline-first mobile app with sync. Team has 3 junior devs, 8-week timeline. Realistic?] ``` ## Pro Tips **Provide context upfront**: Team skills, timeline, budget, constraints. Better context = better recommendations. **Be open to challenges**: Brainstormer will question your assumptions. That's the point. Saves costly mistakes. **Focus on "Recommendation" section**: If overwhelmed by options, read the final recommendation first, then backtrack for details. **Use success criteria**: Brainstormer defines measurable criteria (e.g., "p95 <200ms"). Use these to validate decisions later. **Don't skip "Open Questions"**: Unresolved questions in the output need answers before proceeding. **Trust YAGNI assessments**: If brainstormer says it's overengineering, it probably is. Build what you need now. **Follow "Next Steps"**: Output includes actionable next steps. Usually involves `/ck:plan` command for implementation. ## Related Agents - [Planner Agent](/docs/engineer/agents/planner) - Creates implementation plans after approach is decided - [Researcher Agent](/docs/engineer/agents/researcher) - Provides data for brainstorming decisions - [Docs-Manager Agent](/docs/engineer/agents/docs-manager) - Documents architectural decision records ## Key Takeaway Brainstormer doesn't write code. It saves you from writing the wrong code. Use it before committing to complex architectural decisions. 10 minutes of brainstorming prevents weeks of refactoring. --- # Code Reviewer Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/code-reviewer # Code Reviewer Agent Production-grade security and quality audits with categorized findings before merge. ## Cognitive Framing This agent operates as a **Staff Engineer hunting bugs that pass CI but break production** — race conditions, N+1 queries, trust boundary violations, and security gaps that automated tools miss. ## Behavioral Checklist Before completing any review, this agent verifies: - Concurrency issues and race conditions examined - Error boundaries and failure propagation paths checked - API contracts match between callers and implementations - Backwards compatibility preserved for public interfaces - Input validation and sanitization present at trust boundaries - Auth/authz checks enforced on all protected operations - N+1 query patterns identified and flagged - Sensitive data not leaked in logs, errors, or responses ## When to Use - Pre-merge quality gates - Security vulnerability detection - Type safety validation - Performance bottleneck analysis ## Key Capabilities | Category | Checks | |----------|--------| | **Security** | OWASP Top 10, SQL injection, XSS, CSRF, secrets exposure | | **Type Safety** | TypeScript strict mode, `any` usage, null checks | | **Performance** | N+1 queries, memory leaks, bundle size | | **Quality** | Test coverage (80%+ target), error handling, code duplication | | **Standards** | Linting, naming conventions, documentation | ## Common Use Cases **1. Pre-Merge Review** - **Who**: Any developer before PR - **Prompt**: `/review [feature-name]` - **Output**: Categorized issues (Critical/High/Medium/Low) with fix recommendations **2. Security Audit** - **Who**: Security-conscious teams - **Prompt**: `/review [security audit of auth module]` - **Output**: OWASP compliance report, vulnerability list, remediation steps **3. Refactoring Assessment** - **Who**: Teams improving legacy code - **Prompt**: `/review [type safety improvements in src/]` - **Output**: `any` type locations, strict mode violations, migration plan **4. Performance Analysis** - **Who**: Teams optimizing slow endpoints - **Prompt**: `/review [database query performance]` - **Output**: N+1 problems, missing indexes, caching opportunities **5. Standards Compliance** - **Who**: Teams enforcing code standards - **Prompt**: `/review [compare auth module against code-standards.md]` - **Output**: Standards checklist with pass/fail status ## Pro Tips **Scope Reviews Strategically** ```bash /review [src/auth/] # Directory /review [user authentication] # Feature /review [PR-123] # Pull request ``` **Combine with Fix Workflow** ```bash /review [feature-x] /ck:fix --quick [fix critical security issues from review] /ck:test /review [feature-x] # Verify fixes ``` **Use Review Categories** - **Critical**: Must fix before merge (security, data loss) - **High**: Should fix (performance, type safety, reliability) - **Medium**: Recommended (maintainability, code smells) - **Low**: Optional (style, minor improvements) **Check Task Status Updates** Reviews automatically update plan files with found issues and blocking status. **Set Quality Gates** Enforce 80%+ test coverage, zero `any` types, security scan pass before production. ## Related Agents - [Planner](/docs/engineer/agents/planner) - Creates fix plans from review findings - [Tester](/docs/engineer/agents/tester) - Validates fixes with comprehensive tests - [Scout External](/docs/engineer/skills/scout) - Researches best practices for fixes ## Key Takeaway The code reviewer agent prevents production incidents by catching security vulnerabilities, type safety violations, and performance issues before merge. Use it as a quality gate in every PR workflow. --- # Code Simplifier Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/code-simplifier # Code Simplifier Agent **Expert code simplification: reduce complexity, eliminate redundancy, improve naming — without changing behavior.** ## When to Use - After implementation, before code review - When code passes tests but feels over-engineered - When reducing nesting and cognitive load in a module - When enforcing project standards from `CLAUDE.md` - As the penultimate step before merge (implementation → simplify → review) ## Key Capabilities | Capability | What It Does | |------------|-------------| | **Complexity Reduction** | Flattens deep nesting, prefers early returns | | **Redundancy Elimination** | Removes duplicate logic, merges similar branches | | **Naming Improvement** | Renames variables/functions for clarity and intention | | **Standards Enforcement** | Applies project conventions from `CLAUDE.md` | | **Behavior Preservation** | Never alters what code does, only how it reads | ## What It Does / Doesn't Do **Does:** - Rewrite verbose conditionals as early returns - Extract repeated logic into named helpers - Simplify complex expressions into readable steps - Remove unnecessary abstractions and indirection - Apply consistent naming across a module **Doesn't:** - Change business logic or algorithm behavior - Add new features or capabilities - Modify test files (reads only) - Touch files outside the scope of recently modified code (unless instructed) ## Refinement Process 1. **Identify Scope** - Focus on recently modified files unless a specific scope is given 2. **Analyze** - Read code for complexity hotspots: deep nesting, long functions, unclear names 3. **Apply Standards** - Cross-reference `CLAUDE.md` and `docs/code-standards.md` for project conventions 4. **Simplify** - Rewrite for clarity using early returns, extracted helpers, better naming 5. **Verify** - Confirm behavior is unchanged by re-reading logic (does not modify tests) 6. **Run Verification** - Execute typecheck, linter, and test suite to confirm nothing broke The agent operates autonomously after implementation — no interactive prompts during simplification. ## Model Uses **Opus** (most capable model) to maximize code quality judgment and catch subtle naming issues. ## Team Mode When operating as a teammate in an Agent Team: - Respects file ownership boundaries — only simplifies files it is assigned - Claims tasks via `TaskUpdate` before starting work - Communicates completion with a summary of changes to lead agent - Does not send intermediate progress messages ## Pro Tips **Sequence matters** — always simplify after tests pass, before code review: ``` implement → test → simplify → review → merge ``` **Scope it explicitly** when working on large codebases: ``` /simplify [src/auth/token-manager.ts] /simplify [recently modified files in src/api/] ``` **Pair with code-reviewer** — simplified code yields cleaner, more actionable review findings. ## Related Agents - [Code Reviewer](/docs/engineer/agents/code-reviewer) - Quality gates after simplification is complete ## Key Takeaway The code simplifier runs between implementation and review — producing cleaner, more readable code without altering behavior. It catches the over-engineering that tests can't see. --- # Docs Manager Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/docs-manager # Docs Manager Agent **Keep your docs synced with your codebase.** Creates, updates, and maintains technical documentation automatically after code changes. ## Cognitive Framing This agent operates as a **Technical Writer ensuring docs are comprehensive, accurate, and maintainable** — treating documentation as a product that must stay synchronized with the codebase it describes. ## Behavioral Checklist Before completing any documentation task, this agent verifies: - Read the actual code before documenting — never describe assumed behavior - Verify every code example compiles/runs before including it - Check that referenced file paths, function names, and CLI flags still exist - Remove stale sections rather than leaving them with "TODO: update" markers - Cross-reference related docs to prevent contradictions ## When to Use - After implementing new features requiring documentation updates - Setting up initial project documentation with `/ck:docs init` - Generating codebase summaries with Repomix integration - Syncing docs with code changes using `/ck:docs update` ## Key Capabilities | Feature | What It Does | |---------|-------------| | **Auto Documentation** | Analyzes code changes → updates relevant docs | | **Repomix Integration** | Generates codebase summaries from compacted XML | | **Scout Orchestration** | Runs parallel file searches to gather context | | **Standards Enforcement** | Validates case conventions, links, code examples | | **Doc Structure** | Maintains PDRs, architecture, code standards, guides | ## Common Use Cases ### New Project Setup **Who**: Team leads starting new projects **Prompt**: `/ck:docs init` **Result**: Creates full documentation suite in `./docs/` directory ### Post-Feature Documentation **Who**: Developers who just shipped a feature **Prompt**: `/ck:docs update` **Result**: Scans git diff → updates system architecture, API docs, standards ### Architecture Documentation **Who**: Tech leads documenting system design **Prompt**: "Update system-architecture.md with the new microservices setup" **Result**: ASCII diagrams, component docs, integration flows ### Codebase Summary **Who**: Onboarding new team members **Prompt**: `/ck:docs summarize` **Result**: Runs Repomix → generates `codebase-summary.md` with stats and structure ### API Reference Generation **Who**: Backend devs exposing new endpoints **Prompt**: "Document the /api/auth endpoints with request/response examples" **Result**: Complete API docs with schemas, errors, curl examples ## Pro Tips **1. Run After Every Feature** ```bash # Standard workflow git commit -m "feat: add auth" /ck:docs update git add docs/ && git commit -m "docs: update for auth" ``` **2. Use Scout for Deep Context** ```bash # docs-manager auto-runs these behind the scenes /ck:scout "authentication files" 5 /ck:scout "API endpoints" 5 # Aggregates results for accurate documentation ``` **3. Maintain This Structure** ``` ./docs/ ├── project-overview-pdr.md # Requirements, roadmap ├── code-standards.md # Conventions, patterns ├── codebase-summary.md # Repomix-generated overview ├── system-architecture.md # Technical design ├── deployment-guide.md # Production setup └── design-guidelines.md # UI/UX specs ``` **4. Validate Everything** - Tests code examples before committing - Checks link integrity across all docs - Enforces case conventions (camelCase, PascalCase, snake_case) - Verifies formatting consistency **5. Weekly Maintenance** ```bash # Keep docs fresh /ck:docs update # Scan for outdated content /ck:docs summarize # Regenerate summary (monthly) ``` **6. Document the "Why"** ```markdown # ❌ Bad "Configure the database" # ✅ Good "Set DATABASE_URL in .env to enable connection pooling. Using pooling reduces latency by 60% under high load." ``` **7. API Documentation Template** ```markdown ### POST /api/auth/login Authenticate user and return JWT token. **Request Body:** { email: string; // Valid email password: string; // Min 8 chars } **Response (200):** { token: string; // JWT access token expiresIn: number; // Seconds } **Errors:** - 400: Invalid format - 401: Invalid credentials - 429: Rate limited ``` **8. Use Absolute Paths** ```markdown ✅ [Authentication](/docs/engineer/agents/docs-manager) ❌ [Authentication](./docs-manager) ``` ## Related Agents - [Planner Agent](/docs/engineer/agents/planner) - Creates implementation plans → docs-manager documents them - [Scout Agent](/docs/engineer/skills/scout) - Locates files → docs-manager uses for context - [Project Manager](/docs/engineer/agents/project-manager) - Coordinates tasks → docs-manager provides status ## Key Takeaway **Docs-manager keeps documentation synchronized with code automatically.** Run `/ck:docs init` for initial setup, `/ck:docs update` after features, `/ck:docs summarize` for overview. Integrates with Repomix and Scout for comprehensive analysis. Part of ClaudeKit $99 toolkit. --- # Project Manager Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/project-manager # Project Manager Agent Senior orchestrator for tracking progress, collecting agent reports, maintaining roadmaps, and coordinating multi-agent workflows. ## Cognitive Framing This agent operates as an **Engineering Manager providing project oversight and cross-session continuity** — ensuring the team stays aligned, blockers are surfaced early, and progress is accurately reflected in the roadmap. ## Behavioral Checklist Before completing any status update or coordination task, this agent verifies: - Progress measured against plan: tasks checked complete only if done criteria are met, not just "in progress" - Blockers identified: any task stalled >1 session flagged with owner and unblock path - Scope changes logged: any deviation from original plan documented with reason and impact - Risks updated: new risks added, resolved risks closed — no stale risk register - Next actions concrete: each next step has an owner and a definition of done ## When to Use - Track project status with `/ck:watzup` command - Consolidate multi-agent work after features - Weekly progress reviews and milestone reports - Verify task completeness before deployment ## Key Capabilities | Feature | What It Does | |---------|--------------| | **Progress Tracking** | Monitors agent outputs, task completion, blockers, quality metrics | | **Report Collection** | Gathers reports from all agents in `plans/reports/` | | **Roadmap Updates** | Maintains `docs/project-roadmap.md` after features/milestones | | **Plan Analysis** | Validates plans, identifies gaps, adjusts timelines | | **Coordination** | Orchestrates sequential phases across multiple agents | ## Common Use Cases ### 1. Weekly Status Report **Who**: Team lead checking progress **Prompt**: `/ck:watzup` **Output**: Consolidated report with velocity, quality metrics, completed features, next priorities ### 2. Feature Completion Review **Who**: Developer finishing major feature **Prompt**: "Review authentication implementation and update roadmap" **Output**: Verifies tests, docs, commits → Updates roadmap → Generates completion report ### 3. Multi-Agent Coordination **Who**: PM planning complex feature **Prompt**: "Coordinate Stripe payment integration across all agents" **Output**: Orchestrates planner → code → tester → reviewer → docs-manager → git-manager ### 4. Sprint Planning **Who**: Team starting new sprint **Prompt**: "Analyze last sprint velocity and recommend story points for this week" **Output**: Historical velocity analysis, capacity recommendations, risk assessment ### 5. Blocker Escalation **Who**: Agent hitting blocker **Prompt**: "Frontend integration blocked, need timeline adjustment" **Output**: Documents blocker, adjusts roadmap dates, notifies stakeholders ## Pro Tips **Roadmap Discipline**: Always update `project-roadmap.md` after features, milestones, bugs (critical/high), security updates, weekly reviews. **Report Convention**: `plans/reports/YYMMDD-from-[agent]-to-[agent]-[task]-report.md` (e.g., `251030-from-planner-to-pm-auth-research-report.md`) **Delegation Rule**: Never edits docs directly except `project-roadmap.md`. Delegates all other docs to docs-manager agent. **Velocity Tracking**: Uses historical sprint data (story points/week) to forecast timelines. Adjusts estimates when velocity changes >15%. **Quality Gates**: Verifies checklist before completion: Implementation → Tests → Review → Docs → Security → Performance → Commit. ## Related Agents - [Planner](/docs/engineer/agents/planner) - Creates implementation plans analyzed by PM - [Docs Manager](/docs/engineer/agents/docs-manager) - Receives delegation for doc updates - [Git Manager](/docs/engineer/agents/git-manager) - Provides commit reports to PM - [Tester](/docs/engineer/agents/tester) - Sends test results for quality tracking ## Key Takeaway The project-manager is ClaudeKit's orchestration layer: it doesn't code, test, or write docs—it tracks, reports, delegates, and maintains the single source of truth (project-roadmap.md) so your multi-agent system stays aligned. --- # UI/UX Designer Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/ui-ux-designer # UI/UX Designer Agent Research trending designs, create production-ready interfaces, and ship conversion-optimized layouts with Three.js 3D, pure HTML/CSS/JS, and WCAG 2.1 AA compliance. ## When to Use - Building landing pages, dashboards, or web apps from scratch - Recreating designs from screenshots or videos - Implementing 3D interactive experiences with Three.js/WebGL - Creating responsive design systems with CSS tokens ## Key Capabilities | Capability | Output | |------------|--------| | **Research** | Dribbble, Behance, Awwwards trend analysis → design decisions | | **Wireframing** | Information architecture → component hierarchy → layout structure | | **Visual Design** | Color palettes, typography scale, spacing system → CSS tokens | | **3D Graphics** | Three.js scenes, WebGL shaders, particle systems → interactive 3D | | **Implementation** | Semantic HTML, CSS Grid/Flexbox, vanilla JS → production code | | **Optimization** | WebP images, lazy loading, minification → Lighthouse 90+ score | | **Accessibility** | Keyboard nav, ARIA, screen readers → WCAG 2.1 AA compliant | | **Responsive** | Mobile-first (320px+, 768px+, 1024px+) → works everywhere | ## Common Use Cases ### 1. SaaS Landing Page **Who:** Product team launching new SaaS product **Prompt:** Use `ai-artist` skill (creative mode) - "create conversion-optimized landing page for AI analytics platform with hero 3D visualization, pricing tiers, testimonials" **Output:** Complete landing page with hero section (animated 3D graph), value props, bento grid features, pricing comparison, FAQ accordion, sticky nav, above-fold CTA ### 2. 3D Product Showcase **Who:** E-commerce team selling physical products **Prompt:** Use `ai-artist` or `threejs` skill - "create interactive 3D product viewer for wireless headphones with 360° rotation, material textures, color variants" **Output:** Three.js scene with orbit controls, PBR materials, HDR lighting, color picker UI, zoom/pan/rotate interactions ### 3. Clone from Screenshot **Who:** Startup replicating competitor design **Prompt:** Use `ai-multimodal` or `frontend-design` skill - "recreate this design: ./competitor-landing.png" **Output:** Pixel-perfect recreation with semantic HTML, modern CSS, responsive breakpoints, accessibility improvements ### 4. Dashboard Interface **Who:** Internal tools team building analytics dashboard **Prompt:** Use `ai-artist` skill (creative mode) - "create dark-themed analytics dashboard with charts, KPI cards, data tables, filters sidebar" **Output:** Responsive dashboard layout with CSS Grid, chart containers, skeleton loaders, empty states, mobile nav drawer ### 5. Design System from Video **Who:** Agency recreating client's animated prototype **Prompt:** Use `ai-multimodal` or `remotion` skill - "recreate design from video: ./design-prototype.mp4" **Output:** Component library matching video specs, micro-animations, transitions, color/typography tokens, style guide docs ## Pro Tips - **Fast prototyping:** Use `ai-artist` skill in search mode for quick mockups, creative mode for production-ready designs - **3D performance:** Three.js scenes auto-optimize for 60fps with LOD, frustum culling, texture compression - **Vietnamese support:** All designs include Google Fonts with Vietnamese diacritics (Inter, Roboto, Noto Sans) - **CRO built-in:** Above-fold CTAs, social proof placement, trust signals, risk reversal automatically included - **Design analysis:** Use `ai-multimodal` skill to extract colors, typography, spacing from any screenshot - **Bento grids:** Request "bento grid layout" for modern mixed-size card layouts (like Apple, Linear) - **Glassmorphism:** Specify "glassmorphism" for backdrop blur + transparency effects - **Core Web Vitals:** All designs target LCP <2.5s, FID <100ms, CLS <0.1 with lazy loading, font optimization ## Related Agents - [Copywriter](/docs/engineer/skills/copywriting) - Generate compelling headlines, CTAs, product descriptions - [Fullstack Developer](/docs/engineer/agents/fullstack-developer) - Integrate designs with backend APIs, databases - [Scout](/docs/engineer/skills/scout) - Explore existing components and patterns - [Code Reviewer](/docs/engineer/agents/code-reviewer) - Validate HTML semantics, CSS performance, accessibility ## Key Takeaway ClaudeKit UI/UX Designer agent ships award-winning interfaces in minutes, not days. Research-backed designs with production-ready code, WCAG compliance, and Lighthouse 90+ scores out of the box. No Figma needed. --- # Git Manager Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/git-manager # Git Manager Agent **Stage, commit, and push code with professional conventional commits, security scanning, and 81% cost reduction.** ## When to Use - Auto-generate semantic commit messages (feat, fix, docs, refactor) - Prevent secrets from leaking into Git history - Commit and push after implementing features or fixes - Create pull requests with proper formatting ## Key Capabilities | Feature | Description | |---------|-------------| | **Conventional Commits** | Auto-generates `type(scope): description` messages (max 72 chars) | | **Security Scanning** | Blocks commits with API keys, passwords, tokens, connection strings | | **Token Optimization** | 81% cost reduction vs baseline (Haiku model, 5-8K tokens/commit) | | **Smart Staging** | Auto-detects relevant changes, respects `.gitignore` | | **Delegation** | Escalates complex changes (5+ files) to Gemini for context | ## Common Use Cases ### Developers - Quick Commits **Prompt**: `/ck:git cm` or `/ck:git cp` - Commits auth bug fix with `fix(auth): add email validation in login` - 10-15 seconds, $0.015 per commit - Security scan blocks if secrets detected ### Teams - Consistent History **Prompt**: "commit and push" - Enforces conventional commit format across team - Compatible with changelog generators (semantic-release) - No AI attribution in commit messages ### DevOps - Safe Deployments **Prompt**: `/ck:git cp` after feature work - Scans for leaked AWS credentials, DB passwords, OAuth tokens - Blocks commit and shows file/line number of violations - Whitelists `process.env.*` and `.env.example` ### Code Reviewers - Pre-Commit Validation **Prompt**: Chain with code-reviewer agent → `/ck:git cm` - Reviews code → fixes applied → commits with proper message - Example: `refactor(db): extract query builders to helpers` ### Multi-File Features - Smart Delegation **Prompt**: `/ck:git cm` after dashboard feature - Detects complex changes (Dashboard.tsx, Chart.tsx, styles) - Delegates to Gemini: `feat(dashboard): add interactive chart component` - Includes multi-line body with implementation details ## Pro Tips **Commit Types Reference**: ``` feat → New feature fix → Bug fix docs → Documentation only refactor → Code restructuring perf → Performance improvement test → Adding tests chore → Maintenance (deps, config) ``` **Security Patterns Blocked**: ```typescript // ❌ Blocked const API_KEY = "sk-1234567890abcdef"; const DB_URL = "postgres://user:pass@host/db"; // ✅ Allowed const API_KEY = process.env.API_KEY; ``` **Logical Commit Grouping**: ```bash git add src/auth/* /ck:git cm # Commits only auth changes git add src/components/* /ck:git cm # Separate UI changes ``` **Performance Metrics**: | Metric | Haiku (Optimized) | Sonnet (Baseline) | Savings | |--------|-------------------|-------------------|---------| | Tokens | 5-8K | 25-30K | 81% | | Time | 10-15s | 45s | 67% | | Cost | $0.015 | $0.075 | 80% | **Workflow After Feature**: ```bash git status # Review changes /ck:git cm # Commit with auto-message git log -1 # Verify commit /ck:git cp # Push if satisfied ``` **Fix Push Failures**: ```bash git pull --rebase origin main # Pull latest # Resolve conflicts if any /ck:git cp # Retry push ``` ## Related Agents - [Code Reviewer](/docs/engineer/agents/code-reviewer) - Pre-commit code review - [Project Manager](/docs/engineer/agents/project-manager) - Overall project coordination - [Tester](/docs/engineer/agents/tester) - Pre-commit test verification ## Key Takeaway **git-manager automates professional Git operations with security-first conventional commits at 81% lower cost than baseline—no AI attribution, just clean commit history.** --- # Journal Writer Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/journal-writer # Journal Writer Agent Transform critical failures into brutally honest learning documents that capture technical details, emotional reality, and prevent future mistakes. ## Cognitive Framing This agent operates as an **Engineering diarist capturing technical difficulties with emotional honesty** — documenting not just what broke, but why it was missed, how the team felt, and what must change to prevent recurrence. ## Behavioral Checklist Before completing any journal entry, this agent verifies: - Root cause stated without euphemism: "we shipped without testing the migration" beats "an oversight occurred" - Specific technical detail included: at least one error message, metric, or code reference - Decision documented: what choice was made, what alternatives were rejected, and why - Lesson extractable: a future developer can read this and change their behavior - Emotional reality captured: the frustration, exhaustion, or relief is present — this is a diary, not a ticket - Next steps actionable: what must happen, who owns it, and when ## When to Use - Production down >30min or data loss - Critical bugs caught before release - Failed deployments causing outages - Repeated issues team keeps hitting ## Key Capabilities | Feature | What It Does | |---------|--------------| | Honest Documentation | Captures what failed without sugarcoating - includes error logs, stack traces, timeline | | Root Cause Analysis | Documents what was tried, why it failed, actual cause, systemic issues | | Emotional Context | Records team stress, pressure, relief - builds psychological safety through honesty | | Learning Extraction | Identifies lessons, prevention strategies, warning signs, process improvements | ## Common Use Cases **DevOps Engineer** discovering payment race condition ```bash /ck:journal Context: Found race condition in payment system 2hrs before release. Bug causes duplicate charges when users rapidly click "Buy Now". ``` Output: Full incident report with code snippets, failed attempts (DB constraints, optimistic locking), final fix (Stripe idempotency keys), emotional timeline, lessons learned, checklist for future payment code reviews --- **Backend Dev** after 6-hour production outage ```bash /ck:journal Context: Kubernetes CrashLoopBackOff on all pods for 6 hours. Rolled back - same error. No one knew why. ``` Output: Technical autopsy showing CI/CD silently failing (renamed npm script, old workflow config), cost breakdown ($16K revenue + support), 7 failed fix attempts, root cause (no build verification), new CI/CD checks added --- **Tech Lead** documenting near-miss ```bash /ck:journal Context: QA found SQL injection vulnerability in prod API. Would have exposed 50K user records if exploited. ``` Output: Vulnerability details, attack vectors, immediate patch, systemic causes (no parameterized queries, skipped security review), new secure coding standards, team training plan --- **Site Reliability Engineer** after Redis cluster split-brain ```bash /ck:journal Context: Redis cluster split-brain during network partition. Half the nodes thought they were primary. Data corruption. ``` Output: Network partition timeline, data inconsistency examples, recovery steps, why monitoring didn't catch it, new quorum configuration, chaos engineering tests added --- **Full Stack Dev** documenting performance crisis ```bash /ck:journal Context: API response times jumped from 200ms to 15sec. Unindexed DB query on 10M row table hitting production. ``` Output: Slow query log, missing index discovery, query plan analysis, why staging didn't catch it (small dataset), new query performance testing requirements, database review checklist ## Pro Tips - **Write immediately** - Emotional context fades fast, write while it's fresh - **Include failed attempts** - Learning comes from what didn't work - **Use real language** - "We f*cked up" not "encountered an unexpected issue" - **Show the numbers** - Downtime cost, time to fix, impact metrics - **Add code snippets** - Actual error logs, broken code, working fix - **Make it searchable** - Someone will have same problem, use clear tags - **Blame the system** - Not individuals - focus on process failures that allowed it ## Related Agents - [Debugger](/docs/engineer/agents/debugger) - Debug the issues being documented - [Project Manager](/docs/engineer/agents/project-manager) - Track improvements from learnings - [Fullstack Developer](/docs/engineer/agents/fullstack-developer) - Implement preventive fixes ## Key Takeaway Journal Writer transforms expensive failures into permanent institutional knowledge through brutally honest documentation - capturing technical details, emotional reality, failed attempts, and systemic causes so teams learn once instead of failing repeatedly. Part of ClaudeKit $99 toolkit. --- # Fullstack Developer Agent Section: engineer Category: agents URL: https://docs.claudekit.cc/docs/agents/fullstack-developer # Fullstack Developer Agent **Execute parallel-safe implementation phases across backend, frontend, and infrastructure with strict file ownership enforcement.** ## Cognitive Framing This agent operates as a **Senior Full-Stack Engineer shipping production features end-to-end** — from API contracts to UI components, with quality gates enforced at every layer. ## Behavioral Checklist Before completing any implementation phase, this agent verifies: - Error handling: every async operation has explicit error handling, no silent failures - Input validation: all data entering the system from external sources is validated at the boundary - No TODO/FIXME left: if a workaround was needed, it is documented and tracked, not buried - Clean interfaces: public APIs are minimal, typed, and match the spec exactly - File ownership respected: only modified files listed in phase's "File Ownership" section - Tests added: new logic has unit tests covering happy path and key failure cases - Type safety: no `any` escapes without explicit justification in a comment - Build passes: compile or typecheck runs clean before reporting complete ## When to Use - Implementing phases from `/ck:plan --parallel` output - Running backend + frontend work simultaneously without conflicts - Need file-level isolation for parallel execution - Building full-stack features (API + UI + tests) ## Key Capabilities | Area | Details | |------|---------| | **Backend** | Node.js, Express APIs, auth, database ops | | **Frontend** | React, TypeScript, components, styling | | **Infrastructure** | Config, env setup, deployment scripts | | **Parallel Safety** | File ownership enforcement, conflict detection | | **Quality** | Type checking, tests, success criteria validation | ## Common Use Cases | Who | Prompt | Outcome | |-----|--------|---------| | **Team Lead** | `/ck:cook plans/251201-user-api/phase-02-endpoints.md` | Executes Phase 02 API endpoints with ownership boundaries | | **Developer** | Execute backend + frontend phases simultaneously | Safe parallel execution, no file conflicts | | **PM** | `/ck:plan --parallel Add CRUD API + React dashboard` → `/ck:cook` phases | Full implementation with automated reports | ## How It Works **1. Phase Analysis** - Reads `phase-XX-*.md` from plan directory - Validates file ownership (exclusive files only) - Checks parallelization info and dependencies **2. Implementation** - Follows steps from phase file - Only touches files in "File Ownership" section - **NEVER** modifies files owned by other phases **3. Quality Assurance** ```bash npm run typecheck # Must pass npm test # Must pass ``` **4. Report Output** ``` {active-plan}/reports/fullstack-dev-{YYMMDD}-phase-{XX}-{topic}.md ``` ## File Ownership Example ```markdown # Phase 02: API Endpoints ## File Ownership (Exclusive) - src/api/users.ts - src/schemas/*.ts - tests/api/*.test.ts ## Shared (Read-Only) - src/types/index.ts ``` **Critical Rules:** - **NEVER** modify files not in ownership list - **STOP** immediately if conflict detected - Only read shared files, never write ## Parallel Execution Safety ``` Phase 02 (Backend) Phase 03 (Frontend) ├── src/api/ ├── src/components/ ├── src/schemas/ ├── src/hooks/ └── tests/api/ └── tests/components/ No overlap → Safe for parallel execution ``` **Independence principles:** - Work without checking other phases' progress - Trust dependencies listed in phase file - Report completion to unblock dependent phases ## Pro Tips 1. **Read First**: Check `.claude/active-plan` for current plan path 2. **Ownership Strict**: If not in ownership list, don't touch it 3. **Phase Order**: Sequential phases (01, 04) must run in order; parallel phases (02, 03) can run simultaneously 4. **YAGNI**: Only implement what's in the phase spec, nothing more 5. **Token Efficiency**: Concise implementation, minimal overhead ## Related Agents - [Planner Agent](/docs/engineer/agents/planner) - Creates implementation plans - [Scout Agent](/docs/engineer/skills/scout) - Gathers external context before planning ## Key Takeaway **Fullstack Developer executes implementation phases with file-level isolation, enabling safe parallel backend/frontend development while maintaining code quality through automated testing.** --- # CLAUDE.md Section: engineer Category: configuration URL: https://docs.claudekit.cc/docs/configuration/claude-md # CLAUDE.md The `CLAUDE.md` file is the primary configuration file that provides guidance to Claude Code when working with your codebase. Understanding this file is crucial for effective use of ClaudeKit. ## What is CLAUDE.md? `CLAUDE.md` serves as the entry point for Claude Code's understanding of your project. It contains: - Role and responsibilities definitions - Links to detailed workflow documentation - References to development rules - Documentation management guidelines ## File Structure A typical `CLAUDE.md` file looks like this: ```markdown # CLAUDE.md This file provides guidance to Claude Code when working with code in this repository. ## Role & Responsibilities Your role is to analyze user requirements, delegate tasks to appropriate sub-agents, and ensure cohesive delivery of features that meet specifications and architectural standards. ## Workflows - Primary workflow: `./.claude/workflows/primary-workflow.md` - Development rules: `./.claude/workflows/development-rules.md` - Orchestration protocols: `./.claude/workflows/orchestration-protocol.md` - Documentation management: `./.claude/workflows/documentation-management.md` ## Documentation Management We keep all important docs in `./docs` folder and keep updating them. ``` ## Why File System As Context? ClaudeKit follows Manus's approach to Context Engineering: **Use File System As Context**. ### Benefits 1. **Token Efficiency**: CLAUDE.md contains just a few lines with links to detailed files 2. **On-Demand Loading**: Detailed instructions are loaded only when needed 3. **Better Organization**: Related documentation is grouped in logical directories 4. **Easier Maintenance**: Update specific files without touching CLAUDE.md ### Example Instead of putting all development rules in CLAUDE.md: ```markdown ❌ Bad Approach (All in CLAUDE.md) # CLAUDE.md ## Development Rules 1. Always write tests 2. Follow TypeScript strict mode 3. Use conventional commits ... (hundreds of lines) ``` ClaudeKit uses references: ```markdown ✅ Good Approach (File System As Context) # CLAUDE.md ## Workflows - Development rules: `./.claude/workflows/development-rules.md` ``` This keeps CLAUDE.md lightweight while maintaining access to detailed guidelines. ## Important: Do Not Modify **[Important]** You should not modify `CLAUDE.md` directly, as it will be overwritten each time you update ClaudeKit using `ck init`. ### Why? - ClaudeKit updates may include improvements to workflows and rules - Manual changes will be lost during updates - Consistency across ClaudeKit projects ### What if I need to customize? If you want to modify `CLAUDE.md` without it being overwritten: ```bash # Use the exclude flag during updates ck init --exclude CLAUDE.md ``` **Better approach**: Instead of modifying CLAUDE.md, customize the referenced files in `.claude/workflows/` which are less likely to change during updates. ## Structure Overview CLAUDE.md links to several key directories: ### `.claude/workflows/` Contains detailed workflow instructions: - `development-rules.md` - Code quality standards, subagent orchestration, pre-commit procedures - `documentation-management.md` - Documentation standards and practices - `orchestration-protocol.md` - Agent orchestration methods - `primary-workflow.md` - Development workflow from code to deployment ### `docs/` Project-specific documentation: ``` docs/ ├── project-overview-pdr.md ├── code-standards.md ├── codebase-summary.md ├── design-guidelines.md ├── deployment-guide.md ├── system-architecture.md └── project-roadmap.md ``` These files help Claude Code: - Avoid hallucinations - Prevent creating redundant code - Understand project-specific patterns - Follow established conventions ## How Claude Code Uses CLAUDE.md ### Initial Load 1. Claude Code reads `CLAUDE.md` when started 2. Understands the project's role and structure 3. Knows where to find detailed instructions ### During Tasks When performing specific tasks, Claude Code: 1. References linked workflow files 2. Reads relevant documentation from `docs/` 3. Follows established patterns and rules 4. Updates documentation as needed ### Example Flow ``` User: "Add user authentication" ↓ Claude reads CLAUDE.md ↓ Loads development-rules.md ↓ Checks code-standards.md ↓ Reviews system-architecture.md ↓ Implements following patterns ↓ Updates documentation ``` ## Best Practices ### Do's ✅ Keep CLAUDE.md concise with links to detailed docs ✅ Update workflow files in `.claude/workflows/` as needed ✅ Maintain project docs in `docs/` directory ✅ Use `ck init --exclude CLAUDE.md` if you must customize ### Don'ts ❌ Don't put all documentation in CLAUDE.md ❌ Don't modify CLAUDE.md without understanding update implications ❌ Don't ignore the linked workflow files ❌ Don't skip documentation management ## Token Consumption Using File System As Context significantly reduces token usage: **Without File System As Context:** - Initial load: ~5000 tokens (everything in CLAUDE.md) - Every task: Same 5000 tokens loaded **With File System As Context (ClaudeKit approach):** - Initial load: ~500 tokens (just CLAUDE.md) - Specific task: +1000 tokens (only relevant file) - Total: 1500 tokens vs 5000 tokens (70% savings) ## Validation Ensure your CLAUDE.md is properly configured: ```bash # Check if CLAUDE.md exists cat CLAUDE.md # Verify linked files exist ls .claude/workflows/ # Check documentation structure ls docs/ ``` ## Next Steps Now that you understand CLAUDE.md: - [Workflows](/docs/engineer/configuration/workflows) - Learn about workflow files - [Agents](/docs/engineer/agents/) - Understand the agent system - [Skills](/docs/engineer/skills) - Explore available skills --- **Key Takeaway**: CLAUDE.md is a lightweight entry point that uses the file system as context, making ClaudeKit efficient and maintainable. --- # Workflows Section: engineer Category: configuration URL: https://docs.claudekit.cc/docs/configuration/workflows # Workflows Workflows are the backbone of ClaudeKit's agent coordination system. They provide detailed instructions that ensure agents work together cohesively and follow project standards. ## What are Workflows? Workflows are markdown files stored in `.claude/workflows/` that contain: - Development guidelines and rules - Agent coordination protocols - Documentation standards - Implementation patterns - Quality assurance procedures ## Workflow Files ClaudeKit includes four core workflow files: ### 1. development-rules.md **Purpose**: Comprehensive development guidelines **Contains:** - Code quality standards - Subagent orchestration rules - Pre-commit/push procedures - Implementation principles - Testing requirements - Code review criteria **When Used:** - During feature implementation - Before committing code - During code review - When refactoring **Key Sections:** ```markdown ## Code Quality Standards - TypeScript strict mode - ESLint configuration - Prettier formatting - Test coverage requirements ## Subagent Orchestration - When to use parallel agents - Sequential agent workflows - Agent handoff protocols ## Pre-commit Procedures - Run tests - Check types - Lint code - Update documentation ``` ### 2. documentation-management.md **Purpose**: Documentation standards and maintenance **Contains:** - Documentation structure requirements - When to update docs - Documentation formats - API documentation standards - Changelog management **When Used:** - After implementing features - During refactoring - When updating APIs - For new team members **Key Sections:** ```markdown ## Documentation Standards - Code comments - API documentation - Architecture diagrams - User guides ## Update Triggers - New features - API changes - Breaking changes - Configuration updates ## File Locations - docs/ - Project documentation - README.md - Project overview - CHANGELOG.md - Version history ``` **Why Important:** - Prevents hallucinations by providing context - Avoids redundant code creation - Maintains consistency across codebase ### 3. orchestration-protocol.md **Purpose**: Methods for coordinating multiple agents **Contains:** - Parallel agent initialization - Sequential agent workflows - Agent communication patterns - Task delegation strategies **When Used:** - Complex multi-step tasks - Large feature implementations - System-wide refactoring - Performance optimization **Orchestration Patterns:** **Parallel Orchestration:** ```markdown Use when tasks are independent: - Multiple code reviews - Concurrent testing - Parallel documentation updates Example: 1. Launch scout agents simultaneously 2. Each scans different directories 3. Aggregate results 4. Proceed with unified plan ``` **Sequential Orchestration:** ```markdown Use when tasks depend on each other: 1. Planner agent creates plan 2. Code agent implements 3. Tester agent validates 4. Reviewer agent checks quality 5. Git agent commits changes ``` **Hybrid Orchestration:** ```markdown Combine parallel and sequential: 1. Parallel: Scout agents scan codebase 2. Sequential: Planner creates unified plan 3. Parallel: Multiple code agents implement 4. Sequential: Tester validates all changes 5. Sequential: Git agent commits ``` ### 4. primary-workflow.md **Purpose**: End-to-end development workflow **Contains:** - Implementation workflow steps - Testing procedures - Code review process - Integration protocols - Debugging strategies - Reporting requirements **Standard Workflow:** ```mermaid graph TD A[User Request] --> B[Planner Agent] B --> C[Code Agent] C --> D[Tester Agent] D --> E{Tests Pass?} E -->|No| F[Debugger Agent] F --> C E -->|Yes| G[Code Reviewer Agent] G --> H{Review Pass?} H -->|No| I[Refactor] I --> C H -->|Yes| J[Git Agent] J --> K[Documentation Update] K --> L[Complete] ``` **Workflow Stages:** 1. **Planning**: Analyze requirements, create implementation plan 2. **Implementation**: Write code following standards 3. **Testing**: Run tests, validate functionality 4. **Review**: Check code quality, security, performance 5. **Integration**: Commit changes, update docs 6. **Debugging**: Fix issues if tests or review fail 7. **Reporting**: Document changes and decisions ## How Workflows Work Together ### Example: Implementing a New Feature ``` User: "Add user authentication" 1. Primary Workflow Activates ├─ development-rules.md loaded └─ Checks code standards 2. Orchestration Protocol Determines Approach ├─ Sequential workflow chosen └─ Agents queued in order 3. Planner Agent ├─ Reads documentation-management.md ├─ Reviews docs/system-architecture.md └─ Creates implementation plan 4. Code Agent ├─ Follows development-rules.md ├─ Implements authentication └─ Adheres to code standards 5. Tester Agent ├─ Runs test suite └─ Validates security 6. Code Reviewer Agent ├─ Checks against development-rules.md └─ Validates best practices 7. Documentation Manager ├─ Follows documentation-management.md └─ Updates docs/ 8. Git Agent ├─ Creates conventional commit └─ Pushes changes ``` ## Workflow Benefits ### Consistency All agents follow the same rules and patterns, ensuring: - Uniform code style - Consistent documentation - Predictable behavior - Standardized commits ### Quality Assurance Workflows enforce: - Test coverage requirements - Code review standards - Security best practices - Performance benchmarks ### Coordination Multiple agents work together efficiently: - Clear handoff protocols - No duplicate work - Efficient task distribution - Proper error handling ### Maintainability Well-defined workflows make it easier to: - Onboard new team members - Update development practices - Scale projects - Debug issues ## Customizing Workflows While CLAUDE.md shouldn't be modified, workflow files can be customized: ### Safe to Modify ✅ **development-rules.md** - Add project-specific rules ✅ **documentation-management.md** - Adjust doc structure ✅ **orchestration-protocol.md** - Define custom patterns ### Example Customization ```markdown # development-rules.md ## Project-Specific Rules ### API Design - RESTful endpoints only - Versioned URLs (/v1/users) - JSON responses - Rate limiting required ### Database - PostgreSQL queries use parameterized statements - Migrations before code changes - No raw SQL in business logic ``` ### Best Practices for Customization 1. **Document Changes**: Note why custom rules exist 2. **Test Impact**: Verify agents follow new rules 3. **Team Alignment**: Ensure team agrees on changes 4. **Version Control**: Track workflow changes in git 5. **Backup**: Keep original files for reference ## Workflow Validation Ensure workflows are properly configured: ```bash # Check workflow files exist ls .claude/workflows/ # Should show: # - development-rules.md # - documentation-management.md # - orchestration-protocol.md # - primary-workflow.md # Verify file contents cat .claude/workflows/development-rules.md ``` ## Common Issues ### Agents Not Following Rules **Problem**: Agent behavior inconsistent with workflow rules **Solutions:** 1. Verify workflow files are in correct location 2. Check file permissions (must be readable) 3. Ensure CLAUDE.md references correct paths 4. Review agent logs for errors ### Conflicting Workflows **Problem**: Different workflows give contradictory instructions **Solutions:** 1. Review all workflow files for conflicts 2. Establish clear priority order 3. Consolidate overlapping rules 4. Update CLAUDE.md if needed ### Outdated Workflows **Problem**: Workflows don't match current project needs **Solutions:** 1. Review and update workflow files 2. Run `ck init` to get latest ClaudeKit workflows 3. Merge custom changes with updates 4. Document customizations ## Next Steps Now that you understand workflows: - [Agents](/docs/engineer/agents/) - Learn about the 14 specialized agents - [Skills](/docs/engineer/skills) - Explore available skills - [Development Rules](/.claude/workflows/development-rules.md) - Read the full development rules --- **Key Takeaway**: Workflows ensure all agents follow consistent patterns and coordinate effectively, resulting in high-quality, maintainable code. --- # Hooks Section: engineer Category: configuration URL: https://docs.claudekit.cc/docs/configuration/hooks # Hooks Hooks allow you to extend Claude Code with custom scripts that run at specific points in the workflow. ClaudeKit Engineer includes pre-built hooks for file access control, naming guidance, simplification gates, statusline rendering, optional session context, and notifications. ## Overview Hooks are configured in `.claude/settings.json` and execute shell commands in response to Claude Code events. > **Current default (v2.19.0+):** ClaudeKit installs only lightweight safety and workflow hooks by default. Generated session/subagent/usage context hooks are opt-in and are pruned from existing installs during `ck update` or `ck migrate`. ### Available Hook Events | Event | When Triggered | |-------|----------------| | `SessionStart` | When a Claude Code session begins | | `SubagentStart` | When a Task tool spawns a subagent | | `UserPromptSubmit` | Before user prompt is processed | | `PreToolUse` | Before a tool executes | | `PostToolUse` | After a tool executes | | `TaskCompleted` | When a task is marked completed | | `TeammateIdle` | When an Agent Team member goes idle | | `Stop` | When Claude session ends | | `SubagentStop` | When a subagent completes | ## Configuration Hooks are defined in `.claude/settings.json`: ```json { "statusLine": { "type": "command", "command": "bash .claude/hooks/node-hook-runner.sh .claude/statusline.cjs", "padding": 0 }, "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "bash .claude/hooks/node-hook-runner.sh .claude/hooks/simplify-gate.cjs" } ] } ], "PreToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": "bash .claude/hooks/node-hook-runner.sh .claude/hooks/descriptive-name.cjs" } ] }, { "matcher": "Bash|Glob|Grep|Read|Edit|Write", "hooks": [ { "type": "command", "command": "bash .claude/hooks/node-hook-runner.sh .claude/hooks/scout-block.cjs" }, { "type": "command", "command": "bash .claude/hooks/node-hook-runner.sh .claude/hooks/privacy-block.cjs" } ] } ] } } ``` ### Hook Properties - **type**: Always `"command"` for shell execution - **command**: Shell command to run - **matcher**: (PreToolUse only) Regex to match tool names ## Built-in Hooks ClaudeKit Engineer ships with hooks organized by event type. All default hook files live in `.claude/hooks/`. Shared utilities are in `.claude/hooks/lib/`. Notification providers are in `.claude/hooks/notifications/`. ### Summary Table | Hook File | Default | Event | Purpose | |-----------|---------|-------|---------| | `simplify-gate.cjs` | Yes | `UserPromptSubmit` | Enforce simplification workflow rules when relevant | | `descriptive-name.cjs` | Yes | `PreToolUse` (Write) | Inject file naming guidance: kebab-case, language conventions | | `scout-block.cjs` | Yes | `PreToolUse` (Bash/Glob/Grep/Read/Edit/Write) | Block access to `.ckignore`-listed directories | | `privacy-block.cjs` | Yes | `PreToolUse` (Bash/Glob/Grep/Read/Edit/Write) | Block sensitive files, require user approval | | `session-init.cjs` | No | `SessionStart` | Load config, detect project, persist env vars | | `subagent-init.cjs` | No | `SubagentStart` | Inject minimal context to subagents | | `team-context-inject.cjs` | No | `SubagentStart` | Inject peer info + task summary for Agent Team members | | `cook-after-plan-reminder.cjs` | No | `SubagentStop` (Plan) | Print user-choice guidance after planning | | `dev-rules-reminder.cjs` | No | `UserPromptSubmit` | Inject session context, rules, modularization, Plan Context | | `usage-context-awareness.cjs` | No | `UserPromptSubmit` + `PostToolUse` | Fetch usage limits, write to cache | | `post-edit-simplify-reminder.cjs` | No | `PostToolUse` (Edit/Write/MultiEdit) | Remind about code-simplifier after repeated edits | | `task-completed-handler.cjs` | No | `TaskCompleted` | Log completions, inject progress for Agent Team leads | | `teammate-idle-handler.cjs` | No | `TeammateIdle` | Inject available task context when team member goes idle | The hooks marked `No` are no longer installed by default because they generate context on session, prompt, subagent, or tool events. Existing installations are cleaned up idempotently by the CLI during update and migration. --- ### session-init.cjs **Event:** `SessionStart` **Purpose:** Runs once when a Claude Code session begins. Loads `.claude/.env`, detects the current project, and persists environment variables for the session. **What it does:** - Reads `.claude/.env` and `.env` files and exports variables to the session - Detects project type (Next.js, Express, etc.) and sets `CK_PROJECT_TYPE` - Stores session metadata for hooks that run later in the session --- ### subagent-init.cjs **Event:** `SubagentStart` **Purpose:** Injects minimal context (~200 tokens) into subagents spawned by the Task tool. Keeps subagent prompts lean while ensuring they have the critical paths and config they need. **What it does:** - Injects CWD, plan directory, reports directory - Passes `CK_SESSION_ID` and project type to subagents - Does NOT inject full rules (those come from `dev-rules-reminder.cjs`) --- ### team-context-inject.cjs **Event:** `SubagentStart` **Purpose:** Used in Agent Team workflows. Injects peer agent names, task summary, and coordination context into team member subagents. **What it does:** - Reads team config from `.claude/teams/` - Injects available peer names and their current task status - Provides file ownership boundaries from the active task > Only active when `CK_TEAM_MODE=1` is set. --- ### cook-after-plan-reminder.cjs **Event:** `SubagentStop` (matcher: Plan subagents) **Purpose:** After a planning subagent completes, prints boundary guidance so Claude stops before implementation and presents the available next steps. **What it does:** - Detects if the stopping subagent was a planner - Prints an optional `/ck:cook ` command with the generated plan path - Keeps planning and implementation separated until the user approves implementation - Mentions `--auto` only as an explicit opt-in for autonomous implementation --- ### dev-rules-reminder.cjs **Event:** `UserPromptSubmit` **Purpose:** Injects session context, development rules, modularization guidelines, and Plan Context into Claude's context before each user prompt. **What it does:** - Reads `.claude/workflows/development-rules.md` and injects key rules - Injects active Plan Context (current plan directory) from session state - Reminds about modularization limits (200-line files) - Ensures consistent code quality standards across prompts --- ### usage-context-awareness.cjs **Event:** `UserPromptSubmit` + `PostToolUse` **Purpose:** Fetches Claude Code usage limits from the API and writes them to a cache file. Throttled to avoid excessive API calls. Helps Claude be aware of remaining token budget. **What it does:** - Reads cached usage data from `.claude/.usage-cache.json` (max 60s old) - Fetches fresh usage stats if cache is stale - Injects remaining token budget into context - Silently skips if `ANTHROPIC_API_KEY` is not set --- ### descriptive-name.cjs **Event:** `PreToolUse` (matcher: `Write`) **Purpose:** Injects file naming guidance before Claude writes a new file, enforcing kebab-case and language-specific conventions. **What it does:** - Detects the target file path from the Write tool parameters - Checks if the name follows kebab-case (for most files) or language conventions (e.g., PascalCase for React components) - Injects a reminder if the name is non-descriptive or uses the wrong convention --- ### scout-block.cjs **Event:** `PreToolUse` (matcher: `Bash|Glob|Grep|Read|Edit|Write`) **Purpose:** Blocks file system access to directories listed in `.ckignore`. Allows build commands (e.g., `npm run build`) to pass through. **What it does:** - Reads the shipped `.ckignore` baseline and then layers an optional git-root `./.claude/.ckignore` override - Blocks Read/Edit/Write/Glob/Grep operations on matched paths - Allows Bash commands that are recognized build/test commands - Returns a clear error message explaining which path is blocked and which `.ckignore` file to edit --- ### privacy-block.cjs **Event:** `PreToolUse` (matcher: `Bash|Glob|Grep|Read|Edit|Write`) **Purpose:** Blocks access to sensitive files (`.env`, credentials, private keys). Requires explicit user approval via `AskUserQuestion` before allowing access. **What it does:** - Matches file paths against a list of sensitive patterns (`.env*`, `*.pem`, `*.key`, `credentials.*`, etc.) - On match: returns a `@@PRIVACY_PROMPT@@` JSON marker that triggers the `AskUserQuestion` flow - If user approves: Claude uses `bash cat` to read the file (bypasses the hook) - If user denies: continues without the sensitive file > See `$HOME/.claude/CLAUDE.md` → "Hook Response Protocol" for the full `@@PRIVACY_PROMPT@@` flow. --- ### post-edit-simplify-reminder.cjs **Event:** `PostToolUse` (matcher: `Edit|Write|MultiEdit`) **Purpose:** Tracks the number of file edits in the current session. After 5 or more edits, injects a reminder to run the `code-simplifier` agent to review accumulated complexity. **What it does:** - Increments edit counter in session state after each Edit/Write/MultiEdit - At threshold (default: 5), injects: "You've made N edits. Consider invoking `/simplify` to review accumulated complexity." - Resets counter after reminder is shown --- ### task-completed-handler.cjs **Event:** `TaskCompleted` **Purpose:** Logs task completions to `.claude/logs/tasks.log`. In Agent Team mode, injects progress summary for the lead agent. **What it does:** - Appends task ID, subject, completion time, and owner to the task log - If `CK_TEAM_MODE=1`: formats a progress summary showing completed vs total tasks and injects it into lead's context --- ### teammate-idle-handler.cjs **Event:** `TeammateIdle` **Purpose:** When an Agent Team member goes idle (waiting for input), injects available unblocked task context so they can claim the next task without waiting for a message. **What it does:** - Reads `TaskList` for unblocked pending tasks - Formats task summary and injects it as context - Prevents teammates from staying idle when work is available --- ### Discord Notifications **File:** `.claude/hooks/send-discord.sh` **Purpose:** Sends rich notifications to Discord when tasks complete. > **Note:** Discord notifications are triggered manually in workflows, not automatically via hook events. This is intentional for flexibility. **Setup:** 1. **Create Discord Webhook:** - Discord Server → Settings → Integrations → Webhooks - Create webhook, copy URL 2. **Configure Environment:** ```bash # .env or .claude/.env DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN ``` 3. **Make Executable:** ```bash chmod +x .claude/hooks/send-discord.sh ``` 4. **Test:** ```bash ./.claude/hooks/send-discord.sh 'Test notification' ``` **Usage in Workflows:** ```markdown - When implementation complete, run: `./.claude/hooks/send-discord.sh 'Task completed: [summary]'` ``` **Message Format:** ``` ╔═══════════════════════════════════════╗ ║ 🤖 Claude Code Session Complete ║ ╠═══════════════════════════════════════╣ ║ Implementation Complete ║ ║ ║ ║ ✅ Added user authentication ║ ║ ✅ Created login/signup forms ║ ║ ✅ All tests passing ║ ╠═══════════════════════════════════════╣ ║ ⏰ Session Time: 14:30:45 ║ ║ 📂 Project: my-project ║ ╚═══════════════════════════════════════╝ ``` ### Telegram Notifications **File:** `.claude/hooks/telegram_notify.sh` **Purpose:** Sends detailed notifications to Telegram with tool usage stats. **Setup:** 1. **Create Telegram Bot:** - Message @BotFather on Telegram - Send `/newbot`, follow prompts - Copy bot token 2. **Get Chat ID:** ```bash # After messaging your bot, run: curl -s "https://api.telegram.org/bot/getUpdates" | jq '.result[-1].message.chat.id' ``` 3. **Configure Environment:** ```bash # .env or .claude/.env TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz TELEGRAM_CHAT_ID=987654321 ``` 4. **Configure Hook (add to `.claude/settings.json`):** > **Note:** Telegram hooks are not configured by default. Add this to your `settings.json` to enable automatic notifications. ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/telegram_notify.sh" } ] } ], "SubagentStop": [ { "hooks": [ { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/telegram_notify.sh" } ] } ] } } ``` **Message Format:** ``` 🚀 Project Task Completed 📅 Time: 2025-10-22 14:30:45 📁 Project: my-project 🔧 Total Operations: 15 🆔 Session: abc12345... Tools Used: 5 Edit 3 Read 2 Bash 2 Write Files Modified: • src/auth/service.ts • src/utils/validation.ts • tests/auth.test.ts 📍 Location: /Users/user/projects/my-project ``` ## Notification System Notification providers live in `.claude/hooks/notifications/`. Each provider is a standalone module that reads from environment variables. | Provider | File | Event | |----------|------|-------| | Discord | `notifications/discord.cjs` | `Stop`, `SubagentStop` | | Slack | `notifications/slack.cjs` | `Stop`, `SubagentStop` | | Telegram | `notifications/telegram.cjs` | `Stop`, `SubagentStop` | Configure providers by setting the relevant env vars (see Discord/Telegram sections below) and adding them to `settings.json` hooks. The provider scripts are called by the main notification orchestrator. ## Creating Custom Hooks ### Basic Hook Structure ```javascript // .claude/hooks/my-hook.cjs // Read hook input from stdin (JSON) let input = ''; process.stdin.on('data', chunk => input += chunk); process.stdin.on('end', () => { const data = JSON.parse(input); // Hook logic here console.log('Hook triggered:', data.hookType); // Exit 0 for success, non-zero to block process.exit(0); }); ``` ### Hook Input Data **UserPromptSubmit:** ```json { "hookType": "UserPromptSubmit", "projectDir": "/path/to/project", "prompt": "User's prompt text" } ``` **PreToolUse:** ```json { "hookType": "PreToolUse", "projectDir": "/path/to/project", "tool": "Edit", "parameters": { "file_path": "/path/to/file.ts", "old_string": "...", "new_string": "..." } } ``` **Stop:** ```json { "hookType": "Stop", "projectDir": "/path/to/project", "sessionId": "abc123", "toolsUsed": [ {"tool": "Read", "parameters": {"file_path": "..."}}, {"tool": "Edit", "parameters": {"file_path": "..."}} ] } ``` ### Example: Logging Hook ```javascript // .claude/hooks/log-tools.cjs const fs = require('fs'); let input = ''; process.stdin.on('data', chunk => input += chunk); process.stdin.on('end', () => { const data = JSON.parse(input); const logEntry = { timestamp: new Date().toISOString(), hookType: data.hookType, tool: data.tool, file: data.parameters?.file_path }; fs.appendFileSync('logs.txt', JSON.stringify(logEntry) + '\n'); process.exit(0); }); ``` ### Example: Blocking Hook ```javascript // .claude/hooks/prevent-secrets.cjs let input = ''; process.stdin.on('data', chunk => input += chunk); process.stdin.on('end', () => { const data = JSON.parse(input); // Block edits to .env files if (data.tool === 'Edit' && data.parameters?.file_path?.includes('.env')) { console.error('Blocked: Cannot edit .env files directly'); process.exit(1); // Non-zero exits block the action } process.exit(0); }); ``` ## Environment Variables Hooks can access these environment variables: | Variable | Description | |----------|-------------| | `CLAUDE_PROJECT_DIR` | Project root directory | | `CLAUDE_SESSION_ID` | Current session identifier | | Custom variables | From `.env` files | ### Loading .env Files ClaudeKit hooks load environment variables in this priority: 1. System environment variables 2. `.claude/.env` (project-level) 3. `.claude/hooks/.env` (hook-specific) ## Best Practices ### Security 1. **Never commit secrets:** ```bash # .gitignore .env .env.* ``` 2. **Use environment variables** for tokens and URLs 3. **Rotate webhook tokens** regularly 4. **Limit hook permissions** to necessary scope ### Performance 1. **Keep hooks lightweight** - they run on every event 2. **Use async operations** for slow tasks 3. **Exit quickly** if no action needed ### Reliability 1. **Handle errors gracefully** 2. **Log hook failures** for debugging 3. **Test hooks manually** before deployment ## Troubleshooting ### Hook Not Triggering **Solutions:** 1. Verify hook in `settings.json` is valid JSON 2. Check script is executable (`chmod +x`) 3. Verify path is correct 4. Test script manually ### Hook Blocking Unexpectedly **Solutions:** 1. Check exit code (0 = allow, non-zero = block) 2. Review matcher regex for PreToolUse 3. Add logging to debug ### Environment Variables Not Loading **Solutions:** 1. Check `.env` file exists and has correct format 2. Verify no spaces around `=` in `.env` 3. Ensure script reads `.env` files ## Related - [CLAUDE.md](/docs/engineer/configuration/claude-md) - Project instructions - [MCP Setup](/docs/engineer/configuration/mcp-setup) - MCP server configuration - [Workflows](/docs/engineer/configuration/workflows) - Development workflows --- **Key Takeaway**: Hooks extend Claude Code with custom automation - from development rule enforcement to real-time notifications. Use built-in Discord/Telegram hooks or create custom hooks to fit your workflow. --- # MCP Setup Section: engineer Category: configuration URL: https://docs.claudekit.cc/docs/configuration/mcp-setup # MCP Setup ## TL;DR ClaudeKit routes MCP (Model Context Protocol) server usage through `/ck:use-mcp`. This keeps heavy tool manifests out of the primary agent until a task actually needs MCP access. --- ## Setup Checklist 1. **Copy the template config** ```bash cp .claude/.mcp.json.example .claude/.mcp.json ``` 2. **Customize the MCP roster** - Remove the default sample servers: `context7`, `human-mcp`, `chrome-devtools`, `sequential-thinking`. - Add only the MCP servers you truly need to avoid unnecessary token use. 3. **Save the configuration** so `/ck:use-mcp` can load clients from `.claude/.mcp.json` on demand. > 💡 Keep `.claude/.mcp.json` outside your main prompts so the core agent never loads server manifests unless explicitly requested. --- ## Using MCP Tools Trigger configured tools via the `/ck:use-mcp` command: ```bash /ck:use-mcp ``` **Example** ```bash /ck:use-mcp Use chrome-devtools mcp to capture a screenshot of google.com ``` ClaudeKit loads the configured MCP clients, analyzes available tools, executes the best fit, and returns the results to your primary chat. --- ## Technical Deep Dive ![MCP proxy architecture](/assets/mcp-proxy.jpeg) ### Why This Architecture? Anthropic's “Code Execution with MCP” pattern inspired a lightweight approach: subagents have their own context windows. Loading MCP manifests directly into the main agent quickly bloats its context—especially with tool-heavy servers like Chrome DevTools or Playwright. By shifting those manifests into a subagent, the primary conversation stays clean even if dozens of MCP servers are configured. ![Context isolation](/assets/05-mcp-context.jpg) ### How It Works 1. The **use-mcp** skill reads `.claude/.mcp.json` only when a task asks for MCP access. 2. It can use an LLM-driven path for flexible tool selection or deterministic scripts for direct list/call workflows. 3. When invoked, the skill: - Loads `.claude/.mcp.json`. - Connects to the declared MCP servers. - Enumerates available tools and selects the best option for the prompt. - Executes the tool invocation and streams the response back to the main agent. The result: your main context stays pristine, yet you can still tap into specialized MCP capabilities. (Yes, the joke still stands—you *could* register 80 MCP servers, but please add only what you really need.) ### Further Optimization Even with subagent isolation, processing massive MCP catalogs still burns tokens. To mitigate that, ClaudeKit can hand off heavy MCP orchestration to **gemini-cli**, shifting the most expensive reasoning to a cheaper, external runtime while keeping the main conversation focused. --- ## Next Steps - Keep refining `.claude/.mcp.json` as your toolset evolves. - Version-control the file privately if it includes API endpoints or sensitive details. - Pair `/ck:use-mcp` with automation commands (e.g., `/ck:cook`, `/ck:fix`, `/ck:plan`) to mix bespoke tools with ClaudeKit’s native agents. With this workflow, you get the power of MCP without the usual context penalty. --- # Engineer Kit Section: engineer Category: overview URL: https://docs.claudekit.cc/docs/engineer/index # Engineer Kit Welcome to the ClaudeKit Engineer Kit documentation. This toolkit supercharges your development workflow with AI-powered automation. ## What's Inside The Engineer Kit includes: - **14 Specialized Agents** - From planning to deployment - **70+ Skills** - Slash-invokable development capabilities - **Workflow Automation** - Streamlined development processes ## Quick Start Get started with the Engineer Kit in just a few commands: ```bash # Install ClaudeKit CLI npm install -g claudekit-cli # Create a new engineer project ck new --kit engineer # Start building /ck:plan "implement user authentication" /ck:cook "add login form with validation" ``` ## Core Features ### Planning & Architecture Plan features and design systems with AI assistance: ```bash /ck:plan "implement payment integration" /ck:plan --parallel "refactor authentication system" ``` ### Code Generation Generate high-quality code with context awareness: ```bash /ck:cook "add REST API endpoints for users" /ck:cook "implement caching layer" ``` ### Testing & Quality Ensure code quality with automated testing: ```bash /ck:test "run full test suite" /ck:fix "resolve TypeScript errors" /ck:code-review "review recent changes" ``` ### Database & Infrastructure Manage databases and deployment with skills: ```bash /ck:debug "investigate slow database queries" /ck:cook "set up staging deployment pipeline" ``` ## Next Steps - [Engineer Agents](/docs/engineer/agents) - Meet your AI development team - [Engineer Skills](/docs/engineer/skills) - All available skills - [Engineer Workflows](/docs/engineer/configuration/workflows) - Hooks, agents, and settings --- # Skills Overview Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/index # Skills Overview 80+ specialized skills that extend Claude's capabilities — invoked with `/ck:skill-name` or loaded dynamically when you mention them. The engineer kit release archive bundles both engineer and core skills (83 total). Skills are sourced from [AgentKit](https://github.com/bestagentkits/agentkit) (`kits/engineer/` and `kits/core/`) and installed to `~/.claude/skills/` via `ck init -g --kit engineer`. :::tip[Commands → Skills Complete] As of engineer@2.12.0, all commands have been migrated to skills. The `/ck:` slash syntax is unchanged. See [Migration Guide](/docs/getting-started/migration-from-commands-to-skills). ::: ## Quick Reference ### Frontend & Design | Skill | Purpose | |-------|---------| | [frontend-design](/docs/engineer/skills/frontend-design) | Build memorable web interfaces with bold aesthetics | | [ui-ux-pro-max](/docs/engineer/skills/ui-ux-pro-max) | Production-ready UI with research-backed patterns | | [ui-styling](/docs/engineer/skills/ui-styling) | Tailwind patterns, responsive layouts, dark mode | | [frontend-development](/docs/engineer/skills/frontend-development) | React patterns, Suspense, state management | | [web-frameworks](/docs/engineer/skills/web-frameworks) | Next.js + Turborepo + RemixIcon stack | | [tanstack](/docs/engineer/skills/tanstack) | TanStack Start/Form/AI for full-stack React applications | | [threejs](/docs/engineer/skills/threejs) | 3D web experiences with WebGL/WebGPU | | [react-best-practices](/docs/engineer/skills/react-best-practices) | React and Next.js performance optimization from Vercel | | [web-design-guidelines](/docs/engineer/skills/web-design-guidelines) | Web Interface Guidelines compliance | | [web-testing](/docs/engineer/skills/web-testing) | Playwright, Vitest, k6 testing | | [shader](/docs/engineer/skills/shader) | GLSL fragment shaders for procedural graphics | | [remotion](/docs/engineer/skills/remotion) | Video creation in React | ### Backend & Infrastructure | Skill | Purpose | |-------|---------| | [backend-development](/docs/engineer/skills/backend-development) | Node.js, NestJS, security, testing patterns | | [databases](/docs/engineer/skills/databases) | Schema design, query optimization, migrations | | [devops](/docs/engineer/skills/devops) | CI/CD, deployment, infrastructure automation | ### AI & Multimodal | Skill | Purpose | |-------|---------| | [ai-multimodal](/docs/engineer/skills/ai-multimodal) | Gemini vision, audio, document processing | | [google-adk-python](/docs/engineer/skills/google-adk-python) | Google AI Development Kit for Python agents | | [ai-artist](/docs/engineer/skills/ai-artist) | Generate images via Nano Banana with curated prompts | ### Tools & Utilities | Skill | Purpose | |-------|---------| | [mcp-builder](/docs/engineer/skills/mcp-builder) | Create MCP servers (Python FastMCP / TypeScript) | | [skill-creator](/docs/engineer/skills/skill-creator) | Create custom skills for your projects | | [repomix](/docs/engineer/skills/repomix) | Pack repos into AI-friendly context files | | [document-skills](/docs/engineer/skills/document-skills) | PDF, DOCX, PPTX, XLSX processing | | [docs-seeker](/docs/engineer/skills/docs-seeker) | Find and retrieve external documentation | | [chrome-devtools](/docs/engineer/skills/chrome-devtools) | Browser automation, performance profiling | | [media-processing](/docs/engineer/skills/media-processing) | FFmpeg, ImageMagick, background removal | | [agent-browser](/docs/engineer/skills/agent-browser) | AI-optimized browser automation | | [markdown-novel-viewer](/docs/engineer/skills/markdown-novel-viewer) | Book-like markdown reading experience | | [context-engineering](/docs/engineer/skills/context-engineering) | Monitor and optimize token consumption | | [gkg](/docs/engineer/skills/gkg) | GitLab Knowledge Graph semantic analysis | | [mintlify](/docs/engineer/skills/mintlify) | Build and deploy modern documentation sites with Mintlify | ### Process & Methodology | Skill | Purpose | |-------|---------| | [plan](/docs/engineer/skills/ck-plan) | Transform requirements into executable plans | | [research](/docs/engineer/skills/research) | Multi-source validation before implementation | | [sequential-thinking](/docs/engineer/skills/sequential-thinking) | Numbered thought sequences for complex problems | | [problem-solving](/docs/engineer/skills/problem-solving) | Systematic approaches when stuck | | [debug](/docs/engineer/skills/ck-debug) | Root cause investigation framework | | [code-review](/docs/engineer/skills/code-review) | Verification gates and technical rigor | | [brainstorm](/docs/engineer/skills/brainstorm) | Trade-off analysis with brutal honesty | | [scout](/docs/engineer/skills/scout) | Fast parallel codebase scouting | | [cook](/docs/engineer/skills/cook) | Feature implementation workflow | | [fix](/docs/engineer/skills/fix) | Bug fixing with intelligent routing | | [git](/docs/engineer/skills/git) | Git operations with conventional commits | | [plans-kanban](/docs/engineer/skills/plans-kanban) | Open the integrated plans dashboard in the CLI UI | | [kanban](/docs/engineer/skills/kanban) | Alias for plans-kanban — visual plan board shortcut | | [project-management](/docs/engineer/skills/project-management) | Task tracking, plan status, session bridging | | [team](/docs/engineer/skills/team) | Agent Teams for parallel multi-session collaboration | | [ask](/docs/engineer/skills/ask) | Answer technical and architectural questions | | [bootstrap](/docs/engineer/skills/bootstrap) | Initialize new projects with spec-driven development | | [coding-level](/docs/engineer/skills/coding-level) | Set coding experience level for tailored output | | [docs](/docs/engineer/skills/docs) | Manage project documentation (init, update, summarize) | | [journal](/docs/engineer/skills/journal) | Write development journal entries | | [preview](/docs/engineer/skills/preview) | View files or generate visual explanations and diagrams | | [test](/docs/engineer/skills/test) | Run test suites, coverage analysis, build verification | | [use-mcp](/docs/engineer/skills/use-mcp) | Utilize MCP server tools | | [mcp-management](/docs/engineer/skills/mcp-management) | Discover, select, and execute MCP server capabilities | | [watzup](/docs/engineer/skills/watzup) | Review recent changes and wrap up sessions | | [worktree](/docs/engineer/skills/worktree) | Create isolated git worktrees | ### Integrations & Specialized | Skill | Purpose | |-------|---------| | [better-auth](/docs/engineer/skills/better-auth) | TypeScript auth (OAuth, 2FA, passkeys, multi-tenant) | | [shopify](/docs/engineer/skills/shopify) | Shopify apps, GraphQL API, checkout extensions | | [payment-integration](/docs/engineer/skills/payment-integration) | Stripe, PayPal, LemonSqueezy, SePay integration | | [mobile-development](/docs/engineer/skills/mobile-development) | React Native, Flutter, Swift/SwiftUI, Kotlin | | [copywriting](/docs/engineer/skills/copywriting) | Conversion copy formulas and templates | | [mermaidjs-v11](/docs/engineer/skills/mermaidjs-v11) | Diagram creation with Mermaid.js | | [find-skills](/docs/engineer/skills/find-skills) | Discover and install agent skills | ## How to Use **Basic invocation:** ``` "Use [skill-name] to [task]" ``` **Examples:** ``` "Use better-auth to add GitHub OAuth with 2FA" "Use devops to create production deployment" "Use debug to investigate this test failure" "Use frontend-design to build a SaaS landing page" ``` **Skill not activating?** Be explicit: ``` "Use the [skill-name] skill to..." ``` ## Under the Hood ### How Skills Activate Skills activate through **semantic matching** on your prompt: 1. Claude matches your request to skill descriptions 2. Relevant skill instructions load into context 3. Claude follows skill-specific patterns and best practices **Activation triggers:** - Mentioning the skill name explicitly - Describing a task that matches skill description - Using keywords from skill's domain ### Skill Structure Every skill contains: ``` # Source (AgentKit repo): agentkit/kits//skills/[skill-name]/ ├── SKILL.md # Core instructions ├── references/ # Detailed documentation └── scripts/ # Automation scripts (optional) # Installed location on your machine: ~/.claude/skills/[skill-name]/ # global (ck init -g) .claude/skills/[skill-name]/ # local (ck init) ``` **Progressive disclosure**: SKILL.md provides essentials, references/ has depth. ### Skills vs Agents | Aspect | Skills | Agents | |--------|--------|--------| | **Purpose** | Specialized knowledge + workflow orchestration | Task execution | | **Invocation** | `/skill-name` or "Use [skill]..." | Auto-spawned by skills | | **Scope** | Single capability or multi-step process | Autonomous work unit | | **Example** | /ck:plan, /ck:cook, /ck:fix, better-auth, devops | planner, tester, code-reviewer | :::note Commands and skills now use the same `/` invocation syntax. The "commands" concept has been unified into skills as of engineer@2.12.0. ::: ### Creating Custom Skills ``` "Use skill-creator to create a skill for [your-domain]" ``` skill-creator will: 1. Ask clarifying questions 2. Design skill structure 3. Create SKILL.md with proper frontmatter 4. Add references if needed 5. Save to `.claude/skills/` (local) or `~/.claude/skills/` (global) ### Troubleshooting **Skill not working?** - Check skill name spelling - Provide more context about your task - Try explicit invocation: "Use the X skill to..." **Need a skill that doesn't exist?** - Use skill-creator to build it - Request on [Discord](https://claudekit.cc/discord) ## Key Takeaway 70+ skills provide instant expertise—invoke with `/skill-name` or mention the skill and describe your task. No configuration needed. --- # ck:brainstorm Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/brainstorm # Brainstorm Your elite technical advisor for architecture decisions, system design, and strategic planning. This skill brings brutal honesty and deep expertise to help you make the right technical choices. ## What This Skill Does The Brainstorm skill transforms ClaudeKit into a senior architect who challenges your assumptions, explores alternatives, and provides frank feedback. It operates on the holy trinity of YAGNI, KISS, and DRY—every solution must honor these principles. Think of it as having a trusted technical advisor who will tell you hard truths before you waste time on over-engineered solutions. The skill asks probing questions, evaluates multiple approaches, and works with you to find the optimal path forward. ## Core Capabilities - System architecture design and scalability patterns - Risk assessment and mitigation strategies - Development time optimization and resource allocation - User Experience (UX) and Developer Experience (DX) optimization - Technical debt management and maintainability - Performance optimization and bottleneck identification ## The Process 1. **Scout Phase**: Understand current project state via docs and code 2. **Discovery Phase**: Clarifying questions about requirements and constraints 3. **Research Phase**: Gather information from docs, search, and other agents 4. **Analysis Phase**: Evaluate multiple approaches using YAGNI/KISS/DRY 5. **Debate Phase**: Present options, challenge preferences, find optimal solution 6. **Consensus Phase**: Ensure alignment on chosen approach 7. **Documentation Phase**: Create comprehensive summary report 8. **Finalize Phase**: Optional handoff to planner for implementation plan ## Usage Activate by typing `/ck:brainstorm` or mentioning ideation, architecture decisions, technical debates, or feature exploration. ## Example Prompts - "Should we use a microservices architecture or a modular monolith?" - "What's the best approach for real-time notifications in our app?" - "Help me evaluate these three database options for our use case" - "Is adding this feature worth the complexity it introduces?" - "How should we structure our API to support future mobile apps?" ## What Makes This Different The Brainstorm skill doesn't just generate ideas—it challenges yours. If your approach is unrealistic, over-engineered, or likely to cause problems, you'll hear about it directly. This prevents costly mistakes before you commit to a direction. ## Output Produces detailed markdown reports including: problem statement, evaluated approaches with pros/cons, final recommendation with rationale, implementation considerations, success metrics, and next steps. --- # ck:plan Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/ck-plan # Plan Creates structured, research-backed implementation plans in the active plan root. Project scope defaults to `plans/` in the current project. Global scope is allowed conditionally and resolves through the configured global plans root, defaulting to `~/.claude/plans/` when unset. Formerly split across `/ck:plan --fast`, `/ck:plan --hard`, and other commands—now consolidated into one skill. ## What This Skill Does Planning produces complete project blueprints: `plan.md` overview plus `phase-XX-*.md` files with implementation steps, file ownership, success criteria, and risk assessment. Plans persist across sessions and drive task hydration. ## Workflow Modes | Flag | Mode | Research | Red Team | Validation | Cook Flag | |------|------|----------|----------|------------|-----------| | `--auto` | Auto-detect | Follows mode | Follows mode | Follows mode | Follows detected mode | | `--fast` | Fast | Skip | Skip | Skip | (none) | | `--hard` | Hard | 2 researchers | Yes | Optional | (none) | | `--deep` | Deep | 2-3 researchers + per-phase scout | Yes | Yes | (none) | | `--parallel` | Parallel | 2 researchers | Yes | Optional | `--parallel` | | `--two` | Two approaches | 2+ researchers | After selection | After selection | (none) | Composable flags: - `--tdd` — add tests-first structure to each phase for regression-safe refactors - `--no-tasks` — skip task hydration after plan creation ## Usage ``` /ck:plan [flags] ``` **Examples:** - `/ck:plan "add Stripe subscription billing" --fast` - `/ck:plan "migrate from REST to GraphQL" --hard` - `/ck:plan "untangle the notification pipeline" --deep` - `/ck:plan "refactor auth middleware safely" --tdd` - `/ck:plan "implement real-time notifications + presence" --parallel` - `/ck:plan "redesign auth system" --two` - `/ck:plan "scaffold new microservice" --auto --no-tasks` - `/ck:plan "create shared architecture roadmap" --global` ## Scope Rules - **Project scope** is the default whenever the current working tree has project context. - **Global scope** is allowed when: - you explicitly ask for it with `--global`, or - there is no project context to anchor a local plan. - **No project context** means no `.git`, `package.json`, or `CLAUDE.md` was found in the ancestor chain. - Scan unfinished plans in the active scope before creating a new one. ## Workflow Process ``` Pre-Creation Check → Mode Detection → Research Phase → Codebase Analysis → Plan Documentation → Red Team Review → Validation → Hydrate Tasks → Boundary reminder ``` 1. **Pre-Creation Check** — scan existing plans to avoid duplication 2. **Mode Detection** — interpret flags or auto-select based on task complexity 3. **Research Phase** — spawn parallel researchers (hard/deep/parallel/two modes) 4. **Codebase Analysis** — scout relevant files, patterns, dependencies 5. **Plan Documentation** — write plan.md + phase files 6. **Red Team Review** — adversarial critique of the plan (hard/deep/parallel/two) 7. **Validation** — confirm plan is implementable 8. **Hydrate Tasks** — create session-scoped tasks from phase todo items 9. **Boundary reminder** — show the active plan path and optional implementation command without treating implementation as pre-approved Red-team and validation edits finish with a whole-plan consistency sweep. The agent re-reads `plan.md` and every `phase-*.md`, searches for stale terms or superseded assumptions, reconciles duplicated drafts/contracts, and reports unresolved contradictions before recommending cook. ## Plan Output Structure ``` plans/ └── YYMMDD-HHMM-/ ├── plan.md # Overview, phases, status ├── phase-01-setup.md # Setup / environment ├── phase-02-*.md # Implementation phases └── reports/ └── researcher-*.md # Research findings ``` Global scope uses the same directory shape under the configured global plans root instead of the current project. Each phase file contains: overview, requirements, architecture, file ownership, implementation steps, todo checklist, success criteria, risk assessment. Deep mode adds per-phase file inventories, test scenario matrices, and dependency maps. `--tdd` adds "Tests Before", "Refactor", and "Tests After" sections so the generated plan protects existing behavior during refactors. ## Task Hydration Tasks are ephemeral (session-scoped). Plan files are persistent. Hydration bridges them: 1. Read `[ ]` items from phase files 2. `TaskCreate` for each unchecked item 3. Work proceeds via `TaskUpdate` 4. On complete: mark `[x]` in plan file 5. Next session: re-hydrate remaining `[ ]` items Use `--no-tasks` when you want the plan only (e.g., for review before execution). If planning used `--tdd`, keep that flag on the cook handoff command: `/ck:cook /absolute/path/to/plan.md --tdd` ## Cross-Plan Dependencies Use `ck plan status` as the authoritative dependency/status view. - Bare references such as `260413-auth-system` stay in the current scope. - Cross-scope references use explicit prefixes: - `global:260413-auth-system` - `project:260413-dashboard` - Missing refs should warn and render as `not found`, not hard-fail the plan. ## Active Plan State Hooks track the current active plan. Downstream skills (cook, project-management, research) automatically write reports to the active plan's directory. Switching plans updates hook context. ## Quality Standards Plans follow YAGNI, KISS, DRY. Honest and brutal—no wishful thinking about complexity or timeline. Concise phase files beat exhaustive ones. Each phase must be independently executable. ## Subcommands | Subcommand | Purpose | |------------|---------| | `/ck:plan archive` | Write journal entry and archive completed plans | | `/ck:plan red-team` | Adversarial review — hostile critique of a plan to find weaknesses | | `/ck:plan validate` | Critical questions interview to verify plan is implementable | ## Related Skills - [Cook](/docs/engineer/skills/cook) — executes plans produced by this skill - [Bootstrap](/docs/engineer/skills/bootstrap) — end-to-end scaffold that delegates to plan + cook - [Agent Teams](/docs/engineer/skills/team) — parallel execution teams that consume phase files --- # ck:cook Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/cook # Cook Your complete feature implementation engine. Replaces the old `/code` command with smart workflow detection, research phases, and quality gates. ## What This Skill Does Cook orchestrates the entire implementation journey from idea to tested, reviewed code. It automatically detects the right workflow based on your request—whether you need fast prototyping, parallel execution, or full research-backed development. Think of it as your implementation conductor. Give it a task like "add user authentication" and it coordinates researchers, planners, developers, testers, and reviewers to deliver production-ready code. ## Core Capabilities - **Smart Intent Detection**: Analyzes your request to choose optimal workflow - **Research Phase**: Parallel researchers gather relevant technical knowledge - **Scout Phase**: Discover codebase structure and related files - **Planning**: Create detailed implementation plans with phases - **Implementation**: Execute with quality gates and review cycles - **TDD Refactors**: Add tests-first execution with `--tdd` when you need regression-safe changes - **Testing**: Comprehensive test coverage with 100% pass requirement - **Code Review**: Automated or human review based on complexity ## Workflow Modes | Mode | Research | Testing | Review Gates | Use When | |------|----------|---------|--------------|----------| | **interactive** (default) | ✓ | ✓ | User approval each step | Standard features | | **auto** | ✓ | ✓ | Auto if score≥9.5 | Trusted autonomous work | | **fast** | ✗ | ✓ | User approval each step | Quick prototypes | | **parallel** | Optional | ✓ | User approval each step | Multi-feature work | | **no-test** | ✓ | ✗ | User approval each step | Experimental code | | **code** | ✗ | ✓ | User approval each step | Execute existing plan | ## Usage ``` /ck:cook [--flag] ``` Optional flags: `--interactive`, `--fast`, `--parallel`, `--no-test`, `--auto` Composable flags: `--tdd` adds tests-first execution per phase without changing the detected mode. If no flag provided, uses interactive mode by default. ## Example Prompts - "/ck:cook add user authentication to the app" - "/ck:cook implement real-time notifications --fast" - "/ck:cook path/to/plan.md --auto" - "/ck:cook refactor auth middleware --tdd" - "/ck:cook add search, filters, and pagination --parallel" - "/ck:cook prototype new UI design --no-test" ## Workflow Overview ``` [Intent Detection] → [Research?] → [Review] → [Plan] → [Review] → [Implement] → [Review] → [Test?] → [Review] → [Finalize] ``` **Default (non-auto)**: Stops at [Review] gates for human approval before each major step. **Auto mode**: Skips human review gates, implements all phases continuously. **TDD mode**: Keeps the selected workflow mode, but splits each implementation phase into tests-before, implementation, and verification steps. ## Quality Gates **Always enforced (all modes):** - Testing: 100% pass required (unless no-test mode) - Code Review: User approval OR auto-approve (score≥9.5, 0 critical) - Finalize: project-manager AND docs-manager must complete ## What Makes This Different Cook doesn't just write code—it manages the entire software development lifecycle. It knows when to research, when to skip research, when to parallelize work, and when to enforce quality gates. The result: production-ready features, not prototypes. ## Related Skills - [Planning](/docs/engineer/skills/ck-plan) - Creates plans that cook executes - [Brainstorm](/docs/engineer/skills/brainstorm) - For architecture decisions before implementation - [Fix](/docs/engineer/skills/fix) - For debugging existing code - [Scout](/docs/engineer/skills/scout) - For codebase discovery --- # ck:fix Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/fix # Fix Complete bug fixing workflow with intelligent routing based on issue complexity. Automatically activates before fixing ANY bug, error, test failure, or code problem. ## What This Skill Does Fix orchestrates the entire debugging and repair process from investigation to verified solution. It assesses complexity, routes to the appropriate workflow, and ensures fixes don't break other parts of the codebase. Think of it as your bug triage system—analyzing the problem, selecting the right strategy (quick, standard, or deep), and coordinating parallel verification to prevent regressions. ## Core Capabilities - Complexity assessment and intelligent workflow routing - Parallel root cause hypothesis exploration - Simple/Moderate/Complex/Parallel issue handling - Autonomous or human-in-the-loop review modes - Comprehensive verification to prevent new issues - Automatic docs updates and commit management ## Workflow Modes | Mode | Recommend When | Behavior | |------|----------------|----------| | **Autonomous** (default) | Simple/moderate issues | Auto-approve if score ≥9.5 & 0 critical | | **Human-in-the-loop Review** | Critical/production code | Pause for approval at each step | | **Quick** | Type errors, lint, trivial bugs | Fast debug → fix → review cycle | ## The Process ### Step 1: Mode Selection First action (unless "auto" in request): Ask user to choose workflow mode ### Step 2: Debug - Activate `debug` skill - Guess all possible root causes - Explores the codebase in parallel to verify each hypothesis - Create report with findings ### Step 3: Complexity Assessment & Fix Classify before routing: | Level | Indicators | Workflow | |-------|------------|----------| | **Simple** | Single file, clear error, type/lint | Quick workflow | | **Moderate** | Multi-file, root cause unclear | Standard workflow | | **Complex** | System-wide, architecture impact | Deep workflow | | **Parallel** | 2+ independent issues | Parallel developers | ### Step 4: Fix Verification - Read and analyze all changes - Scans related code to ensure fixes don't cause regressions - Ensure fixes don't break other parts - Prevent future issues with comprehensive validation ### Step 5: Finalize - Report summary with confidence level, changes, related files - Ask to commit via `git-manager` and update docs via `docs-manager` ## Usage ``` /ck:fix [--auto|--review|--quick|--parallel] ``` | Flag | Behavior | |------|----------| | `--auto` | Autonomous mode (default) - auto-approve if score >= 9.5 | | `--review` | Human-in-the-loop - pause for approval at each step | | `--quick` | Fast cycle for trivial bugs (type errors, lint) | | `--parallel` | Route to parallel `fullstack-developer` agents per issue | ### --parallel Mode (v2.10.0+) When you have multiple independent issues, `--parallel` spawns separate agents to fix each one simultaneously. Useful for: - Batch fixing lint errors across files - Addressing unrelated test failures - Fixing multiple independent bugs in one session ```bash # Fix multiple issues in parallel /ck:fix --parallel # Example: 3 unrelated type errors → 3 parallel agents ``` Activate automatically when mentioning bugs, errors, test failures, CI/CD issues, type errors, lint, log errors, UI issues, or code problems. ## Example Prompts - "Tests are failing in the auth module" - "Fix the type error in UserProfile component" - "Debug why the API returns 500 on login" - "The build is broken in CI" - "Users report the app crashes on logout" ## Output Format ``` ✓ Step 0: [Mode] selected - [Complexity] detected ✓ Step 1: Root cause identified - [summary] ✓ Step 2: Fix implemented - [N] files changed ✓ Step 3: Tests [X/X passed] ✓ Step 4: Review [score]/10 - [status] ✓ Step 5: Complete - [action taken] ``` ## What Makes This Different Fix doesn't just patch symptoms—it finds root causes, verifies fixes across the codebase, and prevents similar issues in the future through defense-in-depth validation. The result: reliable fixes, not band-aids. ## What's New (v2.14.0) - Updated internal references to match renamed skill directories (`ck-debug`, `ck-plan`) - Parallel exploration patterns refined — each hypothesis branch runs independent codebase analysis before convergence - Documentation links updated to reflect `ck:` namespace prefix ## Related Skills - [Debug](/docs/engineer/skills/ck-debug) - Systematic debugging framework - [Cook](/docs/engineer/skills/cook) - For implementing new features --- # ck:git Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/git # Git Execute git workflows with conventional commit format, intelligent commit splitting, and security scanning for secrets. ## What This Skill Does The Git skill handles all git operations with conventional commit standards, automatic commit splitting by type/scope, and security scanning for accidentally committed secrets. Think of it as your git guardian—ensuring clean commit history, preventing security leaks, and handling complex workflows like PRs and merges with proper GitHub CLI integration. ## Core Capabilities - Stage files and create conventional commits - Auto-split commits by type/scope for clean history - Security scanning for API keys, tokens, passwords - Push with error handling and conflict resolution - Create Pull Requests with remote diff analysis - Merge branches with safety checks - GitHub CLI integration for issues and PRs ## Arguments - `cm`: Stage files & create commits - `cp`: Stage files, create commits, and push - `pr`: Create Pull Request [to-branch] [from-branch] - `merge`: Merge [to-branch] [from-branch] ## Core Workflow ### 1. Stage + Analyze ```bash git add -A && git diff --cached --stat && git diff --cached --name-only ``` ### 2. Security Check Scan for secrets before commit: ```bash git diff --cached | grep -iE "(api[_-]?key|token|password|secret|credential)" ``` **If secrets found**: STOP, warn user, suggest `.gitignore`. ### 3. Split Decision **Split commits if:** - Different types mixed (feat + fix, code + docs) - Multiple scopes (auth + payments) - Config/deps + code mixed - FILES > 10 unrelated **Single commit if:** - Same type/scope, FILES ≤ 3, LINES ≤ 50 ### 4. Commit ```bash git commit -m "type(scope): description" ``` ## Usage Activate by typing `/ck:git` followed by arguments or mentioning git operations. ## Example Prompts - "/ck:git cm" - Create commits - "/ck:git cp" - Create commits and push - "/ck:git pr main dev" - Create PR from dev to main - "/ck:git merge dev feature-branch" - Merge feature into dev ## Conventional Commit Format ``` type(scope): description [optional body] [optional footer] ``` **Types**: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`, `build`, `style` **Note**: Only use `feat`, `fix`, or `perf` for `.claude` directory files (not `docs`). ## Output Format ``` ✓ staged: N files (+X/-Y lines) ✓ security: passed ✓ commit: HASH type(scope): description ✓ pushed: yes/no ``` ## Error Handling | Error | Action | |-------|--------| | Secrets detected | Block commit, show files | | No changes | Exit cleanly | | Push rejected | Suggest `git pull --rebase` | | Merge conflicts | Suggest manual resolution | ## What Makes This Different Git skill doesn't just execute commands—it enforces best practices, prevents security leaks, and maintains clean commit history automatically. The intelligent commit splitting ensures your git log tells a clear story. ## Related Skills - [Cook](/docs/engineer/skills/cook) - For implementing features that need commits - [Fix](/docs/engineer/skills/fix) - For bug fixes that need commits --- # ck:scout Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/scout # Scout Fast, token-efficient codebase scouting using parallel agents to find files needed for tasks. ## What This Skill Does The Scout skill rapidly explores your codebase using parallel agents to locate relevant files, understand structure, and gather context. It's like having a team of developers simultaneously searching different parts of your codebase and reporting back with findings. Think of it as your reconnaissance mission before feature work—quickly mapping the terrain so you know exactly which files matter for your task. ## When to Use - Beginning work on feature spanning multiple directories - User mentions needing to "find", "locate", or "search for" files - Starting debugging session requiring file relationships understanding - User asks about project structure or where functionality lives - Before changes that might affect multiple codebase parts ## Core Capabilities - Parallel agent-based file discovery - Token-efficient codebase exploration - Built-in parallel scouting or external tools (Gemini/OpenCode CLI) - Adaptive scaling based on codebase size - Concise reporting with unresolved questions ## Arguments - **Default**: Scout using built-in parallel exploration - **ext**: Scout using external Gemini/OpenCode CLI tools in parallel ## Quick Start 1. Analyze user prompt to identify search targets 2. Use wide range of Grep/Glob patterns to find files and estimate scale 3. Spawn parallel agents with divided directories 4. Collect results into concise report ## Workflow ### 1. Analyze Task - Parse user prompt for search targets - Identify key directories, patterns, file types, lines of code - Determine optimal scale for parallel exploration ### 2. Divide and Conquer - Split codebase into logical segments per agent - Assign each agent specific directories or patterns - Ensure no overlap, maximize coverage ### 3. Spawn Parallel Agents - Each exploration thread gets specific directories/files to analyze - Each has <200K token context window - Agent count depends on system resources and file scale - Each returns detailed summary to main agent ### 4. Collect Results - 3-minute timeout per agent (skip non-responders) - Aggregate findings into single report - List unresolved questions at end ## Usage Activate by mentioning file discovery, codebase exploration, or structure understanding needs. ## Example Prompts - "Find all authentication-related files in the codebase" - "Where does the user profile feature live?" - "Scout the API layer to understand the payment flow" - "Locate all files that interact with the database" - "Which components use the theme system?" ## Report Format ```markdown # Scout Report ## Relevant Files - `path/to/file.ts` - Brief description - ... ## Unresolved Questions - Any gaps in findings ``` ## What Makes This Different Scout doesn't just grep—it intelligently divides exploration work across parallel agents, each with full context about their assigned territory. The result: comprehensive codebase understanding in minutes, not hours. ## Related Skills - [Cook](/docs/engineer/skills/cook) - Uses Scout before implementation - [Fix](/docs/engineer/skills/fix) - Uses Scout to understand bug context - [GKG](/docs/engineer/skills/gkg) - Semantic code analysis (alternative approach) --- # ck:ask Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/ask # Ask Answer technical and architectural questions about your codebase. This skill provides focused, researched answers rather than superficial responses. ## Usage ``` /ck:ask [your question] ``` ## Examples ```bash /ck:ask how is authentication currently implemented? /ck:ask what's the database schema for orders? /ck:ask explain the middleware chain in this project ``` ## What It Does - Reads relevant code files to find answers - Provides context-aware responses based on your actual codebase - References specific files and line numbers - Explains architecture decisions and patterns found in your code --- # ck:docs Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/docs # Docs Manage project documentation with AI-powered analysis. Initialize docs for new projects, update after changes, or generate summaries. ## Usage ``` /ck:docs init # Initialize documentation for a project /ck:docs update # Update docs after code changes /ck:docs summarize # Generate a documentation summary ``` ## Subcommands | Subcommand | Description | |-----------|-------------| | `init` | Analyze codebase and create initial documentation suite | | `update` | Scan for changes and update existing docs | | `summarize` | Generate a concise project summary | ## What It Creates ``` docs/ ├── project-overview-pdr.md ├── codebase-summary.md ├── system-architecture.md ├── code-standards.md └── project-roadmap.md ``` --- # ck:test Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/test # Test Comprehensive testing framework for code and UI. Runs the full test stack, analyzes failures, measures coverage, and produces QA reports. ## Core Principle **NEVER IGNORE FAILING TESTS.** No workarounds. No mocks to pass CI. No `--passWithNoTests`. Fix the root cause or document a legitimate skip with justification. ## What This Skill Does Test orchestrates the complete quality verification loop: type checking, test execution, failure analysis, coverage measurement, UI validation, and report generation. Works with any test runner and integrates with the debug skill for failures requiring investigation. ## Workflows ### Code Testing Supports all major test runners: | Language | Runners | |----------|---------| | JavaScript/TypeScript | Jest, Vitest, Mocha | | Python | pytest, unittest | | Go | go test | | Rust | cargo test | | Dart/Flutter | flutter test | ### UI Testing Delegates to the `chrome-devtools` skill for: - Visual regression - Interaction testing - Accessibility checks - Performance audits ### Report Generation Produces structured QA reports at `{active-plan}/reports/tester-YYMMDD.md` covering: pass/fail summary, coverage metrics, failing test details, and recommendations. ## Working Process ``` Identify Scope → Typecheck First → Execute Suites → Analyze Failures → Coverage Report → UI Tests (if needed) → QA Report ``` 1. **Identify Scope** — determine which suites are relevant (unit/integration/e2e/UI) 2. **Typecheck First** — run `tsc --noEmit` or equivalent before tests 3. **Execute Suites** — run test runner(s) for the project 4. **Analyze Failures** — for each failure: read error, trace root cause, recommend fix 5. **Coverage Report** — Istanbul/c8/pytest-cov/go cover output 6. **UI Tests** — browser-based validation via chrome-devtools skill 7. **QA Report** — write structured report with actionable findings ## Tools Integration | Tool | Purpose | |------|---------| | Test runners | Execute suites (auto-detected from package.json / config files) | | Istanbul/c8 | JS/TS coverage | | pytest-cov | Python coverage | | go cover | Go coverage | | chrome-devtools skill | Browser/UI testing | | ai-multimodal skill | Screenshot analysis for UI failures | | debug skill | Root cause analysis for complex failures | ## Quality Standards - **Critical paths**: 100% test coverage required - **Happy + error paths**: both must be covered - **Test isolation**: no shared state between tests - **Deterministic**: tests must produce same result every run - **Data cleanup**: tests clean up any created data - **No flaky tests**: fix or remove, never retry-loop ## Diff-Aware Testing (v2.14.0+) The tester agent integrates git diff analysis to run only tests affected by recent changes. Five mapping strategies determine which test files to include: 1. Direct file → test file mapping (e.g., `src/auth.ts` → `src/auth.test.ts`) 2. Import graph analysis (files that import changed modules) 3. Test fixture dependencies 4. Integration test scope detection 5. Full suite fallback (when scope cannot be determined) This reduces test execution time during iteration while preserving full-suite runs for pre-push verification. ## Team Mode In agent team sessions, the tester teammate: - Owns all test files exclusively - Reads implementation files but never edits them - Reports coverage and failures back to lead ## Example Prompts - "Run tests for the auth module and generate a coverage report" - "Run the full test suite and fix any failures" - "Run UI tests on the dashboard page and check for regressions" - "Run integration tests and analyze why the payment tests are failing" ## Related Skills - [Debug](/docs/engineer/skills/ck-debug) — activated for failures requiring root cause analysis - [Cook](/docs/engineer/skills/cook) — cook's quality gate requires 100% test pass - [Chrome DevTools](/docs/engineer/skills/chrome-devtools) — UI and browser testing --- # ck:watzup Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/watzup # Watzup Review recent changes and wrap up your current work session. Generates a summary of what was accomplished and what's next. ## Usage ``` /ck:watzup ``` ## What It Does - Reviews git log for recent commits - Summarizes changes made in the current session - Lists modified files and their purposes - Suggests next steps --- # ck:journal Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/journal # Journal Write development journal entries to document technical decisions, challenges, and progress. Useful for maintaining a record of your development journey. ## Usage ``` /ck:journal [entry topic or description] ``` ## Examples ```bash /ck:journal debugging the auth token refresh loop /ck:journal decided to switch from REST to GraphQL /ck:journal completed phase 2 of the migration ``` --- # ck:cti-expert Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/cti-expert :::caution[Deprecated — not installed] `cti-expert` has been archived from AgentKit and is **no longer included** in new ClaudeKit installations. Commands on this page will not work in current installations. Use `/ck:brainstorm` for threat modeling discussions or `/ck:security` for security audits. ::: :::note[Historical reference only] The content below describes the original `cti-expert` skill. None of these commands are available in current installations. This page is preserved for reference only. ::: # CTI Expert Cyber threat intelligence and open-source intelligence (OSINT) investigation skill. Turns Claude into a trained CTI/OSINT analyst. Generates precision search queries, interprets public data, builds case timelines, and delivers structured intelligence products — no API keys required. Think of it as having a professional threat intelligence analyst on your team who speaks multiple languages, knows every advanced search technique, and can piece together evidence across hundreds of public data sources. ## What This Skill Does CTI Expert conducts multi-source investigations into digital footprints, organizations, domains, credentials, and security threats. It handles everything from username enumeration across 3000+ platforms to building threat models from scattered clues. The skill runs guided case workflows (Acquire → Enrich → Assess → Deliver) that keep investigations organized and verifiable. Every finding is sourced, timestamped, and confidence-scored. You get formal intelligence reports suitable for legal proceedings, executive briefs for decision-makers, or technical threat assessments. ## Quick Start ```bash # Full autonomous case — investigates everything applicable /case target.com # Guided workflow for beginners /flow person # Summary of findings so far /brief # Generate formal report /report ``` Append `--yolo` to any command to skip confirmations and let the analyst decide autonomously. ## Investigation Phases Every case follows the **AEAD** lifecycle: | Phase | What Happens | Examples | |-------|------------|----------| | **Acquire** | Collect raw data | sweep domains, enumerate usernames, check breaches | | **Enrich** | Expand and connect leads | branch identifiers, build timelines, cross-reference | | **Assess** | Score and verify findings | expose score, threat models, validation checks | | **Deliver** | Package output | formal reports, executive briefs, IOC exports | Run `/progress` at any point to see which phase you're in and what's pending. ## Core Capabilities ### Social Media & Username Investigation ```bash # Find a username across 3000+ platforms /username johndoe # Enumerate accounts, timeline, connected accounts /sweep @johndoe ``` ### Breach & Credential Hunting ```bash # Deep breach lookup with context /breach-deep user@example.com # Exposed credentials in repos and paste sites /secrets github.com/org ``` ### Domain & IP Intelligence ```bash # Full domain reconnaissance /sweep example.com # Technology fingerprint: CMS, analytics, CDN, servers /techstack example.com # DNS history and certificate timeline /dns-history example.com /cert-history example.com ``` ### Threat & Vulnerability Assessment ```bash # Threat intelligence on domain/IP/URL/hash /threat-check 185.1.1.1 # Phishing/malware/scam site detection /scam-check susp-site.xyz # CVE and vulnerability lookup /vuln-check CVE-2024-1234 # Check if organization is ransomware victim /ransomware-check "Acme Corp" ``` ### Cloud & Microsoft 365 Reconnaissance ```bash # M365/Azure tenant recon — tenant ID, federation, MDI, SharePoint /msftrecon example.com # Google document metadata and ownership /gdoc https://docs.google.com/document/d/... ``` ### Geographic & Transport Intelligence ```bash # WiFi SSID geolocation /wifi "HomeNetwork" # Exact AP lookup by MAC address /wifi --bssid AA:BB:CC:DD:EE:FF ``` ### Evidence & Reporting ```bash # View archived snapshots /snapshots example.com # Full evidence trail for a subject /show-trail JohnDoe # ASCII relationship diagram /graph ``` ## Case Management Save and resume cases: ```bash # Persist case state /workspace save mycase # Resume a saved investigation /workspace open mycase # Compare two cases /workspace diff case1 case2 # List all saved cases /workspace list ``` ## Report Formats The skill exports intelligence in multiple formats: | Format | Best For | |--------|----------| | `/report` | Formal structured intelligence report | | `/report brief` | Single-page executive summary | | `/report json` | Raw data for integration | | `/report csv` | Spreadsheet analysis | | `/report legal` | Evidence formatted for legal proceedings | | `/report journalist` | Source-citation-heavy format | | `/report ioc` | IOCs as STIX 2.1 or flat list | ## Subject Types CTI Expert tracks entities with rich relationships: | Type | Symbol | Examples | |------|--------|----------| | Person | 👤 | Full name, alias | | Username | @ | Social handle | | Email | 📧 | Address, domain | | Domain | 🌐 | Site, subdomain | | IP Address | 🖥 | IPv4, IPv6 | | Organization | 🏢 | Company, group | | Phone | 📱 | E.164 format | | Crypto Wallet | 💰 | Bitcoin, Ethereum address | | Device | 🖥️ | Server, workstation | | Image | 🖼️ | Screenshot, photograph | ## Command Reference **Acquire phase** — `/case`, `/sweep`, `/username`, `/phone`, `/email-deep`, `/subdomain`, `/breach-deep`, `/traffic`, `/techstack`, `/threat-check`, `/scam-check`, `/vuln-check`, `/msftrecon`, `/dork-sweep`, `/docleak`, `/cert-history` **Enrich phase** — `/branch`, `/timeline`, `/crossref`, `/link-subjects`, `/show-connections`, `/watch`, `/record-finding`, `/graph`, `/pathfind` **Assess phase** — `/exposure`, `/threat-model`, `/validate`, `/coverage`, `/verify-finding`, `/subject`, `/lookup`, `/modify`, `/blind-spots`, `/drift` **Deliver phase** — `/report`, `/brief`, `/report json`, `/report csv`, `/report legal`, `/report ioc`, `/render entities`, `/render timeline`, `/render risk`, `/workspace save/open/list` **Navigation** — `/flow`, `/progress`, `/opsec`, `/onboard`, `/quality`, `/novice`, `/terms` See `SKILL.md` in the skill directory for the complete command reference and examples. ## Best Practices **Collection Method** — The skill uses `agent-browser` when available for JavaScript-heavy sites and infinite-scroll discovery. Falls back to web search, web fetch, and direct URL retrieval when needed. Tool limitations are logged as gaps, never case blockers. **Search Operators** — CTI Expert generates 12–15 advanced search queries automatically. Each targets a specific platform or data source to maximize signal and minimize noise. **Confidence Scoring** — All findings are tagged by confidence level and source. The skill will flag ambiguous or high-uncertainty findings for human verification. **OPSEC Checklist** — Run `/opsec` during sensitive investigations to review operational security practices. ## Use Cases - **Incident response** — Rapid threat assessment and attribution - **Due diligence** — Pre-partnership investigation of companies or individuals - **Legal discovery** — Evidence collection for litigation or compliance - **Security research** — Vulnerability disclosure and responsible reporting - **Fraud investigation** — Tracking digital footprints of bad actors - **Brand protection** — Monitoring for impersonation and credential abuse - **Threat hunting** — Proactive search for indicators of compromise ## Prerequisites - No API keys or paid subscriptions required - Access to Claude with web search and web fetch capabilities - For `agent-browser` features: JavaScript-capable environment (Playwright MCP) ## Related Skills - [Scout](/docs/engineer/skills/scout) — Quick file search and codebase exploration - [Repomix](/docs/engineer/skills/repomix) — Full codebase context dump - [Security](/docs/engineer/skills/ck-security) — Automated security auditing --- # ck:graphify Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/graphify # Graphify Turn any folder of code, documentation, papers, or images into a queryable knowledge graph. Uses tree-sitter AST for code (20+ languages), Whisper for audio/video, and LLM agents for documents. Think of it as building a semantic index of your codebase—one you can search by concept instead of grepping for filenames. ## What This Skill Does Graphify builds interactive knowledge graphs that reveal architecture, dependencies, and cross-file relationships. Instead of jumping between files, ask the graph "what calls this function?" or "which modules depend on X?" and get visual connection maps. The skill produces three artifacts: an interactive HTML visualization, a structured markdown report highlighting key insights, and a persistent JSON graph for programmatic queries. ## Quick Start ```bash # Build knowledge graph from current directory graphify . # Build from specific path graphify /path/to/project # Watch mode — auto-rebuild on file changes graphify . --watch # Expose graph as MCP server for Claude to query python -m graphify.serve graphify-out/graph.json ``` ## When to Use Graphify **Before planning** — Build the graph first to understand architecture, then plan with visual context. **Architecture analysis** — Find god nodes (most-connected concepts), surprising dependencies, and architectural anti-patterns. **Codebase navigation** — Prefer structure-based navigation over grepping when entering unfamiliar projects. **Token-efficient context** — 71.5x fewer tokens than raw files — crucial for large codebases. **Cross-domain understanding** — Combine code AST + documents + papers + images for complete context. ## Output Artifacts | File | Purpose | |------|---------| | `graphify-out/graph.html` | Interactive visualization with search, filtering, community detection | | `graphify-out/GRAPH_REPORT.md` | God nodes, surprising connections, architecture insights, suggested questions | | `graphify-out/graph.json` | Persistent graph for queries across sessions | | `graphify-out/cache/` | SHA256-based incremental updates (only reprocesses changed files) | ## Interactive Visualization Open `graphify-out/graph.html` in your browser to: - **Search for concepts** — Type a class name, function, or topic - **Filter by community** — See related concepts grouped automatically - **Explore neighbors** — Click a node to see everything connected - **Query shortest path** — Find the connection route between two concepts ## Supported Input Types ### Code Files (Tree-Sitter AST) 20+ languages supported with deterministic parsing: Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia For each language, the graph extracts: - Function and class definitions - Imports and dependencies - Call chains and inheritance hierarchies - Variable assignments and mutations - Type annotations (where available) **No API calls for code** — Tree-sitter runs locally. File contents never leave your machine. ### Audio & Video (Whisper) Transcribe podcasts, talks, and videos: ```bash # Builds knowledge graph from audio transcript + timestamps graphify ./videos/*.mp4 --watch ``` **Local transcription** — Uses Whisper on-device. No files sent to external APIs. ### Documents & Papers (LLM-Powered) PDFs, Markdown, Office documents — LLM agents extract key concepts, relationships, and summaries: ```bash # Extract from all PDFs and markdown graphify ./docs ./papers/*.pdf ``` **Semantic extraction** — Processes via your configured model provider (Claude/OpenAI). ### Images (Vision Models) Screenshots, diagrams, photographs — extract text and describe visual elements: ```bash graphify ./screenshots/*.png ``` ## Graph Report Insights The auto-generated `GRAPH_REPORT.md` includes: - **God nodes** — Most-connected concepts in the graph (likely core abstractions) - **Surprising connections** — Unexpected dependencies or architectural patterns - **Community detection** — Automatically grouped concepts and modules - **Suggested questions** — Intelligent queries to explore based on graph structure ## Relationship Confidence Tags Every relationship is tagged by how it was discovered: | Tag | Meaning | Reliability | |-----|---------|------------| | `EXTRACTED` | Directly from AST (imports, calls, inheritance) | 100% | | `INFERRED` | LLM-derived from semantic analysis | 85–95% | | `AMBIGUOUS` | Uncertain — requires human verification | <85% | ## MCP Server Mode Expose the graph as an MCP server so Claude can query it directly: ```bash # Start server from graph file python -m graphify.serve graphify-out/graph.json ``` ### Available MCP Tools | Tool | Query Type | |------|-----------| | `query_graph` | Search for concepts by name or type | | `get_node` | Details of a specific node (definition, references) | | `get_neighbors` | Find all connected concepts | | `shortest_path` | Find minimum hops between two concepts | ### Claude Code Integration Add to `.claude/.mcp.json`: ```json { "mcpServers": { "graphify": { "command": "python", "args": ["-m", "graphify.serve", "graphify-out/graph.json"] } } } ``` Then query within Claude Code: ``` Use the graphify MCP tool to find how AuthService connects to UserRepository ``` ## Installation ClaudeKit already ships `ck:graphify` as a bundled skill. Do not run `graphify install` for ClaudeKit setup: upstream uses that command to install its standalone Claude skill at `~/.claude/skills/graphify/SKILL.md`. ```bash # Core install (code parsing only) pip install graphifyy # With MCP server support pip install 'graphifyy[mcp]' # Full install (MCP + PDF + video + office + community detection) pip install 'graphifyy[all]' ``` **Note:** Package name is `graphifyy` (double-y) on PyPI. **Requirements:** Python 3.10+ ## Architecture: Three-Pass Processing ### Pass 1: AST Extraction (Local, Deterministic) Tree-sitter parses code in 20+ languages. Extraction is: - **Deterministic** — same input → same output every time - **Local** — no API calls, file contents stay private - **Fast** — parallel processing across files ### Pass 2: Audio/Video (Local via Whisper) Transcription runs on-device: - **Private** — audio never uploaded - **Timestamped** — preserves temporal markers - **Fallback-safe** — missing audio → gap in graph, not a blocker ### Pass 3: Semantic Extraction (API-Based) LLM agents process documents, papers, and images: - **Parallel** — multiple documents processed simultaneously - **Configurable** — choose model, context window, temperature - **Privacy-aware** — send only what's necessary ## Incremental Updates Graph rebuilds are optimized: - **SHA256 file hashing** — unchanged files skipped - **Caching** — previous results reused - **Partial updates** — only changed files reprocessed Perfect for watch mode during active development. ## Privacy & Data Handling | Input Type | Processing | Privacy | |-----------|-----------|---------| | Code files | Tree-sitter (local) | Private | | Audio/video | Whisper (local) | Private | | Documents | LLM API (configurable) | Depends on provider | | Images | Vision model (configurable) | Depends on provider | **No data leaves your machine unless you explicitly send it via LLM API calls.** ## Workflow Integration ### Before Planning ```bash graphify /path/to/target # Read GRAPH_REPORT.md for architecture insights /ck:plan "Implement feature X" # now informed by graph ``` ### With Scout Use graphify for high-level structure, scout for specific file details: ```bash graphify . # build architecture graph /ck:scout "auth module" # find specific files ``` ### Active Development ```bash graphify . --watch # rebuild graph as you work # Use graph.html as live architecture reference ``` ## Limitations - **First build** on large codebases can be slow (AST parsing + LLM calls) - **Semantic extraction quality** depends on the underlying model - **Neo4j integration** requires separate setup (`pip install 'graphifyy[neo4j]'`) - **Leiden community detection** requires `pip install 'graphifyy[leiden]'` For very large codebases (1000+ files), consider: - Scoping to a subdirectory (`graphify ./src/core`) - Running in watch mode to incrementally build the graph - Using the cache (`graphify-out/cache/`) for faster rebuilds ## Related Skills - [Scout](/docs/engineer/skills/scout) — Quick file search for specific capabilities - [Repomix](/docs/engineer/skills/repomix) — Full context dump for raw codebase data - [GKG](/docs/engineer/skills/gkg) — Semantic symbol navigation with go-to-definition - [Plan](/docs/engineer/skills/ck-plan) — Plan implementation after understanding architecture ## Best Practices **Build early** — Run graphify before planning complex features. Architecture understanding saves time. **Use watch mode** — Enable `--watch` during exploratory coding to keep the graph fresh. **Combine with scout** — Use graphify for overview, scout for drill-down into specific files. **Export for sharing** — Copy `graphify-out/graph.html` and `GRAPH_REPORT.md` to share architecture with teammates. **Verify ambiguous edges** — Relationships tagged `AMBIGUOUS` need human verification. Don't assume them without checking the code. ## Examples ### Understanding a Django Project ```bash graphify . --watch # Opens graph.html → see models, views, middleware connections # GRAPH_REPORT.md → lists god nodes (core models, middleware) ``` ### Mapping a Microservices Architecture ```bash graphify ./services # Graph shows service boundaries and external dependencies # Shortest path queries reveal call chains across services ``` ### Learning a Codebase Before Contributing ```bash graphify /external/project # Read GRAPH_REPORT.md for architecture # Query graph for "where are authentication checks?" # Browse visualizations to plan contribution ``` --- # ck:frontend-design Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/frontend-design # Frontend Design Tired of generic-looking interfaces that scream "AI made this"? This skill helps you create frontend designs that feel genuinely crafted, memorable, and intentional. ## What This Skill Does Frontend Design guides you in creating distinctive, production-grade interfaces that avoid cookie-cutter aesthetics. Whether you're building from scratch or replicating a design from screenshots, this skill ensures you create something that stands out. The skill handles two primary workflows: extracting design guidelines from screenshots and implementing them with precision, or creating original designs with bold aesthetic direction. It emphasizes creative typography choices, cohesive color systems, intentional motion design, and spatial composition that breaks expectations. Think of it as your creative director and implementation guide combined. It won't let you default to Inter font on a white background with purple gradients. Instead, you'll learn to make bold choices that fit your specific context, whether that's brutalist minimalism, maximalist chaos, or refined elegance. ## Prerequisites Before using this skill effectively, you should have: - Basic understanding of HTML, CSS, and JavaScript - Familiarity with React (for component-based workflows) - Access to the `ai-multimodal` skill (for design extraction and asset generation) - A code editor and browser for testing The skill integrates with the AI Multimodal skill for analyzing screenshots and generating visual assets that match your design direction. ## Two Primary Workflows ### Workflow 1: Implementing from Screenshots When someone hands you a screenshot, image, or design reference to replicate: **Step 1: Extract Design Guidelines** Never jump straight to code. Analyze the screenshot first using the `ai-multimodal` skill: ```bash # Analyze the design with Gemini python scripts/gemini_batch_process.py --files design-screenshot.png --task analyze --prompt "Extract design system: all colors as hex codes, typography (font families, sizes, weights, line heights), spacing scale, layout patterns, visual hierarchy, component styles" ``` Document your findings in `docs/design-guidelines/extracted-design.md` with sections for: - Color palette (exact hex codes) - Typography system (fonts, sizes, weights, line heights) - Spacing scale (margins, padding patterns) - Layout structure (grid, flexbox, positioning) - Component patterns (buttons, cards, forms) - Visual hierarchy and mood **Step 2: Implement with Precision** Now write code that faithfully reproduces the extracted design: ```css /* Use exact colors from extraction */ :root { --color-primary: #2D3748; --color-accent: #ED8936; --color-background: #F7FAFC; } /* Match typography specifications */ .heading { font-family: 'Playfair Display', serif; font-size: 48px; font-weight: 700; line-height: 1.2; } .body-text { font-family: 'Source Sans Pro', sans-serif; font-size: 16px; line-height: 1.6; } ``` **Step 3: Verify Quality** Compare your implementation to the original screenshot: ```bash # Take a screenshot of your implementation # Use chrome-devtools skill or browser dev tools # Compare with ai-multimodal python scripts/gemini_batch_process.py --files original.png implementation.png --task analyze --prompt "Compare these two designs. Check color accuracy, spacing consistency, typography matching, and overall fidelity" ``` ### Workflow 2: Building from Scratch When creating original designs without a reference: **Step 1: Design Thinking** Before writing any code, answer these questions: - **Purpose**: What problem does this interface solve? Who uses it? - **Tone**: What aesthetic direction fits this purpose? (See "Choosing Your Aesthetic" below) - **Constraints**: Framework requirements? Performance targets? Accessibility needs? - **Differentiation**: What will make this unforgettable? **Step 2: Choose a Bold Direction** Pick an extreme aesthetic and commit to it. Some examples: - **Brutally Minimal**: Monospace font, stark black/white, generous whitespace, zero decoration - **Editorial Magazine**: Large display fonts, multi-column layouts, dramatic imagery - **Retro-Futuristic**: Neon gradients, geometric shapes, synthwave colors - **Organic Natural**: Earth tones, flowing shapes, soft shadows - **Industrial Utilitarian**: Exposed grids, monospace, technical aesthetic **Step 3: Execute with Precision** Implement your chosen direction with meticulous attention to detail. ## Choosing Your Aesthetic The skill provides detailed guidance on creating distinctive designs across five key areas: ### Typography: Break the Default Stop using Inter, Roboto, Arial, and system fonts. Choose fonts with character: - Pair a distinctive display font with a refined body font - Examples: Playfair Display + Source Sans Pro, Syne + IBM Plex Sans, Fraunces + Work Sans - Use unexpected font choices that match your context - Consider variable fonts for dynamic weight and width control ### Color & Theme: Commit Fully Use CSS variables for consistency, but choose boldly: ```css :root { /* Dominant colors with sharp accents */ --color-primary: #1A202C; --color-accent: #F56565; --color-neutral: #E2E8F0; /* Not timid, evenly-distributed palettes */ } ``` Dominant colors with sharp accents outperform timid, evenly-distributed palettes. ### Motion: High-Impact Moments Focus on one well-orchestrated page load with staggered reveals rather than scattered micro-interactions: ```css /* Staggered entrance animation */ .hero-title { animation: fadeInUp 0.6s ease-out; } .hero-subtitle { animation: fadeInUp 0.6s ease-out 0.2s; animation-fill-mode: backwards; } .hero-cta { animation: fadeInUp 0.6s ease-out 0.4s; animation-fill-mode: backwards; } @keyframes fadeInUp { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } } ``` For React components, use the Motion library. For advanced JavaScript animations, the skill includes `anime.js` reference documentation. ### Spatial Composition: Break the Grid Create unexpected layouts: - Asymmetric arrangements - Overlapping elements - Diagonal flow instead of strict vertical/horizontal - Generous negative space OR controlled density (pick one) ### Backgrounds & Visual Details Never default to solid colors. Create atmosphere: - Gradient meshes with multiple color stops - Noise textures for subtle grain - Geometric patterns (SVG backgrounds) - Layered transparencies for depth - Dramatic shadows (not just `box-shadow: 0 2px 4px rgba(0,0,0,0.1)`) ## Working with Visual Assets The skill integrates with `ai-multimodal` for generating and analyzing visual assets: ### Generating Assets When you need hero images, backgrounds, or decorative elements: ```bash # Generate a background texture python scripts/gemini_batch_process.py --task generate --prompt "Abstract geometric pattern, teal and navy, minimal style for website background" # Generate hero image python scripts/gemini_batch_process.py --task generate --prompt "Isometric illustration of a modern workspace, soft shadows, pastel color palette" --model imagen-4.0-ultra-generate-001 ``` Ensure generated assets align with your chosen aesthetic direction. ### Analyzing Design References When you find inspiration but need to understand how it works: ```bash # Extract the design system python scripts/gemini_batch_process.py --files inspiration.png --task analyze --prompt "Analyze this design: identify the aesthetic direction, extract color palette, describe typography choices, explain spatial composition, note distinctive elements" ``` ## Real-World Examples ### Replicate a Landing Page from Screenshot You received a screenshot of a competitor's landing page to replicate: ```bash # Extract design system python scripts/gemini_batch_process.py --files competitor.png --task analyze --prompt "Full design system extraction: colors (hex), fonts (names, sizes, weights), spacing (margins, padding), layout structure, component styles" # Document findings in docs/design-guidelines/extracted-design.md # Implement components following exact specifications # Verify with side-by-side comparison ``` ### Create an Original Portfolio Site You're building a portfolio from scratch: **Design Thinking**: Personal brand, creative professional, needs to stand out. **Aesthetic Direction**: Editorial magazine style with large typography, multi-column layouts, dramatic black and white photography. **Implementation**: ```css :root { --color-bg: #FAFAF9; --color-text: #1C1917; --color-accent: #DC2626; --font-display: 'Cormorant Garamond', serif; --font-body: 'Inter', sans-serif; } .hero-title { font-family: var(--font-display); font-size: clamp(48px, 8vw, 120px); font-weight: 600; line-height: 0.95; letter-spacing: -0.02em; } .layout { display: grid; grid-template-columns: repeat(12, 1fr); gap: 24px; max-width: 1440px; margin: 0 auto; } .content-main { grid-column: 1 / 9; } .content-aside { grid-column: 9 / 13; } ``` ## Best Practices **Never Default to Generic Choices**: Every project gets a unique aesthetic direction. Don't converge on Space Grotesk, Inter, or system fonts across all projects. **Match Complexity to Vision**: Maximalist designs need elaborate code with extensive animations. Minimalist designs need precision, restraint, and attention to spacing and typography details. **Design Before Coding**: Whether extracting from screenshots or building from scratch, understand the design system before writing implementation code. **Use CSS Variables**: Define your design tokens (colors, spacing, typography) as CSS custom properties for consistency. **Test Responsively**: Ensure your design works across viewport sizes. Use `clamp()` for fluid typography, CSS Grid for flexible layouts. ## Reference Documentation The skill includes comprehensive reference files in the Engineer Kit: - `references/design-extraction-overview.md` - Process for analyzing screenshots - `references/extraction-prompts.md` - Prompts for comprehensive design analysis - `references/visual-analysis-overview.md` - Verifying implementation quality - `references/asset-generation.md` - Generating design-aligned visual assets - `references/technical-overview.md` - Optimization and performance best practices - `references/animejs.md` - Advanced JavaScript animations These live at `../claudekit-engineer/.claude/skills/frontend-design/references/`. ## Related Skills and Commands Combine Frontend Design with these other skills for complete workflows: - [AI Multimodal](/docs/engineer/skills/ai-multimodal) - Extract design from screenshots, generate visual assets - [Frontend Development](/docs/engineer/skills/frontend-development) - Implement with React/TypeScript best practices - [Media Processing](/docs/engineer/skills/media-processing) - Optimize generated images, remove backgrounds - [Chrome DevTools](/docs/engineer/skills/chrome-devtools) - Take screenshots of implementations for comparison ## Key Principle The skill exists to help you avoid "AI slop" aesthetics. Every design should feel intentional, contextual, and memorable. Whether you're replicating a screenshot with pixel-perfect precision or creating an original design with bold choices, the goal is the same: create something distinctive that people actually remember. --- # ck:debug Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/ck-debug # Debug Comprehensive debugging framework that combines systematic investigation, root cause tracing, and multi-layer validation. No fixes without understanding the root cause first. ## Core Principle **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST** Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success. ## When to Use **Always use for**: Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete **Especially when**: Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success ## The Four Techniques ### 1. Systematic Debugging Four-phase framework ensuring proper investigation: - **Phase 1**: Root Cause Investigation (read errors, reproduce, check changes, gather evidence) - **Phase 2**: Pattern Analysis (find working examples, compare, identify differences) - **Phase 3**: Hypothesis and Testing (form theory, test minimally, verify) - **Phase 4**: Implementation (create test, fix once, verify) **Key rule**: Complete each phase before proceeding. No fixes without Phase 1. ### 2. Root Cause Tracing Trace bugs backward through call stack to find original trigger. When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom. Includes `scripts/find-polluter.sh` for bisecting test pollution. ### 3. Defense-in-Depth Validate at every layer data passes through. Make bugs impossible. **Four layers**: Entry validation → Business logic → Environment guards → Debug instrumentation ### 4. Verification Run verification commands and confirm output before claiming success. **Iron law**: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE Run the command. Read the output. Then claim the result. ## Usage Activate automatically for any debugging task. This skill guides the debugging process from investigation to verified fix. ## Example Prompts - "Tests are failing in the authentication module" - "Users report the app crashes on login" - "Performance degraded after recent deployment" - "Build fails with cryptic error message" - "Integration tests pass locally but fail in CI" ## Quick Reference ``` Bug → Systematic Debugging (Phase 1-4) Error deep in stack? → Root Cause Tracing (trace backward) Found root cause? → Defense-in-Depth (add layers) About to claim success? → Verification (verify first) ``` ## Red Flags Stop and follow process if thinking: - "Quick fix for now, investigate later" - "Just try changing X and see if it works" - "It's probably X, let me fix that" - "Should work now" / "Seems fixed" - "Tests pass, we're done" **All mean**: Return to systematic process. ## Additional Capabilities The full skill includes six more techniques for system-level investigation: - **Investigation Methodology** — five-step structured investigation for server incidents and multi-component failures - **Log & CI/CD Analysis** — collect and correlate logs from servers, GitHub Actions, and application layers - **Performance Diagnostics** — identify bottlenecks, slow queries, and resource exhaustion - **Reporting Standards** — structured diagnostic reports with executive summary, technical analysis, and recommendations - **Task Management** — track multi-step investigations via Claude Tasks (TaskCreate/TaskUpdate); falls back to TodoWrite in VSCode - **Frontend Verification** — visual verification via Chrome MCP or `ck:chrome-devtools` for UI bugs and visual regressions ## Related Skills - [Fix](/docs/engineer/skills/fix) - Complete bug fixing workflow with intelligent routing - [Context Engineering](/docs/engineer/skills/context-engineering) - For complex debugging requiring context optimization --- # ck:payment-integration Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/payment-integration # Payment Integration Implement payment processing with SePay (Vietnamese market) and Polar (global SaaS monetization). ## When to Use - Payment gateway integration and checkout flows - Subscription management with trials, upgrades, and billing - QR code payments (VietQR, NAPAS) and bank transfers - Usage-based billing with metering and credits - Automated benefit delivery (licenses, GitHub access, Discord roles) - Webhook handling for payment notifications - Customer portals for self-service management - Tax compliance and global payments ## Platform Selection ### Choose SePay for: - Vietnamese market (VND currency) - Bank transfer automation (44+ Vietnamese banks) - VietQR/NAPAS payments - Local payment methods - Direct bank account monitoring ### Choose Polar for: - Global SaaS products - Subscription lifecycle management - Usage-based billing - Automated benefits (GitHub, Discord, licenses) - Merchant of Record (handles global tax compliance) - Digital product sales ## Key Capabilities | Feature | SePay | Polar | |---------|-------|-------| | Payment methods | QR, bank transfer, cards | Cards, subscriptions, usage-based | | Bank monitoring | Webhooks for 44+ VN banks | N/A | | Tax handling | Manual | MoR (global compliance) | | Subscriptions | Manual | Full lifecycle management | | Benefits automation | Manual | GitHub, Discord, licenses, files | | Rate limit | 2 calls/second | 300 req/min | | Customer portal | No | Built-in self-service | ## Common Use Cases ### Vietnamese E-commerce Checkout Implement VietQR payment flow with bank transfer monitoring. ``` "Set up SePay checkout with VietQR generation for bank transfers. Monitor transactions via webhook and mark orders paid when bank account receives matching amount." ``` ### SaaS Subscription Platform Build subscription system with automated license delivery. ``` "Use Polar to create subscription product with 3 tiers. Implement checkout flow and webhook handler that auto-generates license keys on successful subscription." ``` ### Usage-Based Billing Implement metered billing for API usage or credits. ``` "Set up Polar usage-based pricing that tracks API calls per month. Configure webhooks to monitor usage and automatically upgrade/downgrade subscriptions." ``` ### Automated GitHub Access Deliver private repository access on payment. ``` "Use Polar's GitHub benefit to automatically grant repository access when customer subscribes. Remove access on subscription cancellation." ``` ## Implementation Workflow ### SePay Quick Start 1. Load `references/sepay/overview.md` for auth setup 2. Load `references/sepay/sdk.md` for integration code 3. Load `references/sepay/webhooks.md` for payment notifications 4. Use `scripts/sepay-webhook-verify.js` for webhook verification 5. Load `references/sepay/best-practices.md` for production ### Polar Quick Start 1. Load `references/polar/overview.md` for auth and concepts 2. Load `references/polar/products.md` for product setup 3. Load `references/polar/checkouts.md` for payment flows 4. Load `references/polar/webhooks.md` for event handling 5. Load `references/polar/benefits.md` for automated delivery 6. Use `scripts/polar-webhook-verify.js` for webhook verification 7. Load `references/polar/best-practices.md` for production ## Pro Tips - Start with sandbox/test mode before production deployment - Always verify webhook signatures to prevent fraudulent requests - Load references progressively - only what you need for current step - Use provided scripts for webhook verification boilerplate - For SePay: Monitor rate limits (2 calls/second) - For Polar: Leverage MoR benefits to avoid tax compliance complexity - **Not activating?** Say: "Use payment-integration skill to integrate Polar checkout" ## Related Skills - [Backend Development](/docs/engineer/skills/backend-development) - API implementation - [Web Frameworks](/docs/engineer/skills/web-frameworks) - Checkout UI integration --- ## Key Takeaway Use SePay for Vietnamese market (VietQR, bank transfers, 44+ banks) and Polar for global SaaS (subscriptions, usage billing, automated benefits with tax compliance). --- # ck:context-engineering Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/context-engineering # Context Engineering The art and science of curating the smallest high-signal token set for maximum LLM reasoning quality while minimizing token usage. ## What This Skill Does Context Engineering helps you design, debug, and optimize agent systems where context limits constrain performance. It provides frameworks for understanding context degradation, implementing compression strategies, and building multi-agent architectures that isolate work efficiently. Think of it as your context budget manager—monitoring usage, detecting degradation patterns, and guiding you toward architectures that maximize reasoning quality per token spent. ## When to Activate - Designing or debugging agent systems - Context limits are constraining performance - Optimizing cost or latency - Building multi-agent coordination - Implementing memory systems - Evaluating agent performance - Developing LLM-powered pipelines ## Core Principles 1. **Context quality > quantity** - High-signal tokens beat exhaustive content 2. **Attention is finite** - U-shaped curve favors beginning/end positions 3. **Progressive disclosure** - Load information just-in-time 4. **Isolation prevents degradation** - Partition work across sub-agents 5. **Measure before optimizing** - Know your baseline ## Four-Bucket Strategy 1. **Write**: Save context externally (scratchpads, files) 2. **Select**: Pull only relevant context (retrieval, filtering) 3. **Compress**: Reduce tokens while preserving info (summarization) 4. **Isolate**: Split across sub-agents (partitioning) ## Key Metrics - **Token utilization**: Warning at 70%, trigger optimization at 80% - **Token variance**: Explains 80% of agent performance variance - **Multi-agent cost**: ~15x single agent baseline - **Compaction target**: 50-70% reduction, <5% quality loss - **Cache hit target**: 70%+ for stable workloads ## Usage Activate when asking about context percentage, rate limits, usage warnings, context optimization, agent architectures, or memory systems. ## Example Prompts - "What's my current context usage? Should I be concerned?" - "How can I optimize this agent workflow to use fewer tokens?" - "Design a multi-agent architecture for processing large codebases" - "Why is my agent failing on large files?" - "Implement a memory system for cross-session knowledge" ## Quick Reference Topics - **Fundamentals**: Context anatomy, attention mechanics - **Degradation**: Lost-in-middle, poisoning, debugging failures - **Optimization**: Compaction, masking, caching, partitioning - **Compression**: Long sessions, summarization strategies - **Memory**: Cross-session persistence, knowledge graphs - **Multi-Agent**: Coordination patterns, context isolation - **Evaluation**: Testing agents, LLM-as-Judge, metrics - **Tool Design**: Tool consolidation, description engineering --- # ck:web-testing Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/web-testing # Web Testing Comprehensive web testing covering unit, integration, E2E, load, security, visual regression, and accessibility testing with industry-standard tools. ## What This Skill Does The Web Testing skill provides complete testing patterns and infrastructure for modern web applications. It covers the entire testing pyramid from unit tests to load testing, with specialized knowledge of Playwright, Vitest, k6, axe-core, and Lighthouse. Think of it as your testing expert—knowing which testing strategy fits your architecture, how to prevent flakiness, optimize CI/CD pipelines, and ensure your app meets performance and accessibility standards. ## Core Capabilities - **Unit/Integration Testing**: Vitest, browser mode, AAA pattern - **E2E Testing**: Playwright fixtures, sharding, selectors - **Component Testing**: React/Vue/Angular patterns (production-ready) - **Load Testing**: k6 patterns and scenarios - **Performance**: Core Web Vitals, Lighthouse CI - **Visual Regression**: Screenshot comparison - **Accessibility**: WCAG, axe-core integration - **Security**: OWASP Top 10 checklists - **Test Infrastructure**: Data management, CI/CD workflows ## Quick Start ```bash npx vitest run # Unit tests npx playwright test # E2E tests npx playwright test --ui # E2E with UI k6 run load-test.js # Load tests npx @axe-core/cli https://example.com # Accessibility npx lighthouse https://example.com # Performance ``` ## Testing Strategy (Choose Your Model) | Model | Structure | Best For | |-------|-----------|----------| | Pyramid | Unit 70% > Integration 20% > E2E 10% | Monoliths | | Trophy | Integration-heavy | Modern SPAs | | Honeycomb | Contract-centric | Microservices | ## Usage Activate when mentioning testing, E2E, Playwright, Vitest, flakiness, Core Web Vitals, mobile gestures, cross-browser, or accessibility testing. ## Example Prompts - "Set up Playwright for E2E testing" - "Write unit tests for this component with Vitest" - "Create a load test scenario with k6" - "Check accessibility with axe-core" - "Fix flaky tests in the login flow" - "Optimize Core Web Vitals in CI" - "Test mobile gestures with Playwright" - "Run cross-browser tests on Chrome, Firefox, Safari" ## Reference Documentation ### Core Testing - Unit/Integration testing with Vitest - E2E testing with Playwright - Component testing patterns - Playwright component testing (production-ready) ### Test Infrastructure - Test data management (factories, fixtures, seeding) - Database testing (Testcontainers, transactions) - CI/CD workflows (GitHub Actions, sharding) - Contract testing (Pact, MSW) ### Cross-Browser & Mobile - Cross-browser checklist - Mobile gesture testing (touch, swipe, orientation) ### Performance & Quality - Core Web Vitals (LCP/CLS/INP, Lighthouse CI) - Visual regression (screenshot comparison) - Test flakiness mitigation ### Accessibility & Security - Accessibility testing (WCAG, axe-core) - Security testing (OWASP Top 10) - Security checklists (auth, API, headers) ### API & Load - API testing (Supertest, GraphQL) - Load testing with k6 ## Scripts **Initialize Playwright Project:** ```bash node ./scripts/init-playwright.js [--ct] [--dir ] ``` Creates best-practice Playwright setup: config, fixtures, example tests. **Analyze Test Results:** ```bash node ./scripts/analyze-test-results.js \ --playwright test-results/results.json \ --vitest coverage/vitest.json \ --output markdown ``` Parses Playwright/Vitest/JUnit results into unified summary. ## CI/CD Integration ```yaml jobs: test: steps: - run: npm run test:unit # Gate 1: Fast fail - run: npm run test:e2e # Gate 2: After unit pass - run: npm run test:a11y # Accessibility - run: npx lhci autorun # Performance ``` ## What Makes This Different Web Testing skill provides battle-tested patterns from production apps—solving real problems like test flakiness, slow CI pipelines, and cross-browser compatibility. Not theory, but proven infrastructure. ## Related Skills - [Agent Browser](/docs/engineer/skills/agent-browser) - For AI-optimized browser automation - [React Best Practices](/docs/engineer/skills/react-best-practices) - For performance optimization - [Web Design Guidelines](/docs/engineer/skills/web-design-guidelines) - For accessibility standards --- # ck:frontend-development Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/frontend-development # Frontend Development Building React applications the modern way means embracing Suspense, lazy loading, and proper data fetching patterns. This skill shows you how. ## What This Skill Does Frontend Development provides comprehensive guidelines for building modern React applications with TypeScript. It emphasizes Suspense-based data fetching with TanStack Query, lazy loading for performance, proper file organization using a features directory, MUI v7 for styling, and TanStack Router for navigation. This isn't just a collection of code snippets. It's a complete approach to structuring React applications that scale, perform well, and maintain consistency across your codebase. You'll learn patterns that prevent common pitfalls like layout shift from loading states, memory leaks from untracked effects, and prop drilling from poor component organization. The skill covers everything from creating a single component to organizing multi-feature applications, with specific guidance on data fetching, styling, routing, error handling, and performance optimization. ## Prerequisites You should have: - Working knowledge of React and TypeScript - Familiarity with npm or yarn package managers - Basic understanding of async/await patterns - A React project set up (or willingness to create one) The skill assumes you're working with: - React 18.3+ - TypeScript 5.7+ - TanStack Query v5 (for data fetching) - TanStack Router (for routing) - MUI v7 (Material-UI for components and styling) ## Quick Start Checklists ### Creating a New Component When you create a component, follow this checklist: - Use `React.FC` pattern with TypeScript - Lazy load if it's a heavy component (DataGrid, charts, editors) - Wrap in `` for loading states - Use `useSuspenseQuery` for data fetching - Import using aliases: `@/`, `~types`, `~components`, `~features` - Styles: inline if under 100 lines, separate `.styles.ts` file if over 100 lines - Use `useCallback` for event handlers passed to children - Default export at bottom - Never use early returns for loading states - Use `useMuiSnackbar` for user notifications ### Creating a New Feature When building a feature, set up this structure: ``` src/features/my-feature/ api/ myFeatureApi.ts # API service layer components/ MyFeature.tsx # Main component SubComponent.tsx # Related components hooks/ useMyFeature.ts # Custom hooks helpers/ myFeatureHelpers.ts # Utility functions types/ index.ts # TypeScript types index.ts # Public exports ``` Then create a route in `src/routes/my-feature/index.tsx` with lazy loading. ## Core Patterns ### Component Structure Modern React components follow a consistent pattern: ```typescript import React, { useState, useCallback } from 'react'; import { Box, Paper } from '@mui/material'; import { useSuspenseQuery } from '@tanstack/react-query'; import { featureApi } from '../api/featureApi'; import type { FeatureData } from '~types/feature'; interface MyComponentProps { id: number; onAction?: () => void; } export const MyComponent: React.FC = ({ id, onAction }) => { const [state, setState] = useState(''); const { data } = useSuspenseQuery({ queryKey: ['feature', id], queryFn: () => featureApi.getFeature(id), }); const handleAction = useCallback(() => { setState('updated'); onAction?.(); }, [onAction]); return ( {/* Content */} ); }; export default MyComponent; ``` **Key points**: - Props interface with clear types - `useSuspenseQuery` instead of `isLoading` checks - `useCallback` for handlers passed to children - Named const export + default export - MUI components with `sx` prop for styling ### Data Fetching with useSuspenseQuery The primary pattern for data fetching is `useSuspenseQuery`: ```typescript import { useSuspenseQuery } from '@tanstack/react-query'; import { postsApi } from '~features/posts/api/postsApi'; // Inside component const { data } = useSuspenseQuery({ queryKey: ['posts', { status: 'published' }], queryFn: () => postsApi.getPosts({ status: 'published' }), }); // data is guaranteed to be defined (no null checks needed) ``` This replaces the old pattern of checking `isLoading` and showing spinners. Instead, wrap components in ``: ```typescript import { SuspenseLoader } from '~components/SuspenseLoader'; // In parent component ``` ### File Organization Organize code by feature, not by type: **Good** (features directory): ``` src/features/ posts/ api/postsApi.ts components/PostList.tsx hooks/usePosts.ts types/index.ts comments/ api/commentsApi.ts components/CommentList.tsx ``` **Bad** (organized by type): ``` src/ api/ postsApi.ts commentsApi.ts components/ PostList.tsx CommentList.tsx ``` The `components/` directory at the root is for truly reusable components like `SuspenseLoader` and `CustomAppBar`. ### Import Aliases Use import aliases for cleaner imports: ```typescript // Instead of: import { apiClient } from '../../../lib/apiClient' import { apiClient } from '@/lib/apiClient'; // Instead of: import type { User } from '../../../types/user' import type { User } from '~types/user'; // Instead of: import { SuspenseLoader } from '../../components/SuspenseLoader' import { SuspenseLoader } from '~components/SuspenseLoader'; // Instead of: import { authApi } from '../features/auth/api/authApi' import { authApi } from '~features/auth'; ``` Aliases are defined in `vite.config.ts`: - `@/` resolves to `src/` - `~types` resolves to `src/types` - `~components` resolves to `src/components` - `~features` resolves to `src/features` ### Styling with MUI v7 Use the `sx` prop for styling MUI components: ```typescript import type { SxProps, Theme } from '@mui/material'; // Inline styles (under 100 lines) const styles: Record> = { container: { p: 2, bgcolor: 'background.paper', }, header: { display: 'flex', justifyContent: 'space-between', mb: 3, }, }; // In component {/* Content */} ``` For over 100 lines of styles, create a separate `.styles.ts` file. **MUI v7 Grid Syntax** (important change): ```typescript // ✅ Correct (v7) Content // ❌ Wrong (old syntax) Content ``` ### Routing with TanStack Router Create folder-based routes with lazy loading: ```typescript // src/routes/posts/index.tsx import { createFileRoute } from '@tanstack/react-router'; import { lazy } from 'react'; const PostsPage = lazy(() => import('@/features/posts/components/PostsPage')); export const Route = createFileRoute('/posts/')({ component: PostsPage, loader: () => ({ crumb: 'Posts' }), }); ``` Directory structure maps to URLs: - `routes/posts/index.tsx` → `/posts` - `routes/posts/create/index.tsx` → `/posts/create` - `routes/posts/$postId/index.tsx` → `/posts/:postId` ### Loading and Error States **Critical Rule**: Never use early returns for loading states. ```typescript // ❌ BAD - Causes layout shift if (isLoading) { return ; } // ✅ GOOD - Consistent layout ``` For user feedback, use `useMuiSnackbar`: ```typescript import { useMuiSnackbar } from '@/hooks/useMuiSnackbar'; const { showSnackbar } = useMuiSnackbar(); // Success message showSnackbar('Post created successfully', 'success'); // Error message showSnackbar('Failed to save changes', 'error'); ``` Never use `react-toastify` or early return loading states. ## Performance Optimization ### Lazy Loading Lazy load heavy components: ```typescript import React from 'react'; // Heavy components (DataGrid, charts, editors) const DataGrid = React.lazy(() => import('@mui/x-data-grid').then(m => ({ default: m.DataGrid }))); const RichTextEditor = React.lazy(() => import('~/components/RichTextEditor')); // In component ``` ### Memoization Use `useMemo` for expensive computations: ```typescript import { useMemo } from 'react'; const filteredPosts = useMemo(() => { return posts .filter(p => p.status === 'published') .sort((a, b) => b.createdAt - a.createdAt); }, [posts]); ``` Use `useCallback` for event handlers passed to children: ```typescript import { useCallback } from 'react'; const handleClick = useCallback(() => { console.log('Button clicked'); }, []); ``` Use `React.memo` for expensive components: ```typescript import React from 'react'; const ExpensiveComponent = React.memo(({ data }) => { // Complex rendering logic }); ``` ## Real-World Examples ### Create a Posts List Page Full workflow from scratch: **Step 1: Create feature structure** ```bash mkdir -p src/features/posts/{api,components,hooks,types} ``` **Step 2: Define TypeScript types** ```typescript // src/features/posts/types/index.ts export interface Post { id: number; title: string; content: string; status: 'draft' | 'published'; createdAt: Date; } ``` **Step 3: Create API service** ```typescript // src/features/posts/api/postsApi.ts import { apiClient } from '@/lib/apiClient'; import type { Post } from '../types'; export const postsApi = { getPosts: async (): Promise => { const { data } = await apiClient.get('/posts'); return data; }, getPost: async (id: number): Promise => { const { data } = await apiClient.get(`/posts/${id}`); return data; }, }; ``` **Step 4: Create component with useSuspenseQuery** ```typescript // src/features/posts/components/PostsList.tsx import React from 'react'; import { Box, Paper, Typography } from '@mui/material'; import { useSuspenseQuery } from '@tanstack/react-query'; import { postsApi } from '../api/postsApi'; export const PostsList: React.FC = () => { const { data: posts } = useSuspenseQuery({ queryKey: ['posts'], queryFn: postsApi.getPosts, }); return ( {posts.map(post => ( {post.title} {post.content} ))} ); }; export default PostsList; ``` **Step 5: Create route with lazy loading** ```typescript // src/routes/posts/index.tsx import { createFileRoute } from '@tanstack/react-router'; import { lazy } from 'react'; const PostsList = lazy(() => import('@/features/posts/components/PostsList')); export const Route = createFileRoute('/posts/')({ component: PostsList, loader: () => ({ crumb: 'Posts' }), }); ``` ## Best Practices Summary **Always Use Suspense**: Wrap lazy components and components using `useSuspenseQuery` in ``. **Lazy Load Heavy Components**: DataGrid, charts, rich text editors, and any component over 50KB should be lazy loaded. **Organize by Feature**: Group related code in `features/` directory with subdirectories for api, components, hooks, helpers, and types. **Use Import Aliases**: Cleaner imports with `@/`, `~types`, `~components`, `~features`. **Inline vs Separate Styles**: Under 100 lines inline, over 100 lines in separate `.styles.ts` file. **No Early Returns**: Prevents Cumulative Layout Shift. Use Suspense boundaries instead. **TypeScript Strict Mode**: Explicit return types, no `any` type, type imports with `import type`. ## Reference Documentation The skill includes detailed reference files in the Engineer Kit at `../claudekit-engineer/.claude/skills/frontend-development/resources/`: - `component-patterns.md` - Component structure, props, exports - `data-fetching.md` - TanStack Query patterns, API service layer - `file-organization.md` - Features directory, import aliases - `styling-guide.md` - MUI v7, sx prop, inline vs separate styles - `routing-guide.md` - TanStack Router, folder-based routes - `loading-and-error-states.md` - Suspense, error handling, user feedback - `performance.md` - Lazy loading, memoization, optimization - `typescript-standards.md` - Type safety, interfaces, generics - `common-patterns.md` - Forms, auth, DataGrid, dialogs - `complete-examples.md` - Full working examples ## Related Skills and Commands Combine Frontend Development with: - [Frontend Design](/docs/engineer/skills/frontend-design) - Create distinctive UI designs before implementing them - [AI Multimodal](/docs/engineer/skills/ai-multimodal) - Generate assets, extract design from screenshots - [Chrome DevTools](/docs/engineer/skills/chrome-devtools) - Test your application, take screenshots, debug issues ## Core Principles The skill is built on eight core principles: 1. Lazy load everything heavy 2. Use Suspense for loading states 3. Use `useSuspenseQuery` for data fetching 4. Organize features with dedicated directories 5. Inline styles under 100 lines, separate file over 100 lines 6. Use import aliases for clean imports 7. No early returns (prevents layout shift) 8. Use `useMuiSnackbar` for all user notifications Follow these principles and your React applications will be performant, maintainable, and consistent. --- # ck:gkg Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/gkg # GKG Semantic code analysis engine using AST parsing and KuzuDB graph database. Enables IDE-like code navigation for AI assistants. ## What This Skill Does The GitLab Knowledge Graph (GKG) skill provides semantic code understanding through abstract syntax tree parsing and graph database storage. It gives ClaudeKit IDE-like capabilities: go-to-definition, find-all-usages, impact analysis, and architecture visualization. Think of it as having an LSP server for your AI assistant—asking "where is this function used?" gets you precise answers across the entire codebase, not grep results. ## When to Use - Find all usages of a function/class across codebase - Go-to-definition for symbols - Impact analysis before refactoring - Generate architecture diagrams - RAG-enhanced code understanding **Use repomix instead** for: quick context dumps, any-language support, remote repos, token counting. ## Core Capabilities - Index repositories with AST parsing - Semantic search across codebases - Cross-file reference tracking - Symbol definition lookup - Impact analysis for refactoring - Architecture diagram generation - HTTP API and MCP integration ## Language Support | Language | Cross-file Refs | |----------|-----------------| | Ruby | ✅ Full | | Java | ✅ Full | | Kotlin | ✅ Full | | Python | 🚧 In progress | | TypeScript | 🚧 In progress | | JavaScript | 🚧 In progress | ## Quick Start ```bash # Index current repo gkg index # Start server (for API/MCP) gkg server start # Stop before re-indexing gkg server stop ``` ## Usage Activate when needing semantic code analysis, impact assessment, or architecture understanding. ## Example Prompts - "Find all places where the `authenticate` function is called" - "Show me the definition of the User class" - "What would break if I change this API signature?" - "Generate an architecture diagram of the authentication module" - "Which files import this utility function?" ## Core Workflows ### Index and Query ```bash gkg index /path/to/project --stats gkg server start # Query via HTTP API at http://localhost:27495 ``` ### Find Symbol Usages 1. Index project: `gkg index` 2. Start server: `gkg server start` 3. Use MCP tool `get_references` or HTTP API `/api/graph/search` ### Impact Analysis 1. Index affected repos 2. Query `get_references` for changed symbols 3. Review all call sites before refactoring ## Key Constraints - Must stop server before re-indexing - Requires initialized Git repository - Languages not connected across repos (yet) - TS/JS/Python cross-file refs incomplete ## What Makes This Different GKG provides semantic understanding, not text matching. It knows the difference between a function definition and a variable with the same name. The result: precise code navigation that scales to large codebases. ## Status Public beta | Requires Git repository | Storage: `~/.gkg/` --- # ck:shader Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/shader # Shader Write GPU-accelerated fragment shaders for procedural graphics, textures, and visual effects using GLSL. ## What This Skill Does The Shader skill enables you to create procedural graphics that run on the GPU using GLSL fragment shaders. From simple shapes to complex noise-based textures, this skill provides the patterns and functions you need to generate visuals mathematically. Think of it as your procedural graphics engine—every pixel calculated in parallel, creating wood grain, marble textures, clouds, terrain, or abstract art entirely from code. ## When to Use - Creating procedural textures (wood, marble, clouds, terrain) - Drawing shapes with distance fields (SDF) - Generating patterns, noise, gradients - Building visual effects and animations - Writing custom shaders for Three.js, WebGL, Processing ## Core Concepts Fragment shaders execute **simultaneously on every pixel**. Each thread: - Receives pixel position via `gl_FragCoord` - Returns color via `gl_FragColor` (vec4: RGBA 0.0-1.0) - Cannot communicate with other threads (stateless) ## Standard Uniforms ```glsl uniform float u_time; // Elapsed seconds uniform vec2 u_resolution; // Canvas size (width, height) uniform vec2 u_mouse; // Mouse position in pixels ``` Normalize coordinates: `vec2 st = gl_FragCoord.xy / u_resolution;` ## Essential Functions | Function | Purpose | Example | |----------|---------|---------| | `mix(a,b,t)` | Linear interpolate | `mix(red, blue, 0.5)` | | `step(edge,x)` | Hard threshold | `step(0.5, st.x)` | | `smoothstep(e0,e1,x)` | Smooth threshold | `smoothstep(0.2, 0.8, st.x)` | | `fract(x)` | Fractional part | `fract(st * 3.0)` for tiling | | `length(v)` | Vector magnitude | `length(st - 0.5)` | | `distance(a,b)` | Euclidean distance | `distance(st, center)` | ## Quick Patterns **Circle:** ```glsl float d = distance(st, vec2(0.5)); float circle = 1.0 - smoothstep(0.2, 0.21, d); ``` **Tiling:** ```glsl st = fract(st * 4.0); // 4x4 grid ``` **Animation:** ```glsl float wave = sin(st.x * 10.0 + u_time) * 0.5 + 0.5; ``` ## Usage Activate when working with GLSL shaders, procedural textures, visual effects, or WebGL graphics. ## Example Prompts - "Create a GLSL shader that draws a circle with a gradient" - "Generate Perlin noise for cloud textures" - "Write a shader that tiles a pattern across the screen" - "Build a procedural wood grain texture" - "Create an animated wave effect using sine functions" - "Make a shader that draws a star using polar coordinates" ## Topic Coverage ### Fundamentals - Data types, vectors, precision, coordinates - Shaping functions, step, smoothstep, curves, interpolation ### Drawing - Colors: RGB, HSB, gradients, mixing, color spaces - Shapes: SDF, circles, rectangles, polar coordinates - Polygons, stars, combinations ### Procedural - Patterns: Tiling, fract, matrices, transformations - Symmetry, Truchet tiles, domain warping - Noise: Random, Perlin, simplex, cellular, Voronoi - fBm: Fractional Brownian Motion, turbulence, octaves - Procedural textures: Clouds, marble, wood, terrain ## Tools - **Online Editor**: editor.thebookofshaders.com - **glslViewer**: CLI tool for running .frag files - **glslCanvas**: HTML embed for live shaders - **ShaderToy**: iTime, iResolution, iMouse uniforms ## What Makes This Different Shader code generates infinite detail with tiny file sizes. No image assets, no downloads—pure math creating visuals that scale perfectly at any resolution. The GPU handles millions of pixels in parallel for real-time rendering. ## External Resources - The Book of Shaders: thebookofshaders.com - LYGIA Library: lygia.xyz (reusable shader functions) - ShaderToy: shadertoy.com - Inigo Quilez: iquilezles.org/articles/ --- # ck:plans-kanban Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/plans-kanban # Plans Dashboard > Open the integrated plans dashboard inside `ck config ui`. ## What This Skill Does `ck:plans-kanban` is now a thin launcher, not a standalone server. It opens the ClaudeKit CLI dashboard plans route and gives you: - multi-plan grid and kanban views - single-plan detail pages with progress summaries - timeline and activity heatmap views - markdown reader navigation for `plan.md` and phase files - quick phase actions such as start, complete, reset, validate, and start-next Scope note: - Project dashboards should show project-scoped plans only. - Global dashboards should show global-scoped plans only. - `ck plan status` remains the authoritative dependency/status view for `blockedBy` / `blocks`. ## How It Works When invoked, the launcher: 1. checks whether the CLI dashboard is already running 2. starts `ck config ui --port 3456 --no-open` if needed 3. opens the plans route in your browser Default URL: ```text http://localhost:3456/plans ``` If port `3456` is busy, the CLI may auto-fallback to `3457-3460`, and the launcher follows that running port. ## Usage ```bash /ck:plans-kanban ``` Direct launcher: ```bash node .claude/skills/plans-kanban/scripts/open-dashboard.cjs ``` Run the dashboard manually: ```bash ck config ui ``` ## Deprecated Compatibility Old standalone-server flags are still accepted with warnings so existing habits do not break abruptly. | Legacy input | Current behavior | | --- | --- | | `--dir ` / positional path | Warns and ignores. This launcher opens the generic `/plans` route and does not choose a custom plan root. | | `--plans ` | Warns and ignores. | | `--port ` | Warns and ignores. The launcher targets the CLI dashboard starting at `3456`. | | `--host ` | Warns and ignores. Use `ck config ui --host ...` directly if needed. | | `--background` / `--foreground` | Warns and ignores. The standalone server flow no longer exists. | | `--stop` | Stops the launcher-managed dashboard process if present; otherwise prints manual shutdown guidance. | | `--open` | Accepted. Opening is now the default behavior. | ## Related CLI Commands ```bash ck config ui ck plan status /absolute/path/to/plan.md cd /absolute/path/to/plan-dir && ck plan check 1 --start cd /absolute/path/to/plan-dir && ck plan check 1 cd /absolute/path/to/plan-dir && ck plan uncheck 1 ``` ## What Changed Before this migration, `plans-kanban` owned: - its own localhost server - its own renderer and static assets - its own background server lifecycle After the migration, those responsibilities moved into `claudekit-cli` and `ck config ui`. That means: - there is no separate `localhost:3500` dashboard anymore - the canonical visual experience lives under the CLI dashboard - the skill exists to open the right place quickly, not to run a separate app stack - the generic `/plans` route still defaults to `plans` unless a `dir` query param is already present - scope-aware plan roots come from project/global dashboard context, not deprecated launcher flags ## Troubleshooting **`ck` not found** Install the ClaudeKit CLI and confirm `ck --version` works. **Dashboard did not open** Start it manually with: ```bash ck config ui --port 3456 ``` Then open `/plans` on the port the CLI reports. **Need a custom host or port** Run `ck config ui` directly with the flags you need. The skill intentionally stays thin and opinionated. **Need to stop a launcher-started dashboard** Run the launcher again with `--stop`. If you started the dashboard manually, stop the terminal running `ck config ui`. ## Related Skills - [ck:plan](/docs/engineer/skills/ck-plan) - plan creation and state management - [markdown-novel-viewer](/docs/engineer/skills/markdown-novel-viewer) - long-form markdown reading --- # ck:project-management Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/project-management # Project Management Project oversight using Claude's native task system with persistent plan files. Bridges sessions, tracks progress, coordinates docs updates, and generates status reports. ## What This Skill Does Project Management connects ephemeral session tasks to persistent plan files. Tasks disappear when a session ends—plan files don't. This skill maintains continuity by hydrating tasks from plan files at session start and syncing state back on completion. ## Core Capabilities ### Task Operations | Operation | When | |-----------|------| | `TaskCreate` | Hydrate from plan `[ ]` items, add discovered work | | `TaskUpdate` | Mark in_progress on start, completed on finish | | `TaskGet` | Read full task details before starting | | `TaskList` | Survey available / blocked work | ### Session Bridging The hydration pattern keeps plans and tasks in sync: ``` Session Start: Read plan files → find [ ] items → TaskCreate for each During Work: TaskUpdate(in_progress) → do work → TaskUpdate(completed) Sync Back: Mark [ ] → [x] in plan file, update YAML frontmatter status Next Session: Re-hydrate remaining [ ] items → continue ``` ### Progress Tracking Scan active plans directory, compute: - Phases complete vs. total - Tasks completed vs. in-progress vs. blocked - Estimated remaining effort (from phase frontmatter) - Blockers and dependencies ### Documentation Coordination After implementation milestones, triggers docs-manager to: - Update `./docs/` directory files - Evaluate claudekit-docs impact - Create or update relevant documentation pages ### Status Reporting Generates `plans/reports/project-status-YYMMDD.md` with: - Phase completion percentages - Active blockers - Recent completions - Next priorities ## Plan YAML Frontmatter Phase files support structured metadata for tracking: ```yaml --- title: "ck:project-management" status: in-progress # pending | in-progress | completed priority: P1 effort: medium branch: feature-branch tags: [auth, api] created: 2026-02-05 --- ``` ## Workflow ``` Scan Plans → Hydrate Tasks → Track Progress → Update Status → Generate Report → Trigger Doc Updates ``` 1. **Scan Plans** — find active `plans/` directories with uncompleted phases 2. **Hydrate Tasks** — create session tasks from `[ ]` items in phase files 3. **Track Progress** — monitor task state changes during session 4. **Update Status** — sync completed tasks back to plan files (`[x]`) 5. **Generate Report** — write status report with metrics 6. **Trigger Doc Updates** — coordinate with docs-manager if milestones hit ## Example Prompts - "What's the current status of the active plan?" - "Hydrate tasks from the authentication plan and start tracking" - "Generate a project status report" - "Mark the database phase complete and update the plan" - "What's blocked in the current sprint?" ## Related Skills - [Planning](/docs/engineer/skills/ck-plan) — creates the plan files this skill tracks - [Cook](/docs/engineer/skills/cook) — executes phases tracked by this skill - [Plans Kanban](/docs/engineer/skills/plans-kanban) — visual kanban view of plan progress --- # ck:copywriting Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/copywriting # Copywriting High-converting copy formulas, templates, and writing style extraction for marketing, landing pages, emails, and product descriptions. ## What This Skill Does The Copywriting skill transforms ClaudeKit into a conversion-focused copywriter with proven formulas like AIDA, PAS, BAB, and 4Ps. It provides headline templates, email patterns, landing page structures, and CTA optimization strategies used by top marketing teams. Beyond templates, this skill can extract writing styles from your existing content—docs, PDFs, images, videos—and apply that style to new copy, ensuring brand consistency across all your marketing. ## Core Capabilities - Apply proven copy formulas (AIDA, PAS, BAB, 4Ps, 4Us, FAB) - Generate high-converting headlines and subject lines - Structure landing pages for maximum conversion - Optimize CTAs for action - Extract writing styles from existing content (50+ formats) - Create email campaigns with persuasive patterns - Generate social media copy for each platform ## Copy Formulas Quick Reference | Formula | Structure | Best For | |---------|-----------|----------| | AIDA | Attention → Interest → Desire → Action | Landing pages, ads | | PAS | Problem → Agitate → Solution | Email, sales pages | | BAB | Before → After → Bridge | Testimonials, case studies | | 4Ps | Promise → Picture → Proof → Push | Long-form sales | | 4Us | Urgent + Unique + Useful + Ultra-specific | Headlines | | FAB | Feature → Advantage → Benefit | Product descriptions | ## Writing Style Extraction Extract styles from multi-format files: ```bash # List available styles python scripts/extract-writing-styles.py --list # Extract style from file python scripts/extract-writing-styles.py --style ``` Supported formats: `.md` `.txt` `.pdf` `.docx` `.xlsx` `.pptx` `.jpg` `.png` `.mp4` ## Usage Activate by mentioning copywriting, headlines, landing pages, emails, or marketing copy. ## Example Prompts - "Write a landing page for our SaaS product using AIDA formula" - "Create 10 headline variations for this feature announcement" - "Generate an email sequence for abandoned cart recovery" - "Extract the writing style from our existing marketing docs" - "Write product descriptions that emphasize benefits over features" - "Create social media posts for this blog article" ## Workflows - **CRO Optimization**: 25 conversion rate optimization principles - **Copy Enhancement**: Improve existing copy - **Fast Copy Generation**: Quick, time-sensitive copy - **Quality Copy with Research**: High-stakes content ## Best Practices 1. Lead with benefit, not feature 2. One CTA per piece 3. Specificity > vague claims 4. Read aloud—if awkward, rewrite 5. Test headlines first 6. Match copy to awareness level ## Related Skills - [AI Multimodal](/docs/engineer/skills/ai-multimodal) - Extract styles from images, videos, PDFs --- # ck:react-best-practices Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/react-best-practices # React Best Practices Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories prioritized by impact. ## What This Skill Does The React Best Practices skill provides battle-tested performance patterns from Vercel Engineering. These aren't theoretical guidelines—they're the actual optimizations used in production apps serving millions of users. Think of it as having a Vercel engineer pair-programming with you, catching performance issues before they hit production: eliminating waterfalls, optimizing bundles, preventing unnecessary re-renders, and implementing server-side optimizations. ## When to Apply Reference these guidelines when: - Writing new React components or Next.js pages - Implementing data fetching (client or server-side) - Reviewing code for performance issues - Refactoring existing React/Next.js code - Optimizing bundle size or load times ## Rule Categories by Priority | Priority | Category | Impact | Focus | |----------|----------|--------|-------| | 1 | Eliminating Waterfalls | CRITICAL | Parallel fetching, Suspense boundaries | | 2 | Bundle Size Optimization | CRITICAL | Dynamic imports, barrel files, tree-shaking | | 3 | Server-Side Performance | HIGH | React.cache(), LRU caching, serialization | | 4 | Client-Side Data Fetching | MEDIUM-HIGH | SWR deduplication, event listeners | | 5 | Re-render Optimization | MEDIUM | Memo, derived state, transitions | | 6 | Rendering Performance | MEDIUM | Content visibility, SVG optimization | | 7 | JavaScript Performance | LOW-MEDIUM | Map lookups, caching, iteration | | 8 | Advanced Patterns | LOW | Ref patterns, latest callbacks | ## Critical Optimizations (Top Priority) ### Eliminating Waterfalls - Move await into branches where actually used - Use Promise.all() for independent operations - Start promises early, await late in API routes - Use Suspense to stream content ### Bundle Size - Import directly, avoid barrel files - Use next/dynamic for heavy components - Load analytics/logging after hydration - Load modules only when feature activated - Preload on hover/focus for perceived speed ## Quick Reference **45 rules** with prefixes: - `async-*` - Waterfall elimination - `bundle-*` - Bundle optimization - `server-*` - Server performance - `client-*` - Client data fetching - `rerender-*` - Re-render optimization - `rendering-*` - Rendering performance - `js-*` - JavaScript performance - `advanced-*` - Advanced patterns ## Usage Activate when writing, reviewing, or refactoring React/Next.js code. ## Example Prompts - "Review this component for performance issues" - "Optimize this data fetching logic" - "Why is this page loading slowly?" - "Reduce the bundle size of this feature" - "Fix unnecessary re-renders in this form" - "Implement parallel data fetching for this page" ## How to Use Each rule file contains: - Brief explanation of why it matters - Incorrect code example with explanation - Correct code example with explanation - Additional context and references Browse individual rules at: `rules/async-parallel.md`, `rules/bundle-barrel-imports.md`, etc. ## What Makes This Different These aren't generic React tips—they're proven patterns from teams shipping high-performance applications at scale. The rules are prioritized by actual impact on Core Web Vitals and user experience, not theoretical importance. ## Related Skills - [Cook](/docs/engineer/skills/cook) - For implementing features with these patterns - [Web Testing](/docs/engineer/skills/web-testing) - For performance testing and Core Web Vitals --- # ck:remotion Section: engineer Category: skills URL: https://docs.claudekit.cc/docs/skills/remotion # Remotion Best practices for Remotion—create videos programmatically using React components, animations, and compositions. ## What This Skill Does The Remotion skill provides domain-specific knowledge for building videos in React. It covers everything from fundamental animations to advanced patterns like 3D content, chart visualization, caption display, and audio synchronization. Think of it as your Remotion expert sitting next to you—knowing the right way to sequence scenes, measure text for dynamic layouts, trim videos, apply transitions, and optimize for rendering. ## When to Use Activate whenever working with Remotion code to obtain best practices for video creation, animation timing, asset management, and composition patterns. ## Core Topics Covered - **Animations**: Fundamental skills, timing, interpolation curves, spring animations - **Compositions**: Defining compositions, stills, folders, dynamic metadata - **Assets**: Importing images, videos, audio, fonts - **Audio**: Importing, trimming, volume, speed, pitch control - **Captions**: Displaying captions with TikTok-style pages, word highlighting, SRT imports - **Charts**: Data visualization patterns - **3D**: Three.js and React Three Fiber integration - **Sequencing**: Delay, trim, limit duration of items - **Transitions**: Scene transition patterns - **Measuring**: Text dimensions, DOM nodes, fitting to containers ## Usage Activate when mentioning Remotion, video creation, programmatic rendering, or React-based animations. ## Example Prompts - "Create a Remotion composition with animated text overlays" - "Add background music with volume fade-in to this video" - "Generate captions from audio transcription and display them" - "Build a data visualization animation using Remotion charts" - "Sequence multiple scenes with transitions in Remotion" - "Measure text and fit it dynamically in video frames" - "Import Lottie animations into Remotion composition" ## Key Patterns ### Sequencing ```typescript ``` ### Trimming ```typescript