{"id":104,"date":"2026-10-31T08:00:00","date_gmt":"2026-10-31T07:00:00","guid":{"rendered":"https:\/\/hoja.in\/blog\/packaging-skills-agents-and-hooks-as-a-claude-code-plugin\/"},"modified":"2026-10-16T14:00:12","modified_gmt":"2026-10-16T12:00:12","slug":"packaging-skills-agents-and-hooks-as-a-claude-code-plugin","status":"publish","type":"post","link":"https:\/\/hoja.in\/blog\/packaging-skills-agents-and-hooks-as-a-claude-code-plugin\/","title":{"rendered":"Packaging skills, agents and hooks as a Claude Code plugin"},"content":{"rendered":"

When I started using Claude Code seriously for TYPO3 upgrades, my setup lived in the .claude\/<\/code> folder of each project: a few skills, two or three subagents, a hook script. Then I copied that folder into the next project. And the next. After a month I had five slightly different versions of the same guard hook, and the best fix was in a project I had already closed.<\/p>\n

Claude Code plugins solve exactly this. A plugin is a directory with a fixed layout that bundles skills, agents, hooks, MCP servers and more. You install it from a marketplace, it has a version, and every project uses the same copy. This post shows how I packaged my typo3-project-migration<\/code> plugin, the one that did the legwork for the hoja.in move from TYPO3 7.6 to 14.3.<\/p>\n

The layout<\/h2>\n

The most common mistake first: only the manifest goes into .claude-plugin\/<\/code>. Everything else sits at the plugin root. This is the real tree of my plugin, without node_modules<\/code> and CI files:<\/p>\n

typo3-project-migration\/\n\u251c\u2500\u2500 .claude-plugin\/\n\u2502   \u251c\u2500\u2500 plugin.json\n\u2502   \u2514\u2500\u2500 marketplace.json\n\u251c\u2500\u2500 skills\/\n\u2502   \u251c\u2500\u2500 typo3-project-migration\/\n\u2502   \u2502   \u251c\u2500\u2500 SKILL.md\n\u2502   \u2502   \u251c\u2500\u2500 references\/   (hop cards v10 \u2192 v14, troubleshooting, ...)\n\u2502   \u2502   \u2514\u2500\u2500 scripts\/      (inventory.sh, project-gate.sh, t3.sh, ...)\n\u2502   \u251c\u2500\u2500 assess\/SKILL.md\n\u2502   \u251c\u2500\u2500 verify\/SKILL.md\n\u2502   \u2514\u2500\u2500 dev-companion\/SKILL.md\n\u251c\u2500\u2500 agents\/\n\u2502   \u251c\u2500\u2500 project-scout.md\n\u2502   \u251c\u2500\u2500 extension-auditor.md\n\u2502   \u251c\u2500\u2500 upgrade-strategist.md\n\u2502   \u2514\u2500\u2500 upgrade-reviewer.md\n\u251c\u2500\u2500 hooks\/\n\u2502   \u251c\u2500\u2500 hooks.json\n\u2502   \u2514\u2500\u2500 scripts\/guard-bash.sh\n\u251c\u2500\u2500 scripts\/selftest.sh\n\u2514\u2500\u2500 CHANGELOG.md<\/code><\/pre>\n
Skills are folders with a SKILL.md<\/code>; scripts and reference files the skill needs live next to it. Agents are single Markdown files with frontmatter. Hooks are configured in hooks\/hooks.json<\/code>. Each of these is a default location, so Claude Code finds them without any configuration. Every component is namespaced with the plugin name, so the skill verify<\/code> appears as typo3-project-migration:verify<\/code> and cannot clash with a verify<\/code> skill from another plugin.<\/p>\n
Step 1: the manifest<\/h2>\n
.claude-plugin\/plugin.json<\/code> is optional; only name<\/code> is required when you write one. I write one anyway, because the version and the description matter once other people install the plugin:<\/p>\n
{\n  \"name\": \"typo3-project-migration\",\n  \"displayName\": \"TYPO3 Project Migration\",\n  \"version\": \"0.1.0\",\n  \"description\": \"Upgrade whole TYPO3 projects from v10 to v14, one LTS at a time.\",\n  \"author\": {\n    \"name\": \"Hoja Mustaffa Abdul Latheef\",\n    \"url\": \"https:\/\/jweiland.net\"\n  },\n  \"license\": \"MIT\",\n  \"keywords\": [\"typo3\", \"migration\", \"upgrade\", \"composer\", \"ddev\"]\n}<\/code><\/pre>\n
Use kebab-case for name<\/code>. The validator also refuses names that look like Anthropic’s own plugins (for example anything starting with claude-<\/code>), so do not call yours claude-typo3<\/code>.<\/p>\n
Step 2: agents with a model per job<\/h2>\n
Agents are where a plugin pays off most for me, because each one can have its own tools and model. A read-only scout that greps through templates does not need the biggest model; the reviewer that has to find what the green test run misses does. The frontmatter of the reviewer:<\/p>\n
---\nname: upgrade-reviewer\ndescription: Adversarial reviewer for one finished hop of a TYPO3 project upgrade. Reads the hop's commits, the gate output, the ledger and the plan, and hunts for what the gate misses. Read-only.\ntools: Read, Grep, Glob, Bash\nmodel: opus\n---\n\nYou review one hop of a TYPO3 project upgrade, and you don't trust the green gate. You change nothing.<\/code><\/pre>\n
In my plugin the scout runs on Haiku, the extension auditor on Sonnet, the strategist and the reviewer on Opus. The description is not decoration: it is what the main session reads to decide when to delegate, so write it like a job ad, with the trigger words people actually use.<\/p>\n
Step 3: hooks that travel with the plugin<\/h2>\n
A rule in a prompt is a wish. A hook is enforced by Claude Code, outside the model. My plugin ships one PreToolUse<\/code> hook for the Bash tool:<\/p>\n
{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\"${CLAUDE_PLUGIN_ROOT}\/hooks\/scripts\/guard-bash.sh\"\"\n          }\n        ]\n      }\n    ]\n  }\n}<\/code><\/pre>\n
${CLAUDE_PLUGIN_ROOT}<\/code> resolves to the installed plugin directory, which changes with every version, so never hard-code a path and never write state there. The script reads the tool call as JSON on stdin and answers with a decision. The core of it:<\/p>\n
if has '(typo3|t3.sh)[[:space:]]+[^|;&]*(extension:setup|upgrade:run|upgrade:mark:undone)'; then\n  recent=\"$(find .project-migration\/backups .ddev\/db_snapshots -maxdepth 1 -mmin -1440 \n    ( -name '*.sql' -o -name '*.sql.gz' -o -name '*.gz' ) 2>\/dev\/null | head -1 || true)\"\n  if [[ -z \"$recent\" ]]; then\n    decide deny \"No database dump from the last 24 h. Take one first, then run it again.\"\n  fi\nfi<\/code><\/pre>\n
decide<\/code> prints a small JSON object with hookSpecificOutput.permissionDecision<\/code> set to deny<\/code> or ask<\/code> and a reason that Claude sees. So the agent gets told why, takes the dump with ddev snapshot<\/code>, and tries again. On hoja.in this is the hook that blocked database writes until a fresh dump existed. It also asks before ddev import-db<\/code> and denies --ignore-platform-reqs<\/code> and git commit --no-verify<\/code>.<\/p>\n
Step 4: a marketplace for the team<\/h2>\n
A marketplace is just a .claude-plugin\/marketplace.json<\/code> that lists plugins and where to get them. My plugin repository is its own marketplace, with the plugin at the root:<\/p>\n
{\n  \"name\": \"typo3-project-migration\",\n  \"owner\": { \"name\": \"Hoja Mustaffa Abdul Latheef\" },\n  \"plugins\": [\n    {\n      \"name\": \"typo3-project-migration\",\n      \"source\": \".\/\",\n      \"description\": \"Upgrade whole TYPO3 projects from v10 to v14, one LTS at a time.\"\n    }\n  ]\n}<\/code><\/pre>\n
For a team with several plugins, one repository with a plugins\/<\/code> folder and one entry per plugin works better. Keep the entry name<\/code> and the name<\/code> in plugin.json<\/code> identical; a mismatch gives confusing “not found” errors at install time.<\/p>\n
Then, in the shell:<\/p>\n
claude plugin validate .\/typo3-project-migration\nclaude plugin marketplace add .\/typo3-project-migration\nclaude plugin install typo3-project-migration@typo3-project-migration\n\n# while developing: load the plugin directly, no install\nclaude --plugin-dir .\/typo3-project-migration<\/code><\/pre>\n
To make a project suggest the marketplace and plugin to everybody who opens it, commit this to the project’s .claude\/settings.json<\/code> (the repository name is a placeholder for your own):<\/p>\n
{\n  \"extraKnownMarketplaces\": {\n    \"typo3-tools\": {\n      \"source\": { \"source\": \"github\", \"repo\": \"your-org\/claude-typo3-plugins\" }\n    }\n  },\n  \"enabledPlugins\": {\n    \"typo3-project-migration@typo3-tools\": true\n  }\n}<\/code><\/pre>\n
Step 5: versions and a self-test<\/h2>\n
The version<\/code> in plugin.json<\/code> pins users to that version until you change it. So a fix only reaches your colleagues when you bump the version. I keep a CHANGELOG.md<\/code> in Keep a Changelog format, and a scripts\/selftest.sh<\/code> that runs in CI and checks the boring things: all manifests are valid JSON, the changelog has an entry for the current version, every skill and agent has frontmatter with a real description, and every agent declares a model. Plus claude plugin validate --strict<\/code>, which turns warnings into failures.<\/p>\n
One more thing to know: when you add a marketplace from a local path, Claude Code reads the plugin files in place. Your edits are live at the next session start or after \/reload-plugins<\/code>, without a version bump. Great for development, but remember that your colleagues who installed from git do not have your local edits.<\/p>\n
Was it worth it?<\/h2>\n
Yes. The guard hook exists once, with a self-test. When I improve an agent or a hook, every project gets the better version with the next update instead of the next copy-paste. If you have a .claude\/<\/code> folder that you copied more than twice, package it.<\/p>\n
Further reading<\/h2>\n