claudekit/README.md

Claude Kit

A comprehensive toolkit for Claude Code to accelerate development workflows for teams working with Python and JavaScript/TypeScript.

Features

• 20 Specialized Agents - From planning to deployment
• 43 Skills - Auto-triggered by context: framework, language, methodology, patterns, workflows, optimization (all with YAML frontmatter and bundled resources)
• 7 Behavioral Modes - Task-specific response optimization
• Token Optimization - 30-70% cost savings with compressed output modes
• MCP Integrations - Context7, Sequential Thinking, Playwright, Memory, Filesystem
• Context Management - Project indexing, checkpoints, parallel tasks

Quick Start

1. Copy the .claude folder to your project root
2. Customize .claude/CLAUDE.md for your project
3. Start working — skills auto-trigger based on what you ask ("implement X", "fix Y", "review Z")

Directory Structure

.claude/
├── CLAUDE.md              # Project context (customize this!)
├── settings.json          # Hooks, permissions, and MCP config
├── agents/                # 20 specialized agents
├── modes/                 # 7 behavioral mode definitions
├── mcp/                   # MCP server configurations
└── skills/                # 43 flat skills (router pattern)
    ├── <skill-name>/      # Each skill is a top-level directory
    │   ├── SKILL.md       # Trigger description + core patterns
    │   └── references/    # Deep content loaded on demand
    └── ...

Agents

Core Development

Agent	Description
planner	Task decomposition and planning
researcher	Technology research
debugger	Error analysis and fixing
tester	Test generation
code-reviewer	Code review with security focus
scout	Codebase exploration

Operations

Agent	Description
git-manager	Git operations and PRs
docs-manager	Documentation generation
project-manager	Progress tracking
database-admin	Schema and migrations
ui-ux-designer	UI component creation

Extended

Agent	Description
cicd-manager	CI/CD pipeline management
security-auditor	Security reviews
api-designer	API design and OpenAPI
vulnerability-scanner	Security scanning
pipeline-architect	Pipeline optimization

Skills as Commands

All former slash commands have been migrated to skills that auto-trigger based on context:

# Skills auto-trigger — just describe what you want:
"implement user authentication"     # → feature-workflow + authentication
"this endpoint is slow"             # → performance-optimization
"commit these changes"              # → git-workflows
"refactor this function"            # → refactoring
"add docs to this module"           # → documentation
"scan for security issues"          # → owasp
"switch to brainstorm mode"         # → mode-switching

Skills (43 Total)

Every skill follows a flat directory structure with a router pattern: short SKILL.md for triggering + references/ for deep content loaded on demand. Skills auto-trigger based on context — no slash commands needed.

Tech Stack Skills (7 merged routers)

Skill	Covers	Key Topics
languages	Python, TypeScript, JavaScript	Type hints, generics, async, Pydantic, Zod, ES6+
backend-frameworks	FastAPI, Django, NestJS, Express	Routes, DI, middleware, ORM, guards, pipes
frontend	React, Next.js, shadcn/ui	Hooks, App Router, server components, Suspense
frontend-styling	Tailwind CSS, accessibility	Responsive, dark mode, WCAG, ARIA, focus management
databases	PostgreSQL, MongoDB, Redis, migrations	Schema, indexing, aggregation, caching, Alembic/Prisma
devops	Docker, GitHub Actions, Cloudflare Workers	Multi-stage builds, CI/CD, edge deployment
testing	pytest, vitest, Jest	Fixtures, mocking, MSW, coverage, parametrize

Domain Skills (8)

Skill	Description
openapi	OpenAPI 3.1 spec, pagination, versioning, error schemas, webhooks
owasp	Top 10, auth, CORS, CSP, secret management, rate limiting
playwright	E2E testing, page objects, visual regression, cross-browser
error-handling	Custom errors, retry patterns, Result type, error boundaries
state-management	React state, Zustand, TanStack Query, form state, URL state
logging	Structured logging, log levels, correlation IDs, redaction
caching	Memoization, HTTP cache, Redis, CDN, cache invalidation
api-client	HTTP clients, interceptors, retry, type-safe clients

Pattern Skills (3)

Skill	Description
authentication	JWT, OAuth2, sessions, RBAC, MFA, password hashing
background-jobs	Celery, BullMQ, task queues, scheduled tasks, async workers
writing-concisely	Compressed output modes (30-70% token savings)

Workflow Skills (7 — migrated from commands)

Skill	Description
feature-workflow	End-to-end feature development: requirements → planning → implementation → testing → review
git-workflows	Conventional commits, shipping, PRs, changelogs
documentation	Docstrings, JSDoc, API docs, README generation
refactoring	Code smell detection, extract/rename/simplify patterns, safe refactoring workflow
performance-optimization	Profiling (cProfile, DevTools), N+1 queries, bundle size, memory leaks, benchmarking
mode-switching	Session behavioral modes (brainstorm, token-efficient, deep-research, implementation, review)
session-management	Checkpoints, project indexing, context loading, status checking

Methodology Skills (18)

Category	Skills
Planning	brainstorming, writing-plans, executing-plans, writing-skills
Testing	test-driven-development, verification-before-completion, testing-anti-patterns
Debugging	systematic-debugging, root-cause-tracing, defense-in-depth
Collaboration	dispatching-parallel-agents, requesting-code-review, receiving-code-review, finishing-a-development-branch
Execution	subagent-driven-development, using-git-worktrees, condition-based-waiting
Reasoning	sequential-thinking

