Back in February I wrote about agent-skills — a repo of SKILL.md
files that taught Claude Code my Laravel conventions so I'd stop re-explaining Pest, Action classes and Livewire 4 every session.
It worked. But after a few months of daily use, I hit a ceiling that skills alone couldn't fix.
Today I rewrote the repo. New name, new structure, three layers instead of one: ** nasrulhazim/claude**.
And because most of my projects are scaffolded from Kickoff, the same roster now ships into every generated app via Kickoff 1.36.0.
This post is the upgrade guide.
Before (agent-skills ) |
After (claude ) |
|
|---|---|---|
| Repo | nasrulhazim/agent-skills |
nasrulhazim/claude |
| Content | 14 skills | 29 skills, 20 agents, 10 commands |
| Installs to | ~/.claude/skills/ |
~/.claude/{skills,agents,commands}/ |
| Install methods | curl script | curl script or plugin marketplace |
| Renames | manual cleanup | automatic via migrations.txt
|
| Project-level | copy skills by hand | bundled by Kickoff 1.36.0 |
Upgrade in one line:
curl -fsSL https://raw.githubusercontent.com/nasrulhazim/claude/main/install.sh | bash
The installer detects your old skills, removes the renamed ones, and tells you what changed. Read on for what to watch out for.
A skill answers "how should this be done?" It carries knowledge and method — Pest patterns, PHPStan workflow, Livewire component structure.
What it doesn't answer is "who is doing it, and what are they allowed to touch?"
That distinction turned out to matter a lot. Concretely:
Problem 1 — reviewers that write code. I'd ask for a code review, and Claude would helpfully "fix" things mid-review. A review should produce findings, not commits. A skill can say "don't edit files"; it can't enforce it.
Problem 2 — no fan-out. I maintain 20+ packages. Bumping a dependency across all of them is the same role repeated 20 times in parallel. Skills are loaded into one session; there's no unit to delegate and multiply.
Problem 3 — skills doing two jobs. self-update
was maintaining CLAUDE.md
. api-lifecycle
covered design through governance. Fine names in isolation, but they didn't compose into a system I could reason about.
So the rewrite split one concept into three.
| Layer | Answers | Loaded | Example |
|---|---|---|---|
| Skill | |||
| How is this done? | |||
On demand, by trigger phrase or /name |
|||
pest-testing , code-quality |
|||
| Agent | |||
| Who does it, with what tools? | |||
| By delegation, explicit or automatic | |||
code-reviewer , qa-engineer |
|||
| Command | |||
| Run this workflow now | |||
/name |
|||
/upgrade-laravel , /docs |
|||
The key design rule: agents are thin. An agent is a 25–75 line role persona that loads skills as its playbook. It does not duplicate skill content. Knowledge lives in exactly one place — the skill — and agents are just personas pointing at it.
Here's the agent frontmatter:
---
name: code-reviewer
color: orange # red=security, orange=quality, green=build/ship,
description: Use this agent when... # third-person, trigger-oriented
tools: Read, Grep, Glob, Bash, Skill # optional allowlist; omit for all tools
---
That tools
line is the fix for Problem 1. Reviewer, auditor and security roles ship with a read-only allowlist — no Write
, no Edit
. The reviewer can't rewrite your code while reviewing it. That's not a prompt asking nicely, that's a tool boundary.
The description
field is the routing key. Claude matches your natural request against agent descriptions, which is why they're written in third person and trigger-oriented rather than as instructions to the agent.
One command. It installs everything and cleans up the old names:
curl -fsSL https://raw.githubusercontent.com/nasrulhazim/claude/main/install.sh | bash
Prefer the plugin? Same result, from inside Claude Code:
/plugin marketplace add nasrulhazim/claude
Pick one — installing both duplicates everything.
The installer handles this for you: it finds the old directories in ~/.claude/skills/
, removes them, and prints the mapping at the end of the run. Nothing orphaned, nothing competing for the same trigger phrases.
| Old | New |
|---|---|
api-lifecycle |
|
project-api |
|
faq-generator |
|
project-faq |
|
roadmap-generator |
|
project-roadmap |
|
self-update |
|
project-conventions |
Only thing left for you: update any notes or scripts still calling the old names.
The repo was renamed, so an old local clone needs a nudge before bash install.sh
will work:
git remote set-url origin https://github.com/nasrulhazim/claude.git
git pull
The curl install always fetches the latest installer, so it's never affected.
29 skills, up from 14. The new ones worth knowing:
| Skill | What it does |
|---|---|
project-laravel |
|
| Kickoff conventions enforcer and code scaffolder | |
kickoff-patch |
|
| Patch an existing project to the latest Kickoff baseline via category-grouped 3-way merge | |
project-ddd |
|
| Pragmatic DDD — domain discovery, migration planning, boundary enforcement | |
project-sync |
|
Sync CLAUDE.md conventions across multiple Kickoff projects |
|
project-inventory |
|
| Discover and inventory all Claude Code projects, with an HTML dashboard | |
git-workflow / gh-workflow |
|
| Conventional commits, releases, hooks / GitHub CLI automation | |
log-monitor |
|
| Production log analysis, error triage, GitHub issue creation | |
soc-analyst |
|
| Security triage, investigation, remediation, hardening | |
repo-research |
|
| Deep codebase analysis with structured research docs and diagrams | |
dev-summary |
|
| Multi-repo development stats, timelines, contributor analytics |
20 agents covering every SDLC phase. Rather than listing all of them, here's the mental model — the chains:
| Scenario | Chain |
|---|---|
| Feature | |
| project-manager → business-analyst → software-architect + database-engineer → laravel-developer / api-engineer → code-reviewer + qa-engineer → devops-engineer | |
| Incident | |
| support-analyst (triage) → security-analyst or performance-engineer (diagnose) → laravel-developer (fix) → tech-writer (post-mortem) | |
| Security assurance | |
| security-analyst (defensive audit) → penetration-tester (scoped, local/staging) → laravel-developer (fix) → security-analyst (re-verify) | |
| Release | |
| qa-engineer (suite green) → devops-engineer (changelog, tag, deploy) → tech-writer (release notes) |
Two agents are built specifically to fan out in parallel: package-maintainer
(across ~/Packages
) and fleet-auditor
(read-only sweeps for drift and inventory across many repos). That's Problem 2 solved — "fan out package-maintainer across these 10 packages" is now a single instruction.
When to reach for which:
| Use a… | When |
|---|---|
| Skill | You need knowledge/method in the current session |
| Agent | You want to delegate a role-shaped task, or fan out |
| Command | You want a repeatable workflow entry point (/name ) |
Everything above installs globally to ~/.claude/
. That's great for me and useless for my team — a teammate cloning the repo gets none of it.
Kickoff 1.36.0 fixes that by committing a curated roster into the project itself.
The mechanism is delightfully boring: Kickoff already mirrors stubs/
recursively into every scaffolded app. Drop the assets into stubs/.claude/
and they land in every new project with zero installer changes.
What ships into generated projects:
| Type | Count | Contents |
|---|---|---|
| Agents | 12 | api-engineer, code-reviewer, database-engineer, devops-engineer, laravel-developer, performance-engineer, qa-engineer, security-analyst, software-architect, tech-writer, ui-designer, upgrade-specialist |
| Skills | 17 | project-laravel, livewire-flux, pest-testing, code-quality, php-best-practices, design-patterns, project-api, project-ddd, git-workflow, gh-workflow, ci-cd-pipeline, kickoff-patch, log-monitor, project-conventions, project-docs, project-roadmap, project-faq |
| Commands | 3 | upgrade-laravel, upgrade-livewire, docs |
Note the curation. The global toolkit has 20 agents and 29 skills; the project bundle has 12 and 17. sales-planner
, svg-logo-system
, business-card
, courseware-builder
— those are my business tools, not something a Laravel app repo needs. Kickoff itself also carries its own .claude/
(5 agents, 8 skills) tuned for package development.
Refreshing the bundle:
bin/sync-claude-assets
bin/sync-claude-assets /path/to/claude
Idempotent, with the curated lists at the top of the script so you can edit what's included. The bundle is a snapshot — it doesn't auto-track the toolkit. Re-run the sync each Kickoff release.
Two gotchas from the release notes:
boost:install --skills
still runs during scaffolding and writes package-named skills alongside these. If a name ever collides, re-run bin/sync-claude-assets
.| Layer | Lives in | Good for |
|---|---|---|
| Global | ~/.claude/ |
Your personal roster — business skills, brand tools, multi-repo agents |
| Project |
.claude/ (committed) |
Team-shared conventions that must apply to this codebase |
My rule: if a teammate needs it to work on this repo, it goes in the project. If it's how I personally work, it stays global.
A code reviewer that knows the project's Kickoff conventions belongs in the repo — committed, versioned, reviewed like any other code. My logo designer does not.
This is also why project-conventions
(the renamed self-update
) matters more than it looks. It maintains CLAUDE.md
as you correct Claude during a session. Committed to the repo, that file becomes shared institutional memory — gotchas one developer discovered on Tuesday are available to everyone on Wednesday.
The contributing rules encode the lessons above:
metadata
with compatible_agents
and tags
; put templates and patterns in references/
bash generate-manifest.sh
before committing; migrations.txt
Rules 3 and 5 are the ones I'd steal even if you never touch my repo.
Rule 3 keeps knowledge single-sourced. The moment an agent starts explaining how to write a Pest test instead of delegating to pest-testing
, you have two copies of that knowledge drifting apart.
Rule 5 is what makes renaming survivable. Without a migration file, every rename leaves a landmine in every user's ~/.claude/
— a stale skill with overlapping triggers, silently competing with its replacement. Four lines of old:new
text turn a breaking change into a clean, self-announcing upgrade.
The installer stays Bash 3.2-compatible, incidentally, so macOS's stock /bin/bash
works without anyone installing anything.
The February version of this idea was: give Claude a reusable module of expertise instead of a long prompt. That still holds.
What I got wrong was assuming expertise was the only missing piece. A skill tells Claude how to review code. It doesn't stop Claude from writing code while reviewing. It doesn't let you say "do this role across twenty repos." It doesn't survive a rename.
Skills carry knowledge. Agents carry role and permission. Commands carry workflow. Three layers, one repo, one installer that knows how to upgrade itself.
curl -fsSL https://raw.githubusercontent.com/nasrulhazim/claude/main/install.sh | bash
Toolkit: github.com/nasrulhazim/claude
Kickoff: github.com/cleaniquecoders/kickoff
PRs open — especially agents. If you've found a role boundary worth encoding, I want to see it.