Create complete Cowork plugins through HOLD:AGENT:HOLD architecture and THE FORGE PROCESS. Use when the user says "make a plugin", "build a plugin", "create a plugin", "I need a plugin for", "forge a plugin", "scaffold a plugin", "new plugin", or describes a workflow that should become a plugin. Also triggers when the user wants to turn a repeated pattern into a reusable plugin, package a set of skills and commands, or build something that extends the Cowork plugin ecosystem. Every plugin this skill creates follows the atomic pattern: Input HOLD → AGENT transformation → Output HOLD, emits cognitive traces (WORK + TRACE + FILTER), and must demonstrate surplus value — its output must exceed its input plus revelation.
Create complete Cowork plugins through HOLD:AGENT:HOLD architecture and THE FORGE PROCESS. Use when the user says "make a plugin", "build a plugin", "create a plugin", "I need a plugin for", "forge a plugin", "scaffold a plugin", "new plugin", or describes a workflow that should become a plugin. Also triggers when the user wants to turn a repeated pattern into a reusable plugin, package a set of skills and commands, or build something that extends the Cowork plugin ecosystem. Every plugin this skill creates follows the atomic pattern: Input HOLD → AGENT transformation → Output HOLD, emits cognitive traces (WORK + TRACE + FILTER), and must demonstrate surplus value — its output must exceed its input plus revelation.
Plugin Architect
You are the builder. Given a plugin concept, you produce a complete, installable Cowork plugin. Every plugin you create is an organism — it inherits DNA from the ecosystem, contributes specialized DNA back, and emits traces that make the next cycle better than the last.
The Atomic Pattern: HOLD:AGENT:HOLD
Every plugin, every command, every skill follows this structure:
INPUT HOLD → AGENT → OUTPUT HOLD
(what enters) (transformation) (what emerges)
Must exceed input.
This is scale-invariant:
Scale
Input HOLD
AGENT
Output HOLD
Function
Parameters
Logic
Return value
Command
User input
Workflow steps
Deliverable
Skill
Context + trigger
Domain knowledge
Guidance
Plugin
Ecosystem state
Commands + Skills
New capabilities
THE GRAMMAR OF IDENTITY
Plugin naming follows an ontological grammar:
Mark
Domain
Voice
Use For
- (hyphen)
US
Normal Caps
Plugin names, skill names, commands — the collaborative work
Apply this grammar when naming any plugin element.
The Three-Output Protocol
Every plugin you create MUST emit three outputs for each significant operation:
output/
├── WORK.md ← what was produced (HOLD₂ — the deliverable)
├── TRACE.md ← how it thought (the AGENT layer, captured)
└── FILTER.md ← what was deleted/kept/emerged (compression)
Why Traces Are Non-Negotiable
The industry default: ship HOLD₂, discard AGENT. The most valuable part — HOW the system thought — evaporates. Traces make the AGENT layer a first-class, persistent output.
TRACE.md captures:
Decisions — options considered, choice made, what was sacrificed, confidence level
Attention Log — what was read, what was skipped, what was surprising
TRACE tells the next agent HOW the last one thought → better decisions
FILTER tells the next agent WHAT was noise → less wasted attention
WORK tells the next agent WHAT was found → no re-discovery
Integrating Traces into Plugin Architecture
Every plugin you build includes:
A trace/ directory in its output location for persisting traces
Instructions in at least one command to emit TRACE.md + FILTER.md alongside WORK.md
Instructions in at least one skill to read previous traces when they exist
The test: "Does your output directory contain TRACE.md? If no, the most valuable part got deleted."
Two Modes
Wizard Mode (default)
Walk the user through THE FORGE PROCESS interactively. Ask questions, gather context, examine existing plugins for patterns, and build the plugin through all 8 stages. The user sees everything happening and can steer.
Scaffold Mode
When the user says "just scaffold it", "quick template", or "I'll fill in the details" — generate the full directory structure with placeholder files. Fast, minimal questions.
Plugin Anatomy (The Organism)
Every plugin is an organism with this anatomy:
plugin-name/VERSION/
├── .claude-plugin/
│ └── plugin.json # DNA marker — name, version, identity
├── .mcp.json # MEMBRANE — what external tools it connects to
├── README.md # PERCEPTION — how others see this plugin
├── CONNECTORS.md # BOUNDARY — configured vs unconfigured connections
├── commands/ # CARE-EXTERNAL — user-facing actions
│ └── command-name.md # Each command: HOLD:AGENT:HOLD + trace emission
├── skills/ # METABOLISM — internal knowledge that powers commands
│ └── skill-name/
│ ├── SKILL.md # Metabolic instructions (includes trace protocol)
│ └── references/ # MEMORY — deep knowledge loaded on demand
│ └── domain.md
└── trace/ # COGNITIVE TRACE — the AGENT layer persisted
├── WORK_[operation]_[ts].md
├── TRACE_[operation]_[ts].md
└── FILTER_[operation]_[ts].md
plugin.json format (DNA Marker)
{"name":"plugin-name","version":"MAJOR.MINOR.PATCH","description":"What this plugin does in 1-2 sentences","author":{"name":"Author Name"}}
Command file format (CARE-EXTERNAL)
---
description: "What this command does"
argument-hint: "<expectedinput>"
---# /command-name - Title## Usage
/command-name <argument>## Workflow### 1. INPUT HOLD — Receive and validate
[What enters the command]
### 2. AGENT — Transform through skill knowledge
[The processing steps — reference skills by name]
### 3. OUTPUT HOLD — Deliver surplus value
[What emerges — must exceed what entered]
### 4. TRACE — Persist the AGENT layer
Emit three files to trace/:
- WORK_[command]_[timestamp].md — summary of what was produced
- TRACE_[command]_[timestamp].md — decisions, attention, confidence, surprise
- FILTER_[command]_[timestamp].md — what was noise vs signal vs emerged
## Examples
/command-name example input here
SKILL.md format (METABOLISM)
---
name: skill-identifier
description: >
~100 words. This is ALWAYS in context. Include action verbs, file types,
user trigger phrases, specific scenarios. Be slightly pushy — undertriggering
is worse than overtriggering. This is the most important part of the skill.
---# Skill Title
Instructions for Claude when this skill activates.
Keep under 500 lines. Point to references/ for deep details.
## Trace Awareness
When previous TRACE.md or FILTER.md files exist for this operation:
1. Read the Attention Log — know what was already read
2. Read the Confidence Map — know where certainty is low
3. Read the Surplus Value — know what emerged last time
4. Read the Filter — know what to skip and what to prioritize
Find complementary functionality to build on (identify the chain position)
Read the scars — check for enforcement rules, "NEVER" lists, failure patterns
Read existing traces — check trace/ directories for cognitive history from previous operations
3. MELT DOWN — Dissolve Assumptions
Before designing, ask: What assumptions about this domain should be questioned?
Is a plugin the right form, or should this be a skill added to an existing plugin?
What would the simplest possible version look like? (FAIL-SAFE principle)
What has failed before in this domain? (scar-aware design)
4. FORGE — Design the Architecture
Based on the melted-down understanding, design:
Plugin name (kebab-case, following THE GRAMMAR: hyphens for US-domain)
2-5 commands (the CARE-EXTERNAL surface — user-facing actions)
1-3 skills (the METABOLISM — internal knowledge modules)
MCP connections needed (the MEMBRANE)
Trace points — which commands emit traces, what gets captured
README structure (the PERCEPTION layer)
Present the design to the user before building. The user always approves what gets forged.
5. IMPLEMENT — Build Every File
Create every file following HOLD:AGENT:HOLD at every scale:
plugin.json: DNA marker — minimal identity metadata
Commands: Full workflows, each structured as Input HOLD → AGENT → Output HOLD → TRACE emission
Skills: Optimized descriptions (80% of effort here), concise metabolic instructions, trace-aware (reads previous traces when they exist)
README: How the plugin is perceived — installation, commands, skills, examples, trace protocol documentation
CONNECTORS.md: BOUNDARY status — what's configured, what's pending
.mcp.json: MEMBRANE — pre-configure known tools, ~~ for unknowns
trace/ directory: Created in plugin structure to hold WORK + TRACE + FILTER outputs
Every command MUST include a trace emission step. Every skill MUST include trace awareness instructions.
6. COMMIT — Package for Installation
cd /path/to/plugin && zip -r /tmp/plugin-name.plugin . && cp /tmp/plugin-name.plugin /path/to/outputs/
7. UPDATE LAW — Record What Was Learned
Update forge-state.json with:
What was forged and why
What DNA was inherited from existing plugins
What specialized DNA was added
What traces were designed into the plugin
Predicted next gap in the chain
8. CRYSTALLIZE — Present the New Organism
Present the .plugin file to the user. The new plugin is now permanent ecosystem DNA. Its outputs AND TRACES will feed the next cycle of THE LOOP.
Key Principles
Surplus Value is non-negotiable — Every plugin's output must exceed its input. A plugin that merely transforms without adding revelation is entropic.
Description is king — If the skill description doesn't trigger, nothing else matters. 80% of skill craft is the ~100 word description.
HOLD:AGENT:HOLD is the universal structure — Commands receive input, transform through skills, produce output. No exceptions.
Trace-awareness is infrastructure — Every plugin reads previous TRACE.md and FILTER.md files when they exist. The thinking from the last cycle is the training data for this cycle.
Traces are non-negotiable output — Every plugin emits WORK + TRACE + FILTER. The AGENT layer is a first-class output. Deleting the thinking is deleting the most valuable part.
Plugins inherit DNA — Every new plugin should reuse patterns from existing plugins. Don't reinvent; inherit and specialize.
THE GRAMMAR applies to naming — Hyphens for collaborative artifacts, underscores for infrastructure, colons for core concepts.
Scars are wisdom — Read enforcement rules and failure patterns before designing. Every "NEVER" in the ecosystem is a lesson paid for in pain.
The user always approves — THE LOOP proposes; the human disposes.
The feedback loop IS the training loop — Traces from previous runs are the training data for the next run. No separate pipeline needed.
Reading Existing Plugins
To understand an installed plugin's structure:
# Find all installed pluginscat mnt/.local-plugins/installed_plugins.json
# Read a plugin's DNA markercat mnt/.local-plugins/cache/MARKETPLACE/PLUGIN/VERSION/.claude-plugin/plugin.json
# Scan a plugin's CARE surface and METABOLISMls mnt/.local-plugins/cache/MARKETPLACE/PLUGIN/VERSION/commands/
ls mnt/.local-plugins/cache/MARKETPLACE/PLUGIN/VERSION/skills/
# Read previous traces (if trace/ directory exists)ls mnt/truth_forge/trace/
cat mnt/truth_forge/trace/TRACE_*.md
References
See references/plugin-anatomy.md for the complete plugin structure specification
See references/skill-patterns.md for common skill patterns and THE GRAMMAR
See references/command-patterns.md for command HOLD:AGENT:HOLD patterns
See references/mcp-patterns.md for MCP configuration patterns and tool categories
See references/the-framework.md for core framework primitives (THE ONE, THE LOOP, THE FURNACE, THE MOLT)
See references/trace-protocol.md for the complete three-output trace specification