Key methodology principles:

• TDD Strict: No production code without failing test first
• Verification: Evidence-based completion claims
• Quality Gates: Code review between every task
• Bite-sized Tasks: 2-5 minute increments with exact code
• Sequential Thinking: Step-by-step reasoning with confidence scores

Bundled Resources

Skills include progressive-disclosure resources loaded on demand:

Resource Type	Purpose	Examples
references/	Cheat sheets, decision trees, pattern catalogs	OWASP Top 10, index decision tree, auth flows
templates/	Starter files, boilerplate, configs	OpenAPI spec, Dockerfile, CI workflows
scripts/	Executable helpers for deterministic tasks	Security audit scanner, OpenAPI validator

Behavioral Modes

Switch modes to optimize responses for different task types:

Mode	Description	Best For
default	Balanced standard behavior	General tasks
brainstorm	Creative exploration, questions	Design, ideation
token-efficient	Compressed, concise output	Cost savings
deep-research	Thorough analysis, citations	Investigation
implementation	Code-focused, minimal prose	Executing plans
review	Critical analysis, finding issues	Code review
orchestration	Multi-task coordination	Parallel work

"switch to brainstorm mode"   # → mode-switching skill activates
"let's focus on implementation" # → implementation mode

Token Optimization

Reduce costs by 30-70% with compressed output modes:

Level	Activation	Savings
Standard	(default)	0%
Concise	Ask for concise output	30-40%
Ultra	Ask for code-only responses	60-70%
Session	"switch to token-efficient mode"	30-70%

MCP Integrations

MCP servers extend Claude Kit with powerful capabilities. They are automatically used when configured.

Server	Package	Purpose
Context7	@upstash/context7-mcp	Up-to-date library documentation
Sequential	@modelcontextprotocol/server-sequential-thinking	Multi-step reasoning
Playwright	@playwright/mcp	Browser automation (Microsoft)
Memory	@modelcontextprotocol/server-memory	Persistent knowledge graph
Filesystem	@modelcontextprotocol/server-filesystem	Secure file operations

How MCP Servers Enhance Skills

Skill	MCP Servers Used	Enhancement
feature-workflow	Context7, Sequential, Filesystem	Accurate docs, structured planning, safe file ops
systematic-debugging	Sequential, Memory, Playwright	Step-by-step debugging, context recall, browser testing
testing, playwright	Playwright, Filesystem	E2E browser tests, test file management
writing-plans	Sequential, Memory	Structured breakdown, remembers decisions
brainstorming	Sequential, Memory, Context7	Creative exploration, persistent ideas
session-management	Filesystem, Memory	Project scanning, context persistence

Example: Full Feature Development

"Add user profile with avatar upload"

1. feature-workflow skill activates → orchestrates the workflow
2. Context7 → Fetches latest React/Next.js file upload docs
3. Sequential → Plans component structure step-by-step
4. Memory → Recalls your UI patterns from previous sessions
5. Playwright → Tests the upload flow in browser

Setup: See .claude/mcp/README.md

Customization

CLAUDE.md

The .claude/CLAUDE.md file is your project context. Customize it with:

# Project: Your Project Name

## Tech Stack
- **Backend**: FastAPI
- **Frontend**: Next.js
- **Database**: PostgreSQL

## Conventions
- Use type hints
- 80% test coverage
- Conventional commits

## Agent Overrides
### Tester
- Framework: pytest
- Coverage: 90%

Adding Custom Skills

Create a new skill in .claude/skills/<name>/SKILL.md:

---
name: my-skill
description: >
  What this skill does and when to trigger it. Be specific — list
  contexts, keywords, and scenarios. 2-4 pushy sentences.
---

# My Skill

Brief overview.

## When to Use
- Scenario 1
- Scenario 2

## When NOT to Use
- Anti-trigger scenario

---

## Core Patterns
### Pattern Name
Code examples with good/bad comparisons.

## Best Practices
## Common Pitfalls
## Related Skills

Optionally add bundled resources:

my-skill/
├── SKILL.md
├── references/    # Loaded into context on demand
├── scripts/       # Executed without loading into context
└── templates/     # Scaffolded into user's project

Workflow Chains

Skills chain automatically based on context. Here are common flows:

Feature Development

brainstorming → writing-plans → feature-workflow → requesting-code-review → git-workflows

Bug Fix

systematic-debugging → root-cause-tracing → test-driven-development → verification-before-completion

Ship Code

verification-before-completion → requesting-code-review → git-workflows → finishing-a-development-branch

Superpowers Workflow (Detailed)

brainstorming → writing-plans → executing-plans → git-workflows

Uses one-question-at-a-time design, 2-5 min tasks with exact code, subagent execution with code review gates.

Parallel Work

dispatching-parallel-agents → subagent-driven-development → verification-before-completion

Launch multiple agents for independent tasks, then verify results.

Cost-Optimized Session

"switch to token-efficient mode" → [work on tasks] → "switch to default mode"

Enable compressed outputs for high-volume sessions.

Requirements

• Claude Code 1.0+
• Git
• Node.js or Python (depending on your stack)

License

MIT

---

Built with duthaho