npm package: @khanhcan148/mk
Description: CLI to install and manage MyClaudeKit (.claude/) in your projects
Author: khanhcan148
Latest version: 0.1.16

# Claude Code Skills, Agents & Workflows

[![npm](https://img.shields.io/npm/v/@khanhcan148/mk)](https://www.npmjs.com/package/@khanhcan148/mk)

**Built by** TRAN Le Khanh (khanhcan148@gmail.com) — developer and AI tooling author.

Modular packages that extend Claude Code with specialized knowledge, workflows, and tool integrations.

**Quick Navigation:** [Quick Reference](docs/quick-reference.md) | [Common Workflows](docs/common-workflows.md) | [Skill Index](docs/skill-index.md)


## Quick Start

### CLI Installation (Recommended)

```bash
# Install globally (npm registry)
npm install -g @khanhcan148/mk

# Install kit to current project (./.claude/)
mk init

# Install kit globally (~/.claude/ — available in all projects)
mk init --global

# Preview what would be installed without writing files
mk init --dry-run
```

**Note**: This package has limited access. Email khanhcan148@gmail.com for an invitation to access the npm package and repository.

### CLI Commands

```
mk init              Install kit files to current project (./.claude/)
mk init --global     Install kit globally (~/.claude/)
mk init --dry-run    Preview what would be installed
mk update            Update kit files (preserves your edits by default)
mk update --force    Update and overwrite user-modified files
mk remove            Remove all kit files tracked by manifest
mk --version         Show installed CLI version
mk --help            Show help
```

### Manual Installation (Alternative)

**For contributors with repository access**:

```bash
# Clone the repository (requires access to private repo)
git clone https://github.com/khanhtran148/mk-kit.git
cd mk-kit
```

**Project-level usage** (skills available in one project):
```bash
cp -r .claude /path/to/your/project/
```

**Global-level usage** (skills available across all projects):
```bash
cp -r .claude ~/.claude/
```

### Usage

```bash
# Use a workflow command
/mk-init           # Bootstrap new project
/mk-brainstorm     # Explore options, debate trade-offs; pass Jira/AzDO URL to fetch ticket context first
/mk-plan           # Create implementation plan
/mk-implement      # End-to-end feature delivery
/mk-test           # Run tests and validate
/mk-review         # Code quality review
/mk-debug          # Debug issues
/mk-security       # Security scan and audit
/mk-db             # Database operations
/mk-docs           # Generate documentation
/mk-overview       # Multi-tier stakeholder overview (Executive, Product, Technical)
/mk-git            # Git operations
/mk-audit          # Code archaeology chain: orientation, testing, heatmap, breaking-change analysis, technical debt, domain extraction
/mk-selftest       # Self-validation checks on kit agents, skills, docs, workflows
/mk-log-analysis   # Datadog + Azure App Insights log analysis with severity triage and Mermaid visual reports
```

## Structure

```
├── .claude/
│   ├── agents/      # 32 agents (5 primary + 27 utility: implementers, quality, docs, specialized, concerns)
│   ├── skills/      # 66 skill packages (SKILL.md + scripts/references/assets)
│   │   ├── mk-*/    # 19 workflow commands (/mk-audit, /mk-brainstorm, /mk-log-analysis, /mk-overview, /mk-selftest, etc.)
│   │   └── ...      # Domain skills (frontend, backend, testing, browser automation, etc.)
│   └── workflows/   # Development protocols
├── bin/             # CLI entry point (mk command)
├── src/             # CLI source code
├── docs/            # Project documentation
│   └── plans/       # Implementation plans (created during development)
├── package.json     # npm package metadata
├── CLAUDE.md        # Claude Code guidance
└── README.md        # This file
```

## Primary Workflow

Orchestration is handled by `/mk-*` skills which spawn utility agents as needed. See [Common Workflows](docs/common-workflows.md) for practical examples.

**Architecture:**

```
User → /mk-* command (skill) → spawns utility agents → agents use knowledge skills
```

**Sequential chaining:**
```
/mk-plan → /mk-implement → /mk-test → /mk-review
```

**Entry point commands:**

| Command | Purpose |
|---------|---------|
| `/mk-init` | Full project bootstrap from conception to deployment; includes brownfield detection (Phase 0 gate) and adoption workflow (B1-B4.5 stages); generates AGENTS.md template (or migrates existing tool configs); suggests /mk-audit as next step for brownfield projects |
| `/mk-brainstorm` | Ideation, requirements exploration, structured debate (analyzer opus agent); pass a Jira or AzDO URL to fetch ticket hierarchy first (Phase 0.5) |
| `/mk-audit` | Code archaeology chain: orientation report, characterization testing, topology heatmap, breaking-change analysis, technical debt dashboard, domain extraction; enriches CLAUDE.md and AGENTS.md with auto-generated architecture and debt sections |
| `/mk-plan` | Create implementation plans with phases and tasks (opus) |
| `/mk-design` | UI/UX wireframes, design systems, mockups |
| `/mk-implement` | End-to-end feature delivery (sonnet) |
| `/mk-test` | Run tests, analyze coverage, validate builds |
| `/mk-review` | Code review for quality, security, performance |
| `/mk-debug` | Debugging workflow: investigate, diagnose, fix, verify; always offers incident journal documentation with severity hints |
| `/mk-security` | Security-first workflow: dependency scan, secrets detection |
| `/mk-db` | Database operations: diagnose, optimize, design, migrate |
| `/mk-docs` | Generate and update project documentation; maintains AGENTS.md; Impact Areas analysis produces human-readable "What changed / Who is affected / What could go wrong" narrative |
| `/mk-git` | Git operations: branch, commit, push, PR, merge |
| `/mk-research` | Deep multi-source research on technical topics |
| `/mk-spike` | Investigate external service integrations: fetch API docs, evaluate options, produce <service-slug>-spike.md with Go/No-Go |
| `/mk-overview` | Synthesize project artifacts into multi-tier stakeholder overview: Executive Brief, Product Report, Technical Report |
| `/mk-workflow` | Trace REST endpoint call chains with upstream caller detection, variant branching, side effects/feature flags, Mermaid diagrams |
| `/mk-log-analysis` | Analyze production logs from Datadog or Azure Application Insights via MCP; progressive severity triage, pattern detection, mandatory stack trace investigation, mk-debug integration |
| `/mk-selftest` | Run self-validation checks on kit agents, skills, docs, and workflows |

## Primary Agents

Invoked directly via `/mk-*` skills:

| Agent | Purpose | Model |
|-------|---------|-------|
| **analyzer** | Deep research, decision matrix, architecture diagrams, adversarial debate (Phases 5-8 of /mk-brainstorm) | opus |
| **planner** | Implementation planning with phases, tasks, dependencies | opus |
| **implementer** | End-to-end feature implementation | sonnet |
| **database-admin** | Database operations: diagnose, optimize, design, migrate | sonnet |
| **git-manager** | Git operations: commit, push, PR, merge | sonnet |

## Utility Agents

Spawned by primary agents for domain-specific work:

**Implementation & Quality (9)**
| Agent | Purpose |
|-------|---------|
| **backend-implementer** | API and domain logic implementation |
| **frontend-implementer** | UI components, consuming API contract |
| **mobile-implementer** | Mobile app implementation (Flutter, React Native, Swift, Kotlin) with TFD |
| **tester** | Test execution and validation |
| **debugger** | Issue investigation and diagnosis |
| **refactorer** | Refactoring with TFD-first safety workflow |

**Docs & Project Management (4)**
| Agent | Purpose |
|-------|---------|
| **project-manager** | Progress tracking, roadmap updates |
| **docs-manager** | Documentation maintenance |
| **journal-writer** | Technical difficulty documentation |
| **wiki-maintainer** | Background wiki writes to docs/llm-wiki/ (spawned by mk-* skills) |

**Research & Design (3)**
| Agent | Purpose |
|-------|---------|
| **researcher** | Technical research |
| **ui-ux-designer** | Frontend design |
| **copywriter** | Marketing copy and content |

**Utilities & Search (2)**
| Agent | Purpose |
|-------|---------|
| **scout** | Codebase file search (internal) |
| **scout-external** | Codebase search via external tools |
| **mcp-manager** | MCP server integrations |

**Parallel Concern Review Agents (11)**
| Agent | Purpose |
|-------|---------|
| **quality-reviewer** | Code quality, readability, maintainability (mk-review concern) |
| **security-reviewer** | Security vulnerabilities, threat analysis (mk-review concern) |
| **performance-reviewer** | Performance profiling, optimization opportunities (mk-review concern) |
| **tfd-reviewer** | Test-first development verification (mk-review concern) |
| **dep-scanner** | Dependency vulnerability scanning (mk-security concern) |
| **secret-scanner** | Secrets and credential detection (mk-security concern) |
| **code-security-reviewer** | Code-level security analysis (mk-security concern) |
| **infra-reviewer** | Infrastructure security review (mk-security concern) |
| **log-analyzer** | Log analysis and diagnostics (mk-debug concern) |
| **hypothesis-generator** | Root cause hypothesis generation (mk-debug concern) |
| **log-collector** | External observability platform queries — Datadog and Azure App Insights MCP (mk-log-analysis concern) |

[Full agent details →](.claude/agents/README.md)

## Skills

See [Skill Index](docs/skill-index.md) for a complete categorized list of all skills.

Each skill contains:
- `SKILL.md` (required) - Instructions (≤250 lines)
- `scripts/` (optional) - Executable code with tests
- `references/` (optional) - Documentation chunks
- `assets/` (optional) - Templates, images

```bash
# Create new skill
python .claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>
```

## Documentation

| Document | Description |
|----------|-------------|
| [Skill Index](docs/skill-index.md) | Categorized list of all skills and workflows |
| [mk-* Workflows & Agents](docs/mk-workflow-agents.md) | How each /mk-* command works and which agents it uses |
| [Project Overview & PDR](docs/project-overview-pdr.md) | Requirements, constraints, success metrics |
| [Project Roadmap](docs/project-roadmap.md) | Phases, milestones, and risk register |
| [Changelog](docs/changelog.md) | Version history and release notes |
| [Code Standards](docs/code-standards.md) | Conventions, naming, quality gates |
| [System Architecture](docs/system-architecture.md) | Component diagrams, data flow |
| [Product Domain Glossary](docs/product-domain-glossary.md) | Core domain concepts, terminology, and ecosystem definitions |
| [Quick Reference](docs/quick-reference.md) | Common commands and quick lookup |
| [Common Workflows](docs/common-workflows.md) | Practical workflow examples |

## Core Principles

- **YAGNI** - Don't add functionality until necessary
- **KISS** - Prefer simple solutions
- **DRY** - Extract common patterns
- **SOLID** - For OOP/enterprise projects

## Key Constraints

- SKILL.md must be ≤250 lines
- Reference files in `references/` have no line limit; loaded on-demand
- Scripts must include tests
- **Cross-platform compatibility (Windows + macOS/Linux) is mandatory**: Scripts use Python or Node.js only — no bash/shell scripts
- Token efficiency - minimize context usage

## Cross-Platform Compatibility

This kit is designed to work on Windows, macOS, and Linux:

- **Scripts**: All executable scripts use Python or Node.js (no bash/shell scripts)
- **Claude Code Bash tool**: Provides a Unix-like shell on all platforms, including Windows — git commands and other Bash tool invocations work everywhere
- **External tool installs**: Reference files include install instructions for macOS (`brew`), Ubuntu/Debian (`apt-get`), and Windows (`winget`/`choco`) where applicable
**Supported runtime**: Claude Code CLI. All skills, agents, and workflows are designed for the Claude Code runtime.