Extending the skills and agents catalog

Reading through .claude/skills/, a gap falls into one of two shapes, and they call for different work:

Knowing which one you’re looking at changes the size of the task: the first is "write one new skill that matches an existing contract," the second is "decide whether to generalize or fork, then do either the detection work or the forking."

This is the catalog’s most fully-built extension point, and the template to copy for any similar registry.

iru-plan (Plan) tags every task with a language/framework key by checking which -code-one-task skills are actually installed: first from the skills available in the session (names matching iru--code-one-task), then — when a .claude/skills directory exists — corroborated with find .claude/skills -maxdepth 1 -type d -name "-code-one-task", so the lookup also works when the catalog is installed as plugins (see Plugins) and no such directory exists. The skill name minus its iru- prefix and the suffix is the key (iru-java-code-one-task → java, iru-dotnet-code-one-task → dotnet, iru-database-code-one-task → database); the iru- prefix is only this catalog’s marketplace-collision namespace, not part of the key itself. iru-code-one-task-group (Code One Task Group) does the same lookup for -code-one-task-group at execution time, partitions a plan group’s tasks into buckets by key, and dispatches each bucket to its iru-<key>-code-one-task-group skill. Neither orchestrator names java, dotnet, or database anywhere in its own instructions — they are just whatever happens to be installed.

To add a new backend (say, python or go), create — carrying the iru- prefix every skill and agent in this catalog uses (see Creating and updating skills and agents) to avoid colliding with same-named skills installed from other marketplaces:

Whatever test/coverage/quality/doc-comment skills the new iru-<key>-code-one-task-group calls internally (iru-java-test/iru-java-coverage/iru-java-code-quality/iru-java-javadoc, iru-dotnet-test/iru-dotnet-coverage/ iru-dotnet-code-quality/iru-dotnet-docfx) are not part of the registry contract and aren’t looked up generically by name — they’re plain internal implementation detail of that one group skill, so name them however fits the new stack’s own tooling (there’s no requirement to call the doc-comment one iru-<key>-javadoc, for instance — iru-dotnet-docfx already breaks that pattern). Route each through the iru-gate-runner agent (Gate Runner) the same way the existing ones do, so their raw report output stays out of the calling context.

Once both skills exist, iru-plan and iru-code-one-task-group pick the new key up automatically on their next run — nothing else in the pipeline needs to change.

If the new stack builds a user interface, its iru-<key>-code-one-task also carries the shared UI contract — copy reference/ui-contract.md byte-for-byte from any existing UI coding skill and write a reference/ui-implementation.md mapping it onto the stack (composition idioms, inputs/events, the virtualized collection container, UI test runner, LTR/RTL and light/dark switches, the screenshot helper writing .ui-screenshots/, the automated accessibility check reading .ui-quality.yml); its group skill adds the UI validation stage, its test gate collects the screenshots, and its scaffold writes .ui-quality.yml. See Building user interfaces.

iru-setup-repository (Setup Repository) is the front door for bootstrapping any repository this catalog supports: it detects a non-empty repository by running iru-explore and reading its Project type: line to pre-select a stack, or, on an empty one, asks the project type over up to five AskUserQuestion rounds of three options each, every round ending in a "Something in the next group" escape hatch (JVM services & libraries, Web & Node, PHP, Python, Mobile & Apple — an option that bundles several types gets one bounded follow-up, e.g. web app → React / Next.js / Angular), asks the shared inputs (open-source, visibility, ci, sonar, ci-tests, pages, publish/distribution, …) once, and delegates to the matching stack orchestrator via iru-isolated-skill-executor. It first announces the setup mode (from scratch, or updating an existing repository with an inventory of the prior setup found); on an existing repository it forces mode: existing on that delegation, and every component sub-skill then warns about each pre-existing artifact it owns and asks Update / Keep as is / Replace instead of assuming a brand-new repo.

