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: find .claude/skills -maxdepth 1 -type d -name "-code-one-task" — the directory 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 typescript), 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.

iru-setup-java-library-repository (Setup Java Library Repository) is a fixed, six-step orchestration — iru-setup-java-library → iru-setup-antora → iru-setup-java-gitignore → iru-setup-java-github-workflows → iru-setup-changelog → iru-setup-readme — built specifically for a brand-new Java/Maven repository. Three of those six (iru-setup-antora, iru-setup-changelog, iru-setup-readme) already derive everything from whatever’s on disk and aren’t Java-specific in principle; the other three (iru-setup-java-library, iru-setup-java-gitignore, iru-setup-java-github-workflows) are.

To support bootstrapping a different stack (an npm library, a Python package, a .NET library), the two options this catalog’s own architecture points at:

Either way, iru-setup-antora, iru-setup-changelog, and iru-setup-readme are the parts of this pipeline already generalized — don’t fork those; extend the stack-specific three (or their equivalents for the new stack).

iru-release (Release) is, today, entirely Maven/gitflow-shaped: it reads and writes a <version> element in pom.xml, assumes a develop integration branch and a release_x.y.z branch name, and hands README.md/Antora version-snippet updates off to iru-setup-readme. The parts of it that are already stack-agnostic — 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) — don’t need to change for a new ecosystem.

What would need to generalize is narrowly the version-bump mechanics: which file carries the version (pom.xml vs package.json vs <Project>/Directory.Build.props/.csproj vs pyproject.toml), what "current pre-release" looks like in that ecosystem (-SNAPSHOT vs a pre-release semver tag vs a dev version marker), and what command (if any) applies the bump for that tool. Rather than teaching one iru-release skill every ecosystem’s version file, the same registry shape as [_language_framework_backends_for_the_code_pipeline] applies cleanly here: detect the project’s language/build tool (iru-explore’s own Step 3 already does this), then look for and delegate to an `iru-<key>-bump-version-style skill if one is installed, falling back to asking the user which file to edit by hand if none is. That keeps `iru-release’s own branch/PR/label/changelog steps — the genuinely reusable majority of the skill — untouched while making the one Maven-specific step pluggable per ecosystem.

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 (Java Code One Task Group Step 1/4 and .NET Code One Task Group's equivalent are the two current call sites). 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.

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