Skip to main content
Version: Next

Author a custom module

A module is the smallest reusable unit insight-flow composes agents from. The shipped modules are built in and immutable; your own live in user space and carry a custom: id. This guide authors one and validates it.

1. Pick a kind​

Every module declares a kind. The authorable kinds are:

KindWhat it contributes
sectionA heading + body of role-prompt text.
includeA verbatim @<ref> line (e.g. @AGENT_SECURITY.md).
mcp-serverAn entry merged into .mcp.json under mcpServers[name].
hookA Claude Code hook reconciled into .claude/settings.json.
skillA .claude/skills/<name>/SKILL.md file.
bundleA list of other module ids, expanded in place.

Only mcp-server, hook, skill, and bundle emit installable artifacts; section and include are pure prompt text. (status-transition and handover are behavior-as-data and are typically authored on a flow's edges, not by hand here.)

2. Write the file​

User-space modules live under insightFlow/modules/, one JSON file per module. The id must start with custom: followed by a lowercase slug (custom:my-module), and the filename should match the id tail.

A section module — insightFlow/modules/house-style.json:

{
  "id": "custom:house-style",
  "title": "House code style",
  "kind": "section",
  "heading": "## House style",
  "body": "Match the existing two-space indent and double quotes. Keep diffs minimal."
}

An mcp-server module with a templated secret — insightFlow/modules/context7.json:

{
  "id": "custom:context7",
  "title": "Context7 MCP",
  "kind": "mcp-server",
  "name": "context7",
  "config": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp"],
    "env": { "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}" }
  },
  "inputs": [
    { "name": "CONTEXT7_API_KEY", "title": "Context7 API key", "secret": true }
  ]
}

The ${CONTEXT7_API_KEY} placeholder becomes a collected input at install time — see The install engine.

3. Validate​

User-space definitions are parsed with the same Zod schemas as the built-ins, on load. The quickest way to surface an error is to ask for the module's install plan (which loads the registry):

insight-flow ui

Open the dashboard at http://localhost:6006, browse to your module in the module browser, or trigger any flow/agent that references it. A malformed module throws a precise error, e.g.:

Invalid user-space definition insightFlow/modules/house-style.json:
  custom id must be 'custom:' followed by lowercase letters, digits, and hyphens

Common rules the loader enforces:

  • Non-custom: ids are rejected unless they exactly match a shipped built-in you are intentionally overriding (locked modules — status-transition / handover and the cross-cutting baseline — can never be overridden). Overriding a built-in is supported for one-off changes, but the authoring flow prefers a custom: variant — built-in defaults are treated as read-only so they stay upgradable.
  • Duplicate ids across files throw.
  • section modules need a heading or a non-empty body; skill / hook-script names must be safe path segments.

See also​