Underneath the front door, each stack has its own orchestrator. The eleven -repository orchestrators — iru-setup-java-library-repository, iru-setup-quarkus-repository, iru-setup-typescript-repository, iru-setup-php-repository, iru-setup-python-repository, iru-setup-android-repository, iru-setup-swift-repository, iru-setup-kmp-repository, iru-setup-macos-repository, iru-setup-windows-repository, iru-setup-cli-repository — all run the same fixed six-step shape, standalone or via the front door: scaffold (the language/flavor-specific iru-setup-<stack>-library/-app skill, e.g. iru-setup-typescript-repository’s own `flavor picks between iru-setup-typescript-library, iru-setup-react-web, iru-setup-angular-web, iru-setup-react-native-app, iru-setup-ionic-app, iru-setup-nestjs-app, iru-setup-nextjs-web; iru-setup-php-repository’s between `iru-setup-php-laravel, iru-setup-php-wordpress (plugin or block theme), iru-setup-php-prestashop; iru-setup-python-repository’s between `iru-setup-python-fastapi, iru-setup-python-django; iru-setup-quarkus-repository always runs iru-setup-quarkus-service, parameterized by language/build-tool/layout; iru-setup-kmp-repository always runs iru-setup-kmp-app, parameterized by ui; iru-setup-macos-repository and iru-setup-windows-repository always run iru-setup-macos-app/iru-setup-windows-app, parameterized by ui and architecture (MVVM or MVC, offered only where the UI framework supports both); iru-setup-cli-repository picks iru-setup-rust-cli, iru-setup-go-cli, iru-setup-swift-cli or iru-setup-dotnet-cli by language, parameterized by ui, with one shared iru-setup-cli-github-workflows skill for all four languages; and a *toolchain variant such as React Native’s toolchain: expo|metro is a parameter of one scaffold skill, iru-setup-react-native-app, forwarded by its orchestrator to the matching workflows skill too, rather than a separate flavor) → iru-setup-antora → iru-setup-<stack>-gitignore → iru-setup-<stack>-github-workflows → iru-setup-changelog → iru-setup-readme (a stack may reuse a sibling’s gitignore skill, as Quarkus reuses iru-setup-java-gitignore and the macOS desktop stack reuses iru-setup-swift-gitignore). iru-setup-java-springboot is the exception: it runs a manifest-driven chain of its own (interview → springboot-stack.yml → iru-setup-java-springboot-pom/-modules/-apis/-hilla/ -testcontainers/-platform/-github-workflows → iru-update-java-springboot-documentation → gitignore/README/ changelog) because a hexagonal Spring Boot reactor has far more to generate than a single scaffold step; its language: java|kotlin and build-tool: maven|gradle args are how a language variant joins an existing chain without forking it — Kotlin is a branch inside each iru-setup-java-springboot- sub-skill, not a parallel set of skills. iru-setup-antora, iru-setup-changelog, and iru-setup-readme are the three steps already generalized across the -repository orchestrators — don’t fork those; a new stack only ever needs its own scaffold, gitignore, and workflows skills.

To add a new project type:

iru-release (Release) is no longer Maven-only: its branch/PR/label/changelog steps — determining the PR base branch by checking what actually exists on the remote rather than assuming main, delegating the changelog summary to the iru-change-summarizer agent (Change Summarizer), drafting the PR description via iru-pr-description (PR Description) — stay the same for every ecosystem, and only the version-bump mechanics are pluggable: which file carries the version, what "current pre-release" looks like in that ecosystem, and what command (if any) applies the bump. That pluggable piece is now a registry, the same shape as [_language_framework_backends_for_the_code_pipeline]: iru-release discovers the installed iru--bump-version skills from the session’s available skills (corroborated with find .claude/skills -maxdepth 1 -type d -name "iru--bump-version" when that directory exists) and delegates the actual edit to whichever iru-<key>-bump-version skill matches the project it detected (today: java (Maven or Gradle, Java or Kotlin), typescript, react-native, android, kmp, swift, php, python, dotnet, rust, go), falling back to asking the user which file to edit by hand if none is installed.

To add a new ecosystem, create iru-<key>-bump-version following the sibling contract every existing one shares (TypeScript Bump Version is a good template):

iru-release picks up the new key automatically on its next run — nothing else in that skill needs to change.

Two detections already exist inside iru-explore (Explore) and are reused by iru-issue, iru-pr-description, and iru-pr-review, and are worth knowing about before assuming they need building from scratch:

Adding a third tracker (Azure Boards, Linear, …) or confirming support for a host this catalog doesn’t yet name means extending iru-explore’s two detection steps with the new pattern, then — for a new tracker — adding an `iru-create-<tracker>-ticket skill mirroring the two that exist. Because iru-issue, iru-pr-description, and iru-pr-review all read iru-explore’s detection result rather than re-implementing their own, a new host only needs wiring into `iru-explore once and the tooling calls (branch/PR/merge-request creation, comment posting) inside those three downstream skills — not into every skill that touches git hosting individually.

iru-create-jira-ticket (Create Jira Ticket) already asks for the context every ticket needs regardless of organization — purpose, related tickets, an optional epic, a due date, an importance level. Many organizations need more than that before a ticket is genuinely ready to file: a required custom field, team/component ownership, a customer/account, an affected environment, a compliance or security classification. Rather than growing iru-create-jira-ticket itself with organization-specific questions that wouldn’t apply to every installation of this catalog, that skill delegates to iru-jira-custom-context (Jira Custom Context) during its own context-gathering step.

Out of the box, iru-jira-custom-context asks a single generic, optional catch-all question and returns whatever the user provides — it defines no organization-specific questions of its own. Extending it is a one-file customization, unlike the registry-shaped extension points above: there’s no naming convention to match or a new skill to register, just this one skill’s own Step 2, edited in place, with whichever questions or lookups a given Jira workflow actually needs — a fixed-choice AskUserQuestion when the answer is a known, bounded set, an open-ended question when it’s free-form, or an automated lookup (via a connected MCP tool) when the context can be derived rather than asked.

iru-check-license, iru-check-security, and the per-language iru-<key>-code-quality skills are all invoked the same way — through the iru-gate-runner agent (Gate Runner), which runs one gate, optionally diffs it against a baseline, and reports back a compact summary instead of the raw tool report. Adding a new gate (a dependency-vulnerability scan, an accessibility check, a performance budget) means writing one skill in that same shape — a single scan/check with a clear pass/fail and issue list — and then wiring a iru-gate-runner call for it into whichever iru-<key>-code-one-task-group skill(s) should run it as part of their per-bucket validation pass (every validating group skill has one — e.g. Java Code One Task Group Step 1/4, PHP Code One Task Group, NestJS Code One Task Group, FastAPI Code One Task Group; only Database Code One Task Group runs no gates). The new gate doesn’t need to touch iru-gate-runner itself — that agent already runs "whatever skill name it’s told to run."

Agents documents the three custom agents this catalog has needed so far (iru-gate-runner, iru-isolated-skill-executor, iru-change-summarizer) and, more usefully for extension, the test it applies before adding a fourth: only when a built-in agent type’s tool access or system prompt genuinely doesn’t fit a recurring sub-agent shape used by more than one skill. A one-off isolation need (as several skills already handle by calling the built-in general-purpose or Explore types directly via Agent) doesn’t warrant a new custom agent definition; a shape that starts showing up identically in a third or fourth skill probably does.

iru-setup-antora, iru-build-docs, iru-update-docs, and iru-generate-skill-docs are all built specifically around Antora — the toolchain this catalog itself uses for docs/. Supporting a repository that documents itself with something else (MkDocs, Docusaurus, plain GitHub wiki pages) would mean paralleling this same quartet for that tool rather than trying to generalize Antora-specific logic (playbook/component config, AsciiDoc xref syntax, the nav.adoc format) in place — there’s currently no signal in this catalog that more than one doc toolchain needs supporting at once, so building that generalization ahead of a second real use case would be speculative.

The sections above cover each extension point in isolation; a genuinely new project type (a new stack, not just a new flavor of an existing one) touches most of them at once. This checklist pulls the full set together in the order it’s usually easiest to work through:

Once a new skill following one of the shapes above is in place: