Skip to content
Skills Library
AI & agents · Building & coding

create-mod

/create-mod

Scaffold a Claude Code mod (a plugin with a function-hooks module) from ruflo's governed template — hybrid hooks.json with a classic fallback, a host adapter over literal $ calls, userConfig options, engine-kit tests and a tsconfig — then validate and test it. Use when the user asks for a mod, a function hook, or wants Claude Code to modify itself.

Repository
ruflo ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Scaffold a Claude Code mod (a plugin with a function-hooks module) from ruflo's governed template — hybrid hooks.json with a classic fallback, a host adapter over literal $ calls, userConfig options, engine-kit tests and a tsconfig — then validate and test it. Use when the user asks for a mod, a function hook, or wants Claude Code to modify itself.

Arguments

/create-mod <mod-name>
Original author description

Scaffold a Claude Code mod (a plugin with a function-hooks module) from ruflo's governed template — hybrid hooks.json with a classic fallback, a host adapter over literal $ calls, userConfig options, engine-kit tests and a tsconfig — then validate and test it. Use when the user asks for a mod, a function hook, or wants Claude Code to modify itself.

How it works

  1. Steps
Original SKILL.md headings · 28 lines, 584 words
SKILL.md preview
---
name: create-mod
description: Scaffold a Claude Code mod (a plugin with a function-hooks module) from ruflo's governed template — hybrid hooks.json with a classic fallback, a host adapter over literal $ calls, userConfig options, engine-kit tests and a tsconfig — then validate and test it. Use when the user asks for a mod, a function hook, or wants Claude Code to modify itself.
argument-hint: "<mod-name>"
allowed-tools: Bash Read Write Edit
---

# Create Mod

Scaffold a mod the governed way, instead of an ad-hoc one: the template already follows the rules ruflo's own mod (ADR-404) was reviewed against.

## Steps

1. **Name it.** kebab-case `<name>`. Commands it registers are namespaced `<name>-<verb>`; never register a built-in's name (`/diff`, `/help`) or another plugin's (`/ruos*`, `ruflo-*`).
2. **Scaffold from the template** with `node plugins/ruflo-plugin-creator/scripts/scaffold-mod.mjs <name> <target-dir>`. It copies `templates/mod/`, turns the manifest template `plugin.json.tmpl` into `.claude-plugin/plugin.json` (the template keeps it under a non-manifest name so plugin validators do not mistake `templates/mod` for a second plugin), and replaces `my-mod` everywhere (plugin.json `name`, the command, `MY_MOD_ACTIVE` → `<NAME>_ACTIVE` in both `hooks/register.ts` and `hooks/classic.cjs`, the status folder). Doing it by hand: copy the folder, move `plugin.json.tmpl` to `.claude-plugin/plugin.json`, and make the same replacements.
3. **Keep the status contract.** `hooks/status.ts` writes `.claude-flow/<name>-mod/status.json`, the file the console's Mods section reads. The folder must be `<name>-mod` (lowercase, digits, hyphens, at most 41 characters): the scaffold script already sets `STATUS_PATH` to `<name>-mod`. Fields: `version: 1` (required, anything else is ignored), `summary` (one line), `modVersion`, `guard` (boolean), `calls` (a **number**, not a per-tool object), `blocked` (number), `lastDenied` (a short reason, only once the mod has refused something), plus `updatedMs`/`startedMs`. Other fields are not shown. `tests/status.test.ts` asserts the shape.
4. **Write the behaviour** in pure functions taking the `Host` (see `hooks/host.ts`). In `register.ts`, build the host from literal `$.noun.method(...)` calls only — the engine reads a module's `$` uses off its source, and `claude plugin validate` refuses `$` passed around, computed (`$[noun]`), or deeper than `$.noun.method(input)`.
5. **Keep the rules:**
   - Observe with `const r = await next(e); …; return r`; rewrite with `next({ ...e, … })`; answer (`{ deny }`) only when you mean to stop the chain.
   - On `tool.check`, only ever tighten (the stricter of `await next(e)` and yours); never answer `allow` of your own.
   - Wrap every `$` call so a refusal degrades instead of failing the turn (admins can withhold any `$` affordance).
   - No `$.process.run` / `$.http.fetch` built from event input. Nothing slow on the hot path (about 10 s per dispatch).
   - Anything that must survive a hot reload goes in `$.store` / `$.state`, not module variables.
   - Options come from `userConfig` in plugin.json, not environment variables.
