<div align="center">
  <img src="assets/logos/logo-stack-monochrome.svg" alt="My Agent Kit Logo" width="80" />
</div>

# CLAUDE.md — My Agent Kit

You are working inside the **my-agent-kit** repository — a personal Claude Code agent kit with 14 agents, 90+ skills, 20+ hooks, and structured workflows.

You have two roles depending on what the user asks:

---

## Role 1: Kit Developer & Maintainer

When the user asks to modify, improve, debug, or extend the kit itself.

### Repository structure

```
my-agent-kit/
├── CLAUDE.md              ← This file (kit-level instructions for Claude Code)
├── AGENTS.md              ← Universal version (Codex, Copilot, Cursor, etc.)
├── README.md              ← User-facing documentation
├── CHANGELOG.md           ← Release notes
├── mk-init.sh             ← Installer script
├── package.json           ← npm distribution config
├── templates/             ← Files copied to target projects on install
│   ├── CLAUDE.md          ← Claude Code instructions for target projects
│   └── AGENTS.md          ← Universal instructions for target projects
├── claude/                ← CANONICAL kit content (source of truth)
│   ├── settings.json      ← Hook configuration
│   ├── metadata.json      ← Version + deletions list (for clean upgrades)
│   ├── statusline.cjs     ← Statusline renderer
│   ├── .mk.json           ← Kit config (plan naming, locale, paths)
│   ├── .mkignore          ← Block AI access to dirs/files
│   ├── agents/            ← 14 agent definitions
│   ├── rules/             ← 7 workflow rule files
│   ├── skills/            ← 90+ domain knowledge packs
│   ├── hooks/             ← 20+ event-driven hooks
│   ├── schemas/           ← JSON schemas (.mk.json, skill-schema)
│   ├── scripts/           ← Utility scripts
│   ├── output-styles/     ← Output style templates
│   └── command-archive/   ← Archived command definitions
├── docs/                  ← Documentation templates
└── plans/                 ← Plan templates + reports
```

### Two folders, one purpose

- **`claude/`** in this repo is the **canonical source** of the kit content. Edit files here.
- **`.claude/`** is what `mk-init.sh` creates inside a target project (Claude Code reads `.claude/` natively). It does not exist in this repo.

When a user installs the kit, `mk-init.sh` copies `claude/* → <target>/.claude/*`.

### Development rules

- **File naming:** kebab-case, descriptive (agents read names to infer purpose)
- **Skills format:** folder with `SKILL.md` (YAML frontmatter: name, description, argument-hint)
- **Agents format:** markdown with YAML frontmatter (model, tools, description)
- **Hooks format:** `.cjs` scripts, registered in `claude/settings.json`
- **Namespace:** `mk:` prefix for kit-specific slash commands (`mk:plan`, `mk:debug`, `mk:autoresearch`...)
- **Config:** `.mk.json` for kit settings, `hooks/lib/mk-config-utils.cjs` for loading
- **Identity policy:** No traces of upstream identity. Never introduce `claudekit`, `ck:`, or related markers — even by accident from upstream merges.

### When editing the kit

- Test hooks: check `claude/settings.json` references match actual file paths under `claude/hooks/`
- Test skills: verify `SKILL.md` frontmatter is valid YAML, name matches folder
- Test agents: verify `tools` list contains valid tool names
- After modifying `mk-init.sh`, run `./mk-init.sh --dry-run /tmp/test-target` first
- Keep `templates/CLAUDE.md` and `templates/AGENTS.md` in sync with kit capabilities
- After upstream syncs, ALWAYS strip identity markers — see `claude/skills/strip-identity/` for the procedure

### Upstream sync workflow

When pulling updates from the original upstream kit:

1. Backup current `claude/`
2. Bulk-copy upstream content into `claude/`
3. Rename folders/files: `ck-* → mk-*`, `.ck.json → .mk.json`, `.ckignore → .mkignore`
4. Run `claude/skills/strip-identity/scripts/strip.sh` (or equivalent) to substitute identity markers in file contents
5. Verify: `grep -rln 'claudekit\|goonnguyen\|mrgoonie\|ClaudeKit\|CLAUDEKIT\|/ck:\|ck-config' claude/` must return zero
6. Bump version in `package.json` + `claude/metadata.json`
7. Document changes in `CHANGELOG.md`

---

## Role 2: Installation Assistant

When the user asks to install, set up, or configure the kit for another project.

### Quick install

```bash
# One-command (npm)
npx my-agent-kit init

# Or from this repo
./mk-init.sh /path/to/project

# Cross-tool support
./mk-init.sh /path/to/project --all

# Preview first
./mk-init.sh /path/to/project --dry-run

# Reinstall / overwrite
./mk-init.sh /path/to/project --force

# Clean upgrade (drops files listed in metadata.json deletions before copy)
./mk-init.sh /path/to/project --upgrade --force

# Install + Python skill dependencies
./mk-init.sh /path/to/project --skills-install
```

### What gets installed

| Option | Creates | For |
|---|---|---|
| (default) | `.claude/`, `CLAUDE.md`, `AGENTS.md`, `plans/` | Claude Code |
| `--copilot` | + `.github/copilot-instructions.md` | GitHub Copilot |
| `--codex` | + `.codex/config.toml` + `.codex/hooks.json` + `.agents/skills/` symlink | OpenAI Codex CLI |
| `--all` | All of the above | All tools |
| `--upgrade` | Drops paths from `claude/metadata.json` deletions before copy | Clean migration from older installs |

### Post-install guidance for the user

1. **Customize `CLAUDE.md`** at project root — add stack, conventions, deploy target
2. **Optional:** Run `.claude/skills/install.sh` for Python skill dependencies (image/multimodal skills)
3. **Optional:** Set `GEMINI_API_KEY` in `.claude/.env` for AI image skills
4. **Optional:** Remove unused skills (e.g. `shopify`, `threejs`, `shader`, `remotion`)
5. **Start:** `cd project && claude`

### Key commands

| Command | What it does |
|---|---|
| `/mk:cook "feature X"` | Full workflow: plan → code → test → review |
| `/mk:fix "bug Y"` | Diagnose + fix with root cause analysis (v2.0 structured diagnosis) |
| `/mk:test` | Run tests + coverage |
| `/mk:code-review` | Review current code |
| `/mk:ship` | Full pipeline: test → review → commit → push → PR |
| `/mk:plan "task"` | Create scoped implementation plan with verification roles |
| `/mk:autoresearch` | Autonomous research loop (formerly `mk:loop`) |
| `/mk:docs init` | Scan codebase, generate `docs/` |
| `/mk:show-off` | Showcase / demo presentation |
| `/mk:xia` | Repo-porting / repo-analysis |
| `/mk:graphify` | Generate knowledge graph |
| `/mk:excalidraw` | Generate Excalidraw diagrams |

### Troubleshooting

| Problem | Solution |
|---|---|
| AI ignores rules | Check `CLAUDE.md` references `.claude/rules/` correctly |
| Hook not running | Check `.claude/settings.json` script paths exist |
| Skill not found | Check `SKILL.md` has valid YAML frontmatter |
| Agent spawn fails | Check `tools` list in agent definition |
| Python skill error | Run `.claude/skills/install.sh`, verify `.venv/` exists |
| Old files lingering after upgrade | Re-run with `./mk-init.sh . --upgrade --force` |

---

## Identity policy

This kit was extracted from an external source. **All identity markers have been stripped.** The namespace is `mk:` / `MK` / `my-kit`. When merging upstream updates, always re-run the identity stripping process — see Role 1 → "Upstream sync workflow".

## Language

- Code, configs, file names: English
- User-facing docs (`README.md`, `docs/`): English
- Internal learning notes (if any): Vietnamese
