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

# AGENTS.md — My Agent Kit

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

Compatible with: Claude Code, Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI.

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              ← Claude Code instructions (kit-level)
├── AGENTS.md              ← This file — universal instructions
├── 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          ← For target projects (Claude Code)
│   └── AGENTS.md          ← For target projects (universal)
├── claude/                ← CANONICAL kit content (source of truth)
│   ├── settings.json
│   ├── metadata.json      ← Version + deletions list
│   ├── statusline.cjs
│   ├── .mk.json, .mkignore
│   ├── agents/            ← 14 agent definitions
│   ├── rules/             ← 7 workflow rule files
│   ├── skills/            ← 90+ domain knowledge packs
│   ├── hooks/             ← 20+ event-driven hooks
│   ├── schemas/, scripts/, output-styles/, command-archive/
├── docs/                  ← Documentation templates
└── plans/                 ← Plan templates + reports
```

### Two folders, one purpose

- **`claude/`** in this repo is the **canonical source** — edit files here.
- **`.claude/`** is what `mk-init.sh` creates inside a target project. 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
- **Skills format:** folder with `SKILL.md` (YAML frontmatter)
- **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
- **Config:** `.mk.json` for kit settings
- **Identity policy:** Never introduce `claudekit`, `ck:`, or related markers

### When editing the kit

- Test hooks: check `claude/settings.json` references match actual paths
- 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/` in sync with kit capabilities

---

## Role 2: Installation Assistant

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

### Quick install

```bash
# Basic install (Claude Code only)
./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 deleted files first)
./mk-init.sh /path/to/project --upgrade --force

# With 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` + `.agents/skills/` symlink | OpenAI Codex CLI |
| `--all` | All of the above | All tools |
| `--upgrade` | Drops deleted paths from `metadata.json` before copy | Clean migration |

### Post-install checklist

1. **Customize CLAUDE.md** in the target project — add tech stack, conventions, deploy target
2. **Optional:** Run `.claude/skills/install.sh` for Python skill dependencies
3. **Optional:** Set `GEMINI_API_KEY` in `.claude/.env` for AI image skills
4. **Optional:** Remove unused skills (shopify, threejs, shader, remotion, etc.)
5. **Start:** run `claude` or `codex` in the target project

### Key commands to teach users

| Command | What it does |
|---|---|
| `/mk:cook "feature X"` | Full workflow: plan → code → test → review |
| `/mk:fix "bug Y"` | Diagnose + fix (v2.0 structured diagnosis pipeline) |
| `/mk:test` | Run tests + coverage |
| `/mk:code-review` | Review current code |
| `/mk:ship` | Full pipeline to production |
| `/mk:plan "task"` | Create scoped implementation plan |
| `/mk:autoresearch` | Autonomous research loop |
| `/mk:docs init` | Generate project documentation |
| `/mk:show-off` | Showcase / demo presentation |
| `/mk:xia` | Repo-porting / repo-analysis |
| `/mk:graphify` | Generate knowledge graph |

### Troubleshooting

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

---

## Cross-Tool Compatibility

This kit is designed Claude Code-first, but supports other tools:

| Tool | Reads | Agent system | Skills | Hooks |
|---|---|---|---|---|
| **Claude Code** | `CLAUDE.md` + `.claude/` | Full (14 agents) | Full (90+) | Full (20+) |
| **Codex CLI** | `AGENTS.md` + `.codex/` | Own system | `.agents/skills/` symlink | Own `hooks.json` |
| **Copilot** | `AGENTS.md` + `.github/` + `.claude/skills/` | `.github/agents/` | Reads `.claude/skills/` | `.github/hooks/` |
| **Cursor** | `AGENTS.md` | Limited | No | No |
| **Windsurf** | `AGENTS.md` | Limited | No | No |

`AGENTS.md` is the universal baseline read by 8+ tools. `.claude/` provides deep features for Claude Code and partial support for Copilot.

---

## Identity Policy

All original source identity markers have been stripped. Namespace: `mk:` / `MK` / `my-kit`. Do not reference the original source.

## Language

- Code, configs, file names: English
- User-facing docs: English
- Internal learning notes (if any): Vietnamese