6. **Keep the fallback honest.** `hooks.json` is hybrid: the classic command hook runs everywhere, the module only where function hooks are on (Claude Code >= 2.1.287; 2.1.277+ with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`). The module sets `<NAME>_ACTIVE` at `session.start`; the classic script exits early when it sees it, so nothing fires twice.
7. **Validate and test:**
   ```bash
   claude plugin validate <dir>      # lists hooked events, $ calls, env reads/writes
   claude plugin test <dir>          # tests/*.test.ts on the engine kit
   claude -p --plugin-dir <dir> "/<name>-status"   # writes .claude-plugin/types/ and proves a live load
   npx tsc -p <dir>                  # against those generated types
   ```
8. **Ship it in a plugin marketplace** (`marketplace.json` entry), installed with `/plugin install <name>@<marketplace>` and picked up with `/reload-plugins`. If ruflo-mods is installed with `modTrust: refuse-risky`, a mod using `process.run`/`process.spawn`, `http.fetch`, `mcp.call`/`mcp.connect`, `session.send`, `config.set`, `env.set`, `fs.write`, `agent.spawn`/`agent.register`, `prompt.submit`, `session.append`, `tool.call` or `command.run`, or hooking any event in its `RISKY_EVENTS` (`tool.check`, `tool.call`, `prompt.*`, `agent.spawn`, `tool.describe`, `session.append`, `session.receive`, `turn.step`, `skill.prompt`, `session.compact`, `prompt.edit`, `fs.read`/`fs.stat`/`fs.exists`/`fs.list`, `settings.read`, `env.get`, a hook on any of the calls above (it can rewrite another mod's call), `plugin.register`, `classic.*`, `*`; a glob or a `!` negation is judged by what it selects), is refused unless its plugin id (`<name>@<marketplace>`) is in `modTrustAllow` — the template sets `env.set` (the fallback handshake), so allow-list it by id.

Versions

RepositoryScoreLicence
This page · ruvnet/ruflo100MIT
BrandeisPatrick/silo-harness100MIT

Database snapshot: 13.11.2026 · package version 37d32b00fd9e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100creating-mods
    Use when asked to build, extend or debug a Claude Mod, a Claude Code plugin with function hooks (a hooks module, register(on), hooks shaped ($, e, next), events like tool.call, prompt.submit, ui.render), or when a hooks module loads but its hook never fires.
  • 90claude-mods
    Apply when writing or reviewing a Claude Code mod — a plugin's hooks module (`hooks/hooks.json` naming `modules`), its state contract, or anything under packages/genshin-mods or packages/genshin-persona/mod. Esposter's conventions for function hooks the engine checks at load.
  • 100claude-desktop-mods
    Build, test, and ship Claude Code / Claude Desktop "mods": plugins whose JS/TS module registers event handlers that run inside Claude Code (custom panes, slash commands, tools, permission guards, prompt rewriting, status UI). Use when the user wants to create or debug a mod, a…
  • 100meta-plugin-structure
    Use when the user asks to ”create a plugin”, ”scaffold a plugin”, or ”understand plugin structure” for Claude Code.
  • 100ruflo
    Ruflo is a multi-agent orchestration platform for AI coding agents (Claude Code, Cursor, Codex, Copilot, Gemini, Amp, +12 more). Use this skill when the user wants to (1) install/init ruflo in a project, (2) run multi-agent swarms with hierarchical coordination, (3) use ruflo's…
  • 100claude-desktop-plugins
    Create, validate, and publish Claude plugins for Claude Desktop (Chat, Cowork, Code tab) and Claude Code: .claude-plugin/plugin.json, skills, commands, agents, hooks, MCP and LSP servers, userConfig, marketplaces and the Anthropic directory. Use when the user asks how to build a…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.