claude: Instructions file for Claude Code

CLAUDE.md — Claude Toolkit

Project Overview

A complete Claude Code toolkit: skills, agents and commands in one repo (nasrulhazim/claude). Skills are self-contained directories under skills/ with a SKILL.md and optional references/ folder; agents are single-file role personas under agents/; commands are single-file slash commands under commands/.

Stack

• Format: Markdown with YAML frontmatter (SKILL.md, agents; frontmatter optional for commands)
• Target: Claude Code (installer + plugin marketplace) / Laravel Cloud Skills
• Baseline: Kickoff.my stack (Livewire 4, Pest, PHPStan, Rector, Pint, GitHub Actions)

Architecture

.claude-plugin/               # plugin.json + marketplace.json (single plugin, source "./")
templates/                    # managed blocks appended to ~/.claude/CLAUDE.md by install.sh
skills/
├── [skill-name]/
│   ├── SKILL.md              # YAML frontmatter + markdown instructions
│   └── references/           # Templates, patterns, examples (pure markdown, no frontmatter)
agents/[agent-name].md        # Role personas that load skills as their playbook
commands/[command-name].md    # Slash commands (subdirs allowed for namespacing)
install.sh                    # Installs all three types to ~/.claude/{skills,agents,commands}
generate-manifest.sh          # Regenerates manifest.txt (type-prefixed entries)
migrations.txt                # Rename/removal mappings (legacy skill format + type-prefixed)

DO / DON'T

• ✅ DO include metadata: with compatible_agents and tags in every SKILL.md frontmatter
• ✅ DO include trigger phrases in both English and Bahasa Malaysia
• ✅ DO use description: > (multiline YAML) for the skill description field
• ✅ DO add a ## Reference Files table at the end of every SKILL.md — it is always the last section
• ✅ DO end every high-stakes skill with ## Common Rationalizations (excuse → reality table), ## Red Flags and ## Verification (checkbox gate), placed immediately before ## Reference Files
• ✅ DO keep reference files as pure markdown (no YAML frontmatter)
• ✅ DO keep agents thin (25–75 lines): role persona + "load these skills" + rules — knowledge lives in skills
• ✅ DO write agent descriptions in third person, trigger-oriented ("Use this agent when/for …")
• ❌ DON'T use frontmatter in reference files — only in SKILL.md
• ❌ DON'T hardcode project-specific values in skills — keep them generic
• ❌ DON'T duplicate content between SKILL.md and reference files — SKILL.md is the instruction, references are the data
• ❌ DON'T duplicate skill content inside agents — the agent loads the skill instead