Skills Were Only Half the Answer: Upgrading to Agents, Skills and Commands

Developer Nasrul Hazim rewrote his agent-skills repository into a three-layer system of skills, agents, and commands, now named nasrulhazim/claude, to overcome limitations of skills alone. The new structure separates knowledge (skills), role personas with tool restrictions (agents), and workflow triggers (commands), and is bundled into projects via Kickoff 1.36.0. Key improvements include read-only tool boundaries for reviewers and automatic migration from the old setup.

Back in February I wrote about agent-skills https://dev.to/nasrulhazim/teaching-claude-code-to-think-like-a-laravel-developer-introducing-agent-skills-58cm — 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 https://github.com/cleaniquecoders/kickoff/releases/tag/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, pink=docs/business, blue=design, cyan=audit, yellow=support 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 https://github.com/cleaniquecoders/kickoff/releases/tag/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: Defaults to ~/Packages/claude, or pass a path 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 https://github.com/nasrulhazim/claude Kickoff: github.com/cleaniquecoders/kickoff https://github.com/cleaniquecoders/kickoff PRs open — especially agents. If you've found a role boundary worth encoding, I want to see it.