A comprehensive guide to customizing Claude Code plugins for your organization, using bkit as a reference implementation.
Part I: Understanding bkit
- bkit Design Philosophy
- Why bkit is Well-Designed
- Supported Languages & Frameworks
- Enterprise AI-Native Architecture
Part II: Plugin Architecture
Part III: Customization Guide
- Customizing Agents
- Customizing Skills
- Customizing Commands
- Customizing Hooks
- Creating Templates
- Organization-Specific Customization
Part IV: Reference
Before customizing bkit, understanding its design intent helps you make better decisions about what to adapt and what to keep.
"Enable all developers using Claude Code to naturally adopt 'document-driven development' and 'continuous improvement' even without knowing commands or PDCA methodology"
In essence: AI guides humans toward good development practices.
| Philosophy | Description | Implementation |
|---|---|---|
| Automation First | Claude automatically applies PDCA even if user doesn't know commands | bkit-rules skill + PreToolUse hooks |
| No Guessing | If unsure, check docs → If not in docs, ask user (never guess) | Design-first workflow, gap-detector agent |
| Docs = Code | Design first, implement later (maintain design-implementation sync) | PDCA workflow + /pdca-analyze command |
When customizing bkit, consider keeping these architectural patterns:
Layer 1: hooks.json → SessionStart, PreToolUse, PostToolUse hooks
Layer 2: Skill Frontmatter → hooks: PreToolUse, PostToolUse, Stop
Layer 3: Agent Frontmatter → hooks: PreToolUse, PostToolUse
Layer 4: Description Triggers → "Triggers:" keyword matching
Layer 5: Scripts → Actual bash logic execution
This separation allows fine-grained control over when and how automation triggers.
bkit automatically adjusts its behavior based on detected project complexity:
| Level | Detection | Behavior |
|---|---|---|
| Starter | Simple HTML/CSS structure | Friendly explanations, simplified PDCA |
| Dynamic | Next.js + BaaS indicators | Technical but clear, full PDCA |
| Enterprise | K8s/Terraform/microservices | Concise, architecture-focused |
Pipeline Phase (e.g., API Implementation)
├── Plan: Define requirements
├── Design: Write spec
├── Do: Implement
├── Check: Gap analysis
└── Act: Document learnings
Each of the 9 pipeline phases runs its own PDCA cycle—not one PDCA for the whole project.
Instead of writing test scripts, bkit uses:
- Structured JSON logging
- Request ID flow tracking
- AI-powered real-time log analysis
- Automatic issue documentation
| Keep As-Is | Safe to Customize |
|---|---|
| PDCA workflow structure | Trigger keywords (add your language) |
| Level detection logic | Agent communication style |
| Hook event architecture | Template content and structure |
| Gap analysis methodology | Skill domain knowledge |
For deeper understanding, explore the bkit-system/ folder:
| Document | Purpose |
|---|---|
| bkit-system/README.md | System architecture overview |
| Core Mission | 3 philosophies explained |
| AI-Native Principles | AI-Native development model |
| PDCA Methodology | PDCA + 9-stage pipeline |
| Graph Index | Obsidian visualization hub |
Tip: Open
bkit-system/as an Obsidian vault and pressCtrl/Cmd + Gto visualize all component relationships.
bkit is not just a collection of prompts—it's a production-grade plugin architecture with carefully designed components that work together as a cohesive system.
| Component | Count | Purpose |
|---|---|---|
| Agents | 11 | Specialized AI subagents for task delegation |
| Skills | 18 | Domain knowledge and automated behaviors |
| Commands | 18 | User-invocable slash commands |
| Scripts | 18 | Hook execution scripts (bash) |
| Templates | 21 | Document templates (PDCA + 9 phases) |
| Hooks | 5 layers | Event-driven automation triggers |
Total: 86+ components working in harmony.
┌─────────────────────────────────────────────────────────────────┐
│ bkit Component Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Knowledge Layer │ Skills (18) │ Domain expertise │
│ ───────────────────────────────────────────────────────────── │
│ Execution Layer │ Agents (11) │ Autonomous task work │
│ ───────────────────────────────────────────────────────────── │
│ Interface Layer │ Commands (18) │ User interaction │
│ ───────────────────────────────────────────────────────────── │
│ Automation Layer │ Hooks + Scripts │ Event-driven triggers │
│ ───────────────────────────────────────────────────────────── │
│ Template Layer │ Templates (21) │ Document standards │
│ │
└─────────────────────────────────────────────────────────────────┘
Each layer has a single responsibility, making the system:
- Maintainable: Change one layer without affecting others
- Testable: Verify each component independently
- Extensible: Add new components to any layer
Every major workflow has three coordinated components:
| Workflow | Skill (Knowledge) | Agent (Execution) | Command (Interface) |
|---|---|---|---|
| Beginner Help | starter |
starter-guide |
/init-starter |
| Fullstack Dev | dynamic |
bkend-expert |
/init-dynamic |
| Enterprise | enterprise |
enterprise-expert |
/init-enterprise |
| Gap Analysis | bkit-rules |
gap-detector |
/pdca-analyze |
| QA Testing | zero-script-qa |
qa-monitor |
/zero-script-qa |
| Code Review | phase-8-review |
code-analyzer |
/pdca-iterate |
This triad pattern ensures:
- Consistent UX: Same workflow, different entry points
- Context Sharing: Skill knowledge informs agent behavior
- Flexibility: Users can invoke via command or natural language
bkit implements hooks at 5 different layers:
Layer 1: hooks.json (Plugin-level)
└─ SessionStart → Welcome message + level detection
Layer 2: Skill Frontmatter
└─ PreToolUse → Design doc check before Write/Edit
└─ PostToolUse → Gap analysis suggestion after Write
└─ Stop → Next step guidance
Layer 3: Agent Frontmatter
└─ PreToolUse → Validation before actions
└─ PostToolUse → Result processing
Layer 4: Description Triggers
└─ "Triggers:" keywords for auto-activation
Layer 5: Scripts (18 bash scripts)
└─ Actual logic execution
bkit provides templates for the entire development lifecycle:
PDCA Templates (5):
plan.template.md- Feature planningdesign.template.md- Technical designdesign-starter.template.md- Simplified for beginnersdesign-enterprise.template.md- MSA architectureanalysis.template.md- Gap analysis reportsreport.template.md- Completion reports
Pipeline Phase Templates (10):
- Phase 1-9 templates + Zero Script QA template
Configuration Templates (2):
CLAUDE.template.md- Project instructions_INDEX.template.md- Document index
When you customize bkit, you inherit:
| Benefit | How bkit Provides It |
|---|---|
| Proven Architecture | 86+ components tested together |
| Complete Workflows | PDCA + 9-phase pipeline ready |
| Multilingual Support | 8 languages in trigger keywords |
| Level Adaptation | Auto-adjusts to Starter/Dynamic/Enterprise |
| Documentation Standards | 21 templates for consistency |
| Automation Foundation | 5-layer hook system |
| Metric | bkit Value | Industry Typical |
|---|---|---|
| Component Count | 86+ | 10-20 |
| Hook Layers | 5 | 1-2 |
| Template Coverage | 100% PDCA | Partial |
| Language Support | 8 | 1-2 |
| Project Levels | 3 | 1 |
| Documentation | System architecture docs | README only |
bkit implements a 4-tier language classification system optimized for AI-Native development.
┌─────────────────────────────────────────────────────────────────────────┐
│ TIER 1: AI-Native Essential (Full PDCA Support) │
├─────────────────────────────────────────────────────────────────────────┤
│ Languages: Python, TypeScript, JavaScript │
│ Extensions: .py, .pyx, .pyi, .ts, .tsx, .js, .jsx, .mjs, .cjs │
│ Frameworks: React, Next.js, Svelte, SvelteKit, FastAPI │
│ AI Support: Copilot ✓, Claude ✓, Cursor ✓, Vibe Coding optimized │
├─────────────────────────────────────────────────────────────────────────┤
│ TIER 2: Mainstream Recommended │
├─────────────────────────────────────────────────────────────────────────┤
│ Languages: Go, Rust, Dart │
│ Extensions: .go, .rs, .dart, .astro, .vue, .svelte, .mdx │
│ Frameworks: Vue/Nuxt, Astro, Flutter, Tauri, React Native │
│ AI Support: Good ecosystem support, PDCA recommended │
├─────────────────────────────────────────────────────────────────────────┤
│ TIER 3: Domain Specific │
├─────────────────────────────────────────────────────────────────────────┤
│ Languages: Java, Kotlin, Swift, C, C++ │
│ Extensions: .java, .kt, .swift, .c, .cpp, .h, .sh, .bash │
│ Frameworks: Angular, Electron, Native iOS/Android │
│ AI Support: Platform-specific, moderate AI tool support │
├─────────────────────────────────────────────────────────────────────────┤
│ TIER 4: Legacy/Niche (Migration Recommended) │
├─────────────────────────────────────────────────────────────────────────┤
│ Languages: PHP, Ruby, C#, Scala, Elixir │
│ Extensions: .php, .rb, .cs, .scala, .ex, .exs │
│ AI Support: Limited, migration paths provided │
├─────────────────────────────────────────────────────────────────────────┤
│ EXPERIMENTAL: Future Consideration │
├─────────────────────────────────────────────────────────────────────────┤
│ Languages: Mojo, Zig, V │
│ Status: Monitoring for mainstream adoption │
└─────────────────────────────────────────────────────────────────────────┘
| Project Level | Tier 1 | Tier 2 | Tier 3 | Tier 4 |
|---|---|---|---|---|
| Starter | ✅ Full | ❌ No | ❌ No | |
| Dynamic | ✅ Full | ✅ Yes | ❌ No | |
| Enterprise | ✅ Primary | ✅ System/Cloud | ✅ Native apps |
| Use Case | Recommended | Tier | Notes |
|---|---|---|---|
| Static Site | Next.js / HTML+CSS | 1 | Simplest, AI-native |
| SPA | React + Next.js | 1 | Full ecosystem |
| Content Heavy | Astro | 2 | Optimized for content |
| Enterprise Web | Next.js monorepo | 1 | Scalable, DDD patterns |
| Use Case | Recommended | Tier | Notes |
|---|---|---|---|
| Quick MVP | React Native + Expo | 1 | Fastest to market |
| Cross-platform (6 OS) | Flutter | 2 | Single codebase |
| Native Modules | React Native CLI | 1 | Direct platform access |
| Use Case | Recommended | Tier | Notes |
|---|---|---|---|
| Fullstack BaaS | Next.js + bkend.ai | 1 | Quick prototyping |
| Microservices | Python FastAPI | 1 | Clean architecture |
| System Services | Go / Rust | 2 | K8s native |
| Use Case | Recommended | Tier | Notes |
|---|---|---|---|
| Lightweight (3-5MB) | Tauri | 2 | Rust backend |
| Rich Ecosystem | Electron | 3 | Proven (VS Code, Slack) |
bkit automatically detects language tier via file extensions:
# Detected in lib/common.sh get_language_tier()
Tier 1: .py .pyx .pyi .ts .tsx .js .jsx .mjs .cjs
Tier 2: .go .rs .dart .astro .vue .svelte .mdx
Tier 3: .java .kt .kts .swift .c .cpp .cc .h .hpp .sh .bash
Tier 4: .php .rb .erb .cs .scala .ex .exs| From | To | Strategy |
|---|---|---|
| PHP | TypeScript | Next.js API routes |
| Ruby | Python | FastAPI microservices |
| Java | Kotlin or Go | Gradual module replacement |
| C# | TypeScript or Go | Service-by-service migration |
bkit is designed to support Enterprise-grade systems through AI-Native development, maintenance, operations, and legacy modernization.
AI-Native = Claude Code + PDCA Methodology + 9-Stage Pipeline + Zero Script QA
AI is not just a code generator—it's a development partner that guides the entire software lifecycle.
Build enterprise systems from scratch with AI guidance:
┌─────────────────────────────────────────────────────────────────────────┐
│ Enterprise Development Flow │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: Schema → Domain modeling with AI validation │
│ Phase 2: Convention → Team coding standards (AI-enforced) │
│ Phase 3: Mockup → UI/UX prototypes with AI feedback │
│ Phase 4: API → RESTful design + Zero Script QA │
│ Phase 5: Design System → Platform-agnostic component library │
│ Phase 6: UI Integration→ Frontend-backend connection │
│ Phase 7: SEO/Security → Automated vulnerability scanning │
│ Phase 8: Review → AI-powered code review + gap analysis │
│ Phase 9: Deployment → Infrastructure as Code (Terraform/K8s) │
│ │
│ Each phase runs its own PDCA cycle for continuous improvement │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Refactor existing systems to AI-Native architecture:
┌─────────────────────────────────────────────────────────────────────────┐
│ Legacy Modernization Strategy │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Analysis │
│ └─ code-analyzer agent scans existing codebase │
│ └─ gap-detector identifies design-implementation drift │
│ └─ Language tier assessment (migration priority) │
│ │
│ Step 2: Documentation Recovery │
│ └─ AI generates missing design documents from code │
│ └─ PDCA templates standardize documentation │
│ └─ CLAUDE.md captures institutional knowledge │
│ │
│ Step 3: Incremental Refactoring │
│ └─ pdca-iterator automates improvement cycles │
│ └─ Module-by-module migration (Tier 4 → Tier 1-2) │
│ └─ Zero Script QA validates each change │
│ │
│ Step 4: Architecture Evolution │
│ └─ Monolith → Microservices (enterprise skill guidance) │
│ └─ infra-architect designs K8s/Terraform setup │
│ └─ Clean Architecture (4-layer) implementation │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Maintain and operate enterprise systems with AI assistance:
| Operation | bkit Support |
|---|---|
| Incident Response | qa-monitor agent analyzes logs in real-time |
| Code Review | code-analyzer enforces quality standards |
| Documentation Sync | gap-detector keeps docs and code aligned |
| Knowledge Transfer | CLAUDE.md + PDCA docs preserve context |
| Team Onboarding | Systematic training via /learn-claude-code |
┌─────────────────────────────────────────────────────────────────────────┐
│ Enterprise Reference Architecture │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Frontend (Turborepo Monorepo) │
│ ├─ Next.js 14+ (App Router) │
│ ├─ TypeScript (Tier 1) │
│ ├─ Tailwind CSS + shadcn/ui │
│ ├─ TanStack Query (server state) │
│ └─ Zustand (client state) │
│ │
│ Backend (Microservices) │
│ ├─ Python FastAPI (Tier 1, primary) │
│ ├─ Clean Architecture (4-layer) │
│ │ ├─ API Layer (routers, DTOs) │
│ │ ├─ Application Layer (services, use cases) │
│ │ ├─ Domain Layer (entities, business rules) │
│ │ └─ Infrastructure Layer (repositories, external APIs) │
│ ├─ PostgreSQL (primary database) │
│ ├─ Redis (cache, pub/sub) │
│ └─ RabbitMQ / SQS (messaging) │
│ │
│ Infrastructure │
│ ├─ AWS (EKS, RDS, S3, CloudFront) │
│ ├─ Kubernetes (Kustomize overlays) │
│ ├─ Terraform (Infrastructure as Code) │
│ ├─ ArgoCD (GitOps deployment) │
│ └─ GitHub Actions (CI/CD) │
│ │
└─────────────────────────────────────────────────────────────────────────┘
| Metric | Traditional | AI-Native (bkit) | Improvement |
|---|---|---|---|
| Simple CRUD | 2-3 days | 2-4 hours | 80% faster |
| Medium Feature | 1-2 weeks | 2-3 days | 70% faster |
| Complex Feature | 3-4 weeks | 1-2 weeks | 50% faster |
| Full MVP | 3-6 months | 1-2 months | 60% faster |
| Design-Code Gap | 30-50% | Under 5% | 90% reduction |
| Onboarding Time | 2-4 weeks | Under 1 week | 75% faster |
| Role | Traditional | AI-Native | Change |
|---|---|---|---|
| PM | 1.0 | 0.5 | PDCA auto-tracking |
| Senior Dev | 2.0 | 1.0 | AI guides architecture |
| Junior Dev | 4.0 | 2.0 | 3x productivity with AI |
| QA | 2.0 | 0.5 | Zero Script QA |
| Tech Writer | 1.0 | 0.0 | Auto-generated docs |
| Total | 10 | 4 | 60% reduction |
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ "It's not about reducing developers— │
│ it's about letting developers focus on more valuable work." │
│ │
│ • Repetitive tasks → AI handles │
│ • Creative design → Developers focus │
│ • Documentation, QA → Automated │
│ • Direction & Verification → Human's unique role │
│ │
│ Result: Same team creates 3x more value │
│ │
└─────────────────────────────────────────────────────────────────────────┘
| Reason | Explanation |
|---|---|
| Proven Foundation | 86+ components tested in production |
| Enterprise-Ready | Clean Architecture + Microservices support |
| Future-Proof | AI-Native methodology adapts to new AI capabilities |
| Team Scalable | Works for solo developers and large teams |
| Knowledge Persistent | PDCA docs + CLAUDE.md preserve institutional knowledge |
| Continuous Improvement | Evaluator-Optimizer pattern automates quality |
When you install a Claude Code plugin, components are deployed to the global configuration directory (~/.claude/). To customize these for your specific projects, you can copy and modify them in your project's .claude/ directory.
1. Managed Settings → Enterprise/IT-controlled (highest priority)
2. Command Line Args → Temporary session overrides
3. Project Local → .claude/settings.local.json (personal, gitignored)
4. Project Shared → .claude/settings.json (team-shared)
5. User Global → ~/.claude/settings.json (lowest priority)
Key Insight: Project-level configurations override global configurations with the same name.
| Platform | Path |
|---|---|
| macOS | ~/.claude/ |
| Linux | ~/.claude/ |
| Windows (PowerShell) | %USERPROFILE%\.claude\ or C:\Users\<username>\.claude\ |
| Windows (WSL) | /home/<username>/.claude/ (Linux filesystem, NOT /mnt/c/...) |
| Platform | Path |
|---|---|
| macOS | /Library/Application Support/ClaudeCode/ |
| Linux/WSL | /etc/claude-code/ |
| Windows | C:\Program Files\ClaudeCode\ |
Note: Managed settings require administrator privileges and cannot be overridden by users.
~/.claude/ # Global user configuration
├── settings.json # User settings, permissions, plugins
├── .claude.json # OAuth, MCP servers, preferences
├── CLAUDE.md # Global instructions for all projects
├── agents/ # Global custom subagents
├── skills/ # Global custom skills
├── commands/ # Global custom commands (legacy)
└── plans/ # Plan files storage
.claude/ # Project-level configuration
├── settings.json # Team-shared project settings
├── settings.local.json # Personal project settings (gitignored)
├── CLAUDE.md # Project-level instructions
├── CLAUDE.local.md # Personal project instructions (gitignored)
├── agents/ # Project-specific subagents
├── skills/ # Project-specific skills
└── commands/ # Project-specific commands
A Claude Code plugin like bkit consists of these components:
| Component | Purpose | Location |
|---|---|---|
| Agents | Specialized AI subagents for task delegation | agents/ |
| Skills | Knowledge and instructions Claude follows | skills/<name>/SKILL.md |
| Commands | User-invocable slash commands | commands/ |
| Hooks | Event-triggered scripts/prompts | hooks/ |
| Templates | Document templates for standardization | templates/ |
| Scripts | Helper scripts for automation | scripts/ |
bkit-claude-code/
├── .claude-plugin/
│ ├── plugin.json # Plugin metadata
│ └── marketplace.json # Marketplace registration
├── agents/
│ ├── starter-guide.md # Beginner-friendly agent
│ ├── enterprise-expert.md # Enterprise architecture agent
│ ├── code-analyzer.md # Code review agent
│ └── ...
├── skills/
│ ├── bkit-rules/SKILL.md # Core PDCA rules
│ ├── development-pipeline/SKILL.md
│ └── phase-*/SKILL.md # 9-phase pipeline skills
├── commands/
│ ├── pdca-plan.md # /pdca-plan command
│ ├── pdca-design.md # /pdca-design command
│ └── ...
├── hooks/
│ ├── hooks.json # Hook configuration
│ └── session-start.sh # Session initialization
└── templates/
├── plan.template.md
└── design.template.md
Agents are specialized AI subagents that Claude spawns to delegate specific tasks.
Create a markdown file with YAML frontmatter in agents/ or .claude/agents/:
---
name: your-agent-name
description: |
Brief description of what this agent does.
Use proactively when [trigger conditions].
Triggers: keyword1, keyword2, 한국어, 日本語
Do NOT use for: [exclusion conditions]
permissionMode: acceptEdits # or bypassPermissions, default
model: sonnet # or opus, haiku
tools:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
- WebSearch
skills:
- skill-name # Skills this agent can access
---
# Agent Title
## Role
Describe the agent's primary role and responsibilities.
## Communication Style
Define how the agent should communicate.
## Task Guidelines
Provide specific instructions for handling tasks.| Field | Description |
|---|---|
name |
Unique identifier (kebab-case) |
description |
Multi-line description with triggers and exclusions |
permissionMode |
default, acceptEdits, bypassPermissions |
model |
sonnet (default), opus, haiku |
tools |
List of allowed tools |
skills |
List of skills the agent can reference |
Original bkit agent (agents/starter-guide.md):
---
name: starter-guide
description: |
Friendly guide agent for non-developers and beginners.
...
---Customized for your organization (.claude/agents/onboarding-guide.md):
---
name: onboarding-guide
description: |
ACME Corp onboarding guide for new developers.
Explains company-specific conventions, tools, and workflows.
Use proactively when user mentions "new hire", "onboarding",
"how do we", "company standards", or asks about internal tools.
Triggers: onboarding, new hire, company policy, internal tools
Do NOT use for: general programming questions, external projects
permissionMode: acceptEdits
model: sonnet
tools:
- Read
- Glob
- Grep
- WebFetch
skills:
- company-conventions
- internal-apis
---
# ACME Corp Onboarding Guide
## Role
Help new developers understand ACME Corp's development practices.
## Key Topics
### 1. Repository Structure
- All projects use monorepo structure
- Frontend code lives in `packages/web/`
- Backend code lives in `packages/api/`
### 2. Code Review Process
- All PRs require 2 approvals
- Use conventional commits
- Run `npm run lint` before pushing
### 3. Internal Tools
- Deployment: Use `/deploy staging` or `/deploy production`
- Monitoring: Access Grafana at internal.acme.com/grafanaSkills are knowledge bases that Claude automatically loads when relevant.
skills/
└── your-skill/
├── SKILL.md # Required: Main skill definition
├── reference.md # Optional: Additional documentation
├── examples/ # Optional: Example files
└── scripts/ # Optional: Helper scripts
---
name: your-skill
description: |
What this skill does and when Claude should use it.
Be specific about trigger conditions.
Triggers: keyword1, keyword2
Do NOT use for: exclusion conditions
user-invocable: true # Show in /slash menu
disable-model-invocation: false # Allow Claude to auto-invoke
allowed-tools: Read, Grep, Glob # Restrict available tools
hooks: # Skill-specific hooks
PreToolUse:
- matcher: "Write"
hooks:
- type: command
command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
---
# Skill Content
Detailed instructions Claude follows when this skill is active.| Field | Default | Description |
|---|---|---|
name |
Directory name | Display name and /command |
description |
First paragraph | When to use (Claude reads this) |
user-invocable |
true |
Show in /slash menu |
disable-model-invocation |
false |
Prevent auto-loading |
allowed-tools |
All | Comma-separated tool list |
context |
- | Set to fork for subagent |
agent |
- | Explore, Plan, general-purpose |
model |
- | Override model for this skill |
| Configuration | User Can Invoke | Claude Can Invoke | Use Case |
|---|---|---|---|
| Default | Yes | Yes | Knowledge, guidelines |
disable-model-invocation: true |
Yes | No | Workflows with side effects |
user-invocable: false |
No | Yes | Background context |
Create .claude/skills/company-standards/SKILL.md:
---
name: company-standards
description: |
ACME Corp coding standards and conventions.
Applied automatically when writing or reviewing code.
Triggers: code style, naming convention, lint, formatting
---
# ACME Corp Coding Standards
## Naming Conventions
### Files
- React components: PascalCase (`UserProfile.tsx`)
- Utilities: camelCase (`formatDate.ts`)
- Constants: SCREAMING_SNAKE_CASE in `.constants.ts` files
### Variables
- Boolean: prefix with `is`, `has`, `should`
- Arrays: use plural nouns (`users`, `items`)
- Functions: use verbs (`getUser`, `handleSubmit`)
## Code Structure
### React Components
```tsx
// 1. Imports (external → internal → types → styles)
import React from 'react';
import { useQuery } from '@tanstack/react-query';
import { Button } from '@/components/ui';
import { formatDate } from '@/utils';
import type { User } from '@/types';
import styles from './UserProfile.module.css';
// 2. Types/Interfaces
interface UserProfileProps {
userId: string;
}
// 3. Component
export function UserProfile({ userId }: UserProfileProps) {
// hooks first
// handlers second
// render last
}Always use our custom error classes:
import { ApiError, ValidationError } from '@/errors';
throw new ApiError('User not found', 404);
throw new ValidationError('Invalid email format');Follow Conventional Commits:
<type>(<scope>): <description>
Types: feat, fix, docs, style, refactor, test, chore
Scope: component name or feature area
Example: feat(auth): add OAuth2 login support
---
## 10. Customizing Commands
Commands are user-invoked slash commands (e.g., `/deploy`, `/review`).
### Command File Format
Create `.md` files in `commands/` or `.claude/commands/`:
```markdown
---
description: Short description shown in /slash menu
allowed-tools: ["Read", "Write", "Bash"]
argument-hint: [environment] [options]
---
# Command Instructions
Detailed instructions for Claude when this command is invoked.
## Arguments
- `$ARGUMENTS`: All arguments passed to the command
- `$1`, `$2`: Individual arguments
## Tasks Performed
1. Step one
2. Step two
3. Step three
## Usage Examples
/your-command staging /your-command production --force
Use !`command` syntax to inject dynamic content:
---
description: Create PR with context
allowed-tools: ["Bash"]
---
## Current Context
- Branch: !`git branch --show-current`
- Changes: !`git diff --stat`
- Recent commits: !`git log -3 --oneline`
Create a pull request based on the above context.Create .claude/commands/deploy.md:
---
description: Deploy application to specified environment
allowed-tools: ["Bash", "Read"]
argument-hint: [staging|production]
disable-model-invocation: true
---
# Deployment Command
Deploy the application to the specified environment.
## Environment Validation
Valid environments: `staging`, `production`
If `$ARGUMENTS` is empty or invalid, ask the user to specify.
## Pre-deployment Checks
Before deploying, verify:
1. All tests pass: `npm run test`
2. Build succeeds: `npm run build`
3. No uncommitted changes: `git status`
## Deployment Steps
### For Staging
```bash
npm run deploy:staging# Require explicit confirmation
npm run deploy:production- Verify deployment:
curl https://$ARGUMENTS.acme.com/health - Notify team in Slack (if configured)
- Update deployment log
🚀 Deployment Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Environment: $ARGUMENTS
Version: [version]
Time: [timestamp]
Status: ✅ Success
📋 Checklist:
☑ Tests passed
☑ Build completed
☑ Deployed successfully
☑ Health check passed
🔗 URL: https://$ARGUMENTS.acme.com
---
## 11. Customizing Hooks
Hooks are event-triggered callbacks that run at specific points in Claude's lifecycle.
### Hook Events
| Event | When It Fires |
|-------|---------------|
| `PreToolUse` | Before a tool is called |
| `PostToolUse` | After a tool completes |
| `Stop` | When Claude finishes responding |
| `SubagentStop` | When a subagent completes |
| `SessionStart` | When a new session begins |
| `SessionEnd` | When a session ends |
| `UserPromptSubmit` | Before user prompt is processed |
| `PreCompact` | Before context compaction |
| `Notification` | When a notification is shown |
### hooks.json Format
Create `hooks/hooks.json`:
```json
{
"$schema": "https://json.schemastore.org/claude-code-hooks.json",
"SessionStart": [
{
"once": true,
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
"timeout": 5000
}
]
}
],
"PreToolUse": {
"Bash": {
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate-bash.sh"
}
]
},
"Write": {
"hooks": [
{
"type": "prompt",
"prompt": "Before writing, verify the file follows our coding standards."
}
]
}
},
"PostToolUse": {
"Write": {
"hooks": [
{
"type": "command",
"command": "npm run lint:fix -- $TOOL_INPUT_PATH"
}
]
}
}
}
Execute shell commands:
{
"type": "command",
"command": "/path/to/script.sh",
"timeout": 5000
}Inject instructions into Claude's context:
{
"type": "prompt",
"prompt": "Remember to follow our security guidelines when handling user data."
}| Variable | Description |
|---|---|
${CLAUDE_PLUGIN_ROOT} |
Plugin installation directory |
$TOOL_INPUT |
Input passed to the tool |
$TOOL_INPUT_PATH |
File path (for file operations) |
$TOOL_OUTPUT |
Output from the tool (PostToolUse) |
$CLAUDE_SESSION_ID |
Current session ID |
$CLAUDE_ENV_FILE |
File for persisting environment variables |
Create .claude/hooks/hooks.json:
{
"PreToolUse": {
"Bash(git commit:*)": {
"hooks": [
{
"type": "command",
"command": ".claude/hooks/pre-commit.sh"
}
]
}
},
"PostToolUse": {
"Write": {
"hooks": [
{
"type": "command",
"command": "npx prettier --write $TOOL_INPUT_PATH 2>/dev/null || true"
}
]
}
}
}Create .claude/hooks/pre-commit.sh:
#!/bin/bash
# Validate before committing
echo "Running pre-commit checks..."
# Check for sensitive data
if grep -r "API_KEY\|SECRET\|PASSWORD" --include="*.ts" --include="*.js" src/; then
cat << 'JSON'
{
"decision": "block",
"reason": "Potential sensitive data detected. Please review before committing."
}
JSON
exit 0
fi
# Check for console.log
if grep -r "console\.log" --include="*.ts" --include="*.tsx" src/; then
cat << 'JSON'
{
"decision": "block",
"reason": "console.log statements found. Remove before committing."
}
JSON
exit 0
fi
# All checks passed
cat << 'JSON'
{
"decision": "allow"
}
JSONTemplates standardize document creation across your organization.
templates/
├── plan.template.md
├── design.template.md
├── analysis.template.md
└── report.template.md
| Variable | Description |
|---|---|
{feature} |
Feature name from arguments |
{date} |
Current date |
{author} |
Author name |
{project} |
Project name |
Create templates/feature-spec.template.md:
# Feature Specification: {feature}
**Author**: {author}
**Date**: {date}
**Status**: Draft
---
## 1. Overview
### 1.1 Problem Statement
<!-- What problem does this feature solve? -->
### 1.2 Proposed Solution
<!-- High-level description of the solution -->
### 1.3 Success Criteria
<!-- How do we measure success? -->
---
## 2. Requirements
### 2.1 Functional Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-001 | | High |
| FR-002 | | Medium |
### 2.2 Non-Functional Requirements
| ID | Requirement | Target |
|----|-------------|--------|
| NFR-001 | Performance | < 200ms response |
| NFR-002 | Availability | 99.9% uptime |
---
## 3. Technical Design
### 3.1 Architecture
<!-- Describe the architecture -->
### 3.2 API Design
<!-- API endpoints, request/response formats -->
### 3.3 Data Model
<!-- Database schema, data structures -->
---
## 4. Implementation Plan
### 4.1 Phases
| Phase | Description | Duration |
|-------|-------------|----------|
| 1 | | |
| 2 | | |
### 4.2 Dependencies
<!-- External dependencies, blockers -->
---
## 5. Risks & Mitigations
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| | High | Medium | |
---
## Appendix
### A. References
<!-- Links to related documents -->
### B. Glossary
<!-- Technical terms and definitions --># Create your organization's plugin directory
mkdir -p my-org-plugin/{agents,skills,commands,hooks,templates,scripts}
cd my-org-plugin
# Initialize plugin.json
cat > .claude-plugin/plugin.json << 'EOF'
{
"name": "my-org-kit",
"version": "1.0.0",
"description": "My Organization's Claude Code Plugin",
"author": {
"name": "My Organization",
"email": "dev@myorg.com"
}
}
EOF# Copy bkit components you want to customize
cp -r ~/.claude/plugins/bkit/agents/starter-guide.md agents/team-guide.md
cp -r ~/.claude/plugins/bkit/skills/bkit-rules skills/org-rules
# Edit to match your organization's needsagents/team-lead.md:
---
name: team-lead
description: |
Senior developer guidance for architecture decisions.
Use when discussing system design, code reviews, or mentoring.
permissionMode: acceptEdits
model: opus
tools: [Read, Grep, Glob, WebSearch]
---
# Team Lead Agent
## Role
Provide senior-level guidance on architecture and best practices.
## Responsibilities
1. Review architectural decisions
2. Suggest design patterns
3. Identify potential issues early
4. Mentor on best practices{
"SessionStart": [
{
"once": true,
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/init.sh"
}
]
}
],
"PreToolUse": {
"Write(src/**/*.ts)": {
"hooks": [
{
"type": "prompt",
"prompt": "Ensure TypeScript strict mode compliance."
}
]
}
}
}In your project's .claude/settings.json:
{
"extraKnownMarketplaces": {
"my-org": {
"source": {
"source": "github",
"repo": "my-org/claude-plugins"
}
}
},
"enabledPlugins": {
"my-org-kit@my-org": true
}
}For organization-wide deployment, IT administrators can use managed settings:
macOS: /Library/Application Support/ClaudeCode/managed-settings.json
Linux: /etc/claude-code/managed-settings.json
Windows: C:\Program Files\ClaudeCode\managed-settings.json
{
"strictKnownMarketplaces": ["my-org"],
"enabledPlugins": {
"my-org-kit@my-org": true
},
"extraKnownMarketplaces": {
"my-org": {
"source": {
"source": "github",
"repo": "my-org/claude-plugins"
}
}
}
}- Single Responsibility: Each agent should have one clear purpose
- Clear Triggers: Define explicit trigger conditions in descriptions
- Tool Restrictions: Only include tools the agent actually needs
- Multilingual Support: Include trigger keywords in multiple languages
- Keep SKILL.md Under 500 Lines: Use supporting files for details
- Specific Descriptions: Help Claude understand when to apply
- Use Hooks Sparingly: Only for critical validation/enforcement
- Clear Naming: Use verbs (
deploy,review,create) - Argument Hints: Provide helpful autocomplete hints
- Safe Defaults: Require confirmation for destructive operations
- Informative Output: Show clear success/failure feedback
- Fast Execution: Keep hooks under 5 seconds
- Silent Success: Only output on failure/warning
- Graceful Degradation: Don't block if hook fails unexpectedly
- Never Commit Secrets: Use environment variables
- Validate External Input: Sanitize command arguments
- Restrict Permissions: Use minimal required tool access
- Audit Hooks: Review all hook scripts for security
| Component | Global | Project |
|---|---|---|
| Settings | ~/.claude/settings.json |
.claude/settings.json |
| Instructions | ~/.claude/CLAUDE.md |
CLAUDE.md or .claude/CLAUDE.md |
| Agents | ~/.claude/agents/ |
.claude/agents/ |
| Skills | ~/.claude/skills/ |
.claude/skills/ |
| Commands | ~/.claude/commands/ |
.claude/commands/ |
| Hooks | Via plugins | .claude/hooks/hooks.json |
# Access global settings
Get-Content "$env:USERPROFILE\.claude\settings.json"
# Create project config
New-Item -ItemType Directory -Path ".claude\agents" -Force
New-Item -ItemType Directory -Path ".claude\skills" -Force# List available skills
claude /skills
# Check context usage
claude /context
# View installed plugins
claude /plugins
# Debug hooks
CLAUDE_CODE_DEBUG=hooks claude- Claude Code Official Documentation
- Claude Code Skills Guide
- Agent Skills Open Standard
- bkit GitHub Repository
bkit is licensed under the Apache License 2.0. This means you can:
- Use bkit freely in personal and commercial projects
- Modify bkit to fit your organization's needs
- Distribute your customized versions
- Sublicense derivative works under different terms
When creating derivative works based on bkit, you must:
- Include the original LICENSE file or reference to Apache 2.0
- Include the NOTICE file with original attribution
- Mark modified files with prominent notices stating you changed them
- Retain copyright notices from the original source
When redistributing bkit or derivative works, include:
bkit - Vibecoding Kit
Copyright 2024-2026 POPUP STUDIO PTE. LTD.
This product includes software developed by POPUP STUDIO PTE. LTD.
https://github.com/popup-studio-ai/bkit-claude-code
Licensed under the Apache License, Version 2.0
If you create a plugin based on bkit (e.g., "acme-dev-kit"), add to your plugin.json:
{
"name": "acme-dev-kit",
"version": "1.0.0",
"description": "ACME Corp's development kit based on bkit",
"author": {
"name": "ACME Corporation",
"email": "dev@acme.com"
},
"license": "Apache-2.0",
"attribution": {
"basedOn": "bkit Vibecoding Kit",
"originalAuthor": "POPUP STUDIO PTE. LTD.",
"originalRepository": "https://github.com/popup-studio-ai/bkit-claude-code"
}
}And include a NOTICE file in your plugin root:
ACME Dev Kit
Copyright 2026 ACME Corporation
This product is based on bkit Vibecoding Kit.
Original work Copyright 2024-2026 POPUP STUDIO PTE. LTD.
https://github.com/popup-studio-ai/bkit-claude-code
Licensed under the Apache License, Version 2.0
http://www.apache.org/licenses/LICENSE-2.0
- You don't need to open-source your modifications
- You don't need to use the same license for your additions
- You don't need permission to use bkit commercially
For full license terms, see the LICENSE file.
- Claude Code Official Documentation
- Claude Code Skills Guide
- Agent Skills Open Standard
- bkit GitHub Repository
This guide is part of the bkit Vibecoding Kit. For questions or contributions, visit our GitHub repository.