plugin-authoring

Author and debug Catalyst Code plugins including hooks, custom tools, OAuth providers, and memory backends.

10|1|Updated Jul 7, 2026
One-click install
npx skills add https://github.com/catalystctl/catcode --skill plugin-authoring-catalystctl
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: plugin-authoring
Source: https://github.com/catalystctl/catcode/tree/main/.catalyst-code/skills/plugin-authoring
Command: npx skills add https://github.com/catalystctl/catcode --skill plugin-authoring-catalystctl

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Extending a coding-agent harness normally requires recompiling the core or wiring up an MCP server. This Skill documents the Catalyst Code plugin system so you can add hooks, custom tools, slash commands, OAuth providers, and memory backends by dropping files into .catalyst-code/plugins/. ## Core Features & Use Cases - Hook authoring: Write pre/post hook scripts (pre_bash, pre_write, pre_tool, post_tool, lifecycle hooks) that receive JSON on stdin and return allow/modify/notify responses on stdout, with policy-table failure semantics. - Custom tools and commands: Declare model-callable tools with JSON Schema parameters, override built-in tools, disable tools, and create script-backed or prompt-backed slash commands. - Provider and memory integration: Add subscription OAuth providers (login/complete/token/clear actions) and replace the markdown memory store with an external memory_provider backend. - Use Case: You want every file write linted before it lands. Create a plugin with a pre_write hook script, register it in plugin.json, install it with /plugin-install, and the hook can block or rewrite content before the write executes. ## Quick Start Use the plugin-authoring skill to create a Catalyst Code plugin with a pre_write hook that blocks writes to files containing secrets.

Frequently Asked Questions about plugin-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Catalyst Code plugin?

Create a directory under .catalyst-code/plugins/, write a plugin.json manifest with name, version, and hooks, then add executable hook scripts. Install it with /plugin-install from a local path or GitHub release, and reload with /plugin-reload.

How do plugin hooks work in Catalyst Code?

Each hook script receives one JSON object on stdin with the hook name, tool, workspace, and args, and must write one JSON object to stdout with allow, reason, and optional modify fields. Blocking pre hooks fail closed on errors, while post hooks fail silently.

Can a plugin add custom tools without MCP?

Yes. Add a tools array to plugin.json with a name, JSON Schema parameters, and an executable handler script. The handler receives args on stdin and returns ok and output on stdout, with optional override:true to replace a built-in tool.

How do I add an OAuth provider to Catalyst Code?

Declare an oauth block in plugin.json with provider_id, base_url, kind, and a script handling login, complete, token, and clear actions. The harness manages the loopback redirect server and token caching; your script writes tokens to token_path atomically.

Why is my project plugin not loading?

Repo-shipped plugins require the --trust-project-plugins flag to load, while user-installed workspace plugins load without it. Also verify hook scripts are executable with chmod +x and that the directory name matches the plugin name in plugin.json.

What are the limitations of prompt-backed slash commands?

Prompt-backed commands render a template file and submit it as an agent turn, so they cannot run subprocesses and are capped at 256 KiB templates. When invoked from the command palette without inline args, they should use the ask tool to collect user input via a modal.