| name | add-framework-development |
| description | Internal skill for developing ADD framework artefacts (commands, skills, agents, scripts). Use when add-framework--plan analyzes viability of new framework features, when add-framework--build implements framework artefacts, or when creating/modifying commands, skills, or agents. Always use this skill before proposing or implementing changes to the framework itself. |
Framework Development โ Internal Reference
Operational knowledge for creating and modifying ADD framework artefacts. NOT distributed to users โ exists so add-framework--plan assesses viability and add-framework--build implements correctly.
When to Use
add-framework--plan analyzing if a proposal is technically viable (STEP 0 and STEP 2)add-framework--build implementing a new command, skill, agent, or script- Modifying existing framework artefacts (commands, skills, agents)
- Deciding WHAT TYPE of artefact to create for a given need
- Understanding how the build pipeline distributes artefacts to providers
When NOT to Use
- Implementing user-facing features (backend/frontend code) โ use development skills directly
- Understanding what artefacts exist โ use
add-ecosystem skill (ecosystem map)
- Writing prompts for commands โ use
building-commands skill (prompt engineering patterns)
- Running the project โ use
CLAUDE.md (project standards and conventions)
0. Decision Framework โ What to Create?
This is the FIRST question add-framework--plan must answer. Wrong artefact type = wasted effort.
| Need | Create | Why |
|---|
| Orchestrate a multi-step workflow with gates and user interaction | Command | Commands control execution flow, enforce gates, dispatch agents |
| Teach patterns/rules that multiple commands need | Skill | Skills are reusable knowledge packs loaded by commands and agents |
| Specialize an agent with restricted tools, model, and memory | Agent | Agents are isolated specialists with persistent project memory |
| Automate a deterministic task (no LLM reasoning needed) | Script | Scripts are bash, fast, predictable, no token cost |
Decision Tree
Does it need LLM reasoning?
โโโ NO โ Script (.codeadd/scripts/)
โโโ YES
โโโ Does it orchestrate a workflow with multiple steps/gates?
โ โโโ YES โ Command
โโโ Does it need to run in isolated context with restricted tools?
โ โโโ YES โ Agent
โโโ Is it reusable knowledge that commands/agents consume?
โโโ YES โ Skill
Common Mistakes in Classification
| Mistake | Why it's wrong | Correct approach |
|---|
| Creating a command for something that's just knowledge | Commands orchestrate; if there's no workflow, it's a skill | Create a skill, let commands load it |
| Creating an agent for a one-off task | Agents have overhead (spawn, memory); overkill for simple tasks | Use inline execution in the command |
| Creating a skill that tries to execute steps | Skills teach, they don't execute; execution is commands' job | Split: skill for knowledge, command for workflow |
| Creating a script for something that needs context | Scripts can't reason about code or make judgment calls | Create a command or agent instead |
Artefact Types
| Type | Source path | Format | Count |
|---|
| Command | framwork/.codeadd/commands/{name}.md | Markdown with structured sections | 19 |
| Skill | framwork/.codeadd/skills/{name}/SKILL.md | Markdown with YAML frontmatter | 39 |
| Agent | framwork/.codeadd/agents/{name}-agent.md | Markdown with YAML frontmatter | 15 |
| Script | framwork/.codeadd/scripts/{name}.sh | Bash | variable |
Internal-only artefacts (NOT distributed): .claude/skills/, .claude/commands/
1. Command Structure
Commands are workflow orchestrators. They load skills, dispatch agents, enforce gates, and produce documents.
Anatomy
# [Command Title]
> **LANG:** Respond in user's native language (detect from input). Tech terms always in English.
[One-line description]
## โโโ MANDATORY SEQUENTIAL EXECUTION โโโ
STEP 1: [Action] โ [What happens]
STEP 2: [Action] โ [What happens]
## STEP 1: [Title]
### 1.1: [Subsection]
**GATE: [gate_name]** - MANDATORY before [condition]
**GATE CHECK:** [what must be true?] IF NO -> STOP.
**DISPATCH AGENT: @[agent-name]**
**WAIT:** [condition before continuing]
## Rules
ALWAYS:
- [imperative]
NEVER:
- [prohibition]
Key Elements
Frontmatter โ > **KEY:** value format (not YAML):
LANG, OWNER, ARCHITECTURE REFERENCE, DOCS, MODE
No ## Spec section โ DO NOT add a top-of-file ## Spec JSON metadata block to commands or skills. Output paths, modes, schemas belong in the frontmatter description and STEP body. Nothing programmatically consumes ## Spec. See building-commands skill for the prohibition.
Tool Prohibitions โ โโโ ABSOLUTE PROHIBITIONS block:
โ DO NOT USE: [tool] for [context]
โ
DO: [correct alternative]
Gates โ Named checkpoints that block execution:
**GATE: feature_identified** โ named gate**GATE CHECK:** [condition]? IF NO -> STOP. โ inline check
Subagent Dispatch โ Named agents with fallback:
| Area | Named Agent | Fallback |
|------|-------------|----------|
| Database | @database-agent | Generic subagent + skill add-database-development |
**DISPATCH AGENT: @database-agent**
Prompt: [full prompt with ${FEATURE_ID}, output path, format template]
Wait Points โ **WAIT:** [condition] blocks execution until artifact exists.
Output Paths โ Always use ${FEATURE_ID} variable:
docs/features/${FEATURE_ID}/plan.mddocs/features/${FEATURE_ID}/design.md- Temp files:
plan-database.md, plan-backend.md, etc.
Completion โ Always reference add-ecosystem skill for next steps.
2. Skill Structure
Skills are knowledge packs loaded into context. They teach patterns, not execute workflows.
Anatomy
---
name: add-[kebab-case]
description: "Use when..."
category: [meta|technique|reference|discipline]
---
# [skill-name] โ [Subtitle]
## When to Use
- [specific scenario 1]
- [specific scenario 2]
## When NOT to Use
- **[anti-pattern]** โ use `/add.[other]` instead
## [Content Sections]
## Common Rationalizations (BLOCKED)
| Excuse | Reality |
|--------|---------|
| "[excuse]" | [why it's wrong] |
Tiers
| Tier | Lines | Structure | Example |
|---|
| 1 (simple) | <100 | Single SKILL.md, basic sections | add-commit |
| 2 (medium) | 100-300 | JSON spec blocks, templates, checklists | add-planning |
| 3 (complex) | 300+ | SKILL.md dispatcher + reference subdocs | add-ux-design |
Subdoc pattern (canonical โ references/, any tier):
add-qa/
SKILL.md โ dispatcher/index
references/coordinator.md โ reference doc
โ One convention only: references/. It is what add-skill-creator prescribes (anti-pattern table + pre-deploy checklist) and what the majority of skills use โ add-doc-schemas, add-investigation, add-skill-creator, add-backend-architecture, add-frontend-architecture, add-subagent-driven-development, add-qa. New subdocs go there regardless of tier; a Tier-2 skill that outgrows one file uses references/ too, it does not go flat.
Flat siblings are legacy, not an alternative: add-ux-design (14 files), add-architecture-discovery, add-health-check, add-stripe. Adding a subdoc to one of those may follow its existing flat layout โ mixing both inside one skill is worse than either. Do NOT introduce a flat subdoc in a skill that has none.
scripts/build.js (skillStrategy.postWrite) copies subdirs and siblings recursively, so both layouts distribute identically โ the choice is purely about authoring consistency. Reference a subdoc as {{skill:NAME/references/FILE.md}} (the {{skill:}} resolver matches greedily past /).
Conventions
- Structured data: Inline JSON
{"key":"value"} for lookup tables, checklists, scoring
- Anti-rationalization: Tables with
Excuse | Reality columns
- Enforcement:
โ ๏ธ REGRA OBRIGATรRIA, NEVER/MUST, **OBRIGATรRIO**
- Cross-references:
{{skill:add-[name]/[file]}} for files, /add.[name] for commands
- Token efficiency: JSON minified, max 10 words per description, no decorative formatting
--yolo (scoped, NOT a general convention): an autonomy flag supported ONLY by add.review and add.autopilot (which forwards it). Plan 0057 removed it from add.plan because a design pipeline with a skip-all-confirmations flag can silently ship an unreviewed contract. Do NOT add it to new commands, and do NOT assume a command accepts it โ grep the target command first.
3. Agent Structure
Agents are specialized subagents with preloaded skills, tool restrictions, and persistent memory. Claude Code native feature.
Anatomy
---
name: [name]-agent
description: [1-2 sentences โ what it does + when Claude should use it]
model: [inherit|sonnet|haiku|opus]
tools: [comma-separated tool list]
disallowedTools: [tools to deny]
skills:
- add-[skill-1]
- add-[skill-2]
memory: project
---
[System prompt โ body becomes the agent's instructions]
[Include domain knowledge, patterns, output format expectations]
Frontmatter Fields
| Field | Required | Values |
|---|
| name | yes | [name]-agent (kebab-case) |
| description | yes | Trigger phrase โ "use proactively" encourages auto-delegation |
| model | no | inherit (full reasoning), sonnet (balanced), haiku (fast/cheap) |
| tools | no | Allowlist: Read, Glob, Grep, Bash, Write, Edit |
| disallowedTools | no | Denylist: Write, Edit, NotebookEdit for read-only agents |
| skills | no | Array of skill names to preload into context |
| memory | no | project (.claude/agent-memory/), user, local |
| maxTurns | no | Limit agentic turns |
| permissionMode | no | default, acceptEdits, dontAsk, bypassPermissions, plan |
| hooks | no | Lifecycle hooks scoped to agent |
| mcpServers | no | MCP servers (inline or reference) |
| background | no | true to always run as background task |
| effort | no | low, medium, high, max |
| isolation | no | worktree for isolated git worktree |
Constraints
- Agents CANNOT spawn other agents (leaf nodes only)
- Commands orchestrate; agents execute and return
- Agents don't inherit parent's skills โ only what's in their
skills: field
- Agent source filename:
{name}-agent.md
Design Guidelines
| Need | Model | Tools | Memory |
|---|
| Exploration/discovery | haiku | Read-only | project |
| Code review/audit | sonnet | Read-only | project |
| Implementation | inherit | All | project |
| Architecture decisions | inherit | Read-only | project |
| Design proposals | sonnet | Read/Write | project |
Plugin Agent-Injection Markers
Plugins (see CLAUDE.md โ Plugin System) can inject capability into agent definitions, not just commands โ carrying an external-tool capability across the commandโsubagent dispatch boundary (agents never see a command's injected fragment). To make an agent a plugin injection target:
- Add a
<!-- plugin:PLUGIN:SECTION --> / <!-- /plugin:PLUGIN:SECTION --> marker pair to the agent source body. Markers are stripped at build โ extractInjectionPoints() records each as a content anchor in framwork/.codeadd/injection-points.json; the built agent files ship marker-free and injection is anchored to adjacent prose post-install.
- Place the marker on its own line (an inline marker shown inside prose/code as documentation is ignored โ only standalone-line markers are injection points), and ensure the line directly above it is plain text, not a
{{cmd:}}/{{skill:}}/{{addpath:}} variable (the build walks past variable lines and fails loud if no variable-free adjacent line exists).
- Author a per-agent fragment at
framwork/.codeadd/plugins/{plugin}/fragments/agents/{agent}.md whose <!-- section:SECTION --> matches the marker.
- Declare the target in the catalog entry's
agents array ({ agent, sections }).
- Exclusion is by omission: an agent with a tool allowlist that blocks MCP (e.g.
tools: Glob, Read), or whose purpose is not the code graph, simply carries no marker โ so the build emits no sidecar entry for it and it is never injected. Never add an injection marker to an MCP-blocked agent.
- After adding/moving a marker, rebuild (
node scripts/build.js) to regenerate the sidecar.
Only providers with an agentsSubdir (currently Claude) receive agent injection.
4. Build Pipeline
Why provider-map.json Governs Everything
The framework is distributed to 15 providers (Claude, Codex, Gemini, Copilot, Cursor, Kiro, etc.). Each provider has different directory structures, file formats, and capabilities. A single source file in .codeadd/ must produce correct output for ALL providers.
Every decision when writing commands, skills, or agents must consider:
- Will the file paths resolve correctly across providers? (use
{{cmd:}} / {{skill:}} variables)
- Does this feature depend on a capability not all providers have? (check
capabilities)
- Will the format transform correctly? (md โ toml for Gemini)
provider-map.json is the single source of truth โ it determines where files go, how they're transformed, and what capabilities are available.
Source โ Provider Installation
framwork/.codeadd/ โ SOURCE OF TRUTH (you write here)
โโโ agents/ โ agent definitions
โโโ commands/ โ command definitions
โโโ skills/ โ skill modules
โโโ scripts/ โ bash scripts
โ node scripts/build.js (reads provider-map.json)
โ per provider: lint โ strip comments โ resolve paths โ transform format โ write
framwork/.claude/ โ Claude Code output
framwork/.agents/ โ OpenAI Codex output
framwork/.gemini/ โ Gemini CLI output (TOML!)
framwork/.github/ โ GitHub Copilot output
[... 15 providers total]
provider-map.json Structure
{
"providers": {
"claude": {
"dir": "framwork/.claude",
"commands": "commands/{name}.md",
"skills": "skills/{name}/SKILL.md",
"agents": "agents/{name}.md",
"capabilities": {
"hooks": true,
"agentDispatch": true,
"mcp": true,
"nativeFormat": "md",
"slashCommands": true
}
}
},
"commands": { "add.build": { "description": "..." } },
"skills": { "add-backend-development": {} },
"agents": { "backend-agent": { "description": "..." }}
}
How Output Paths Vary Per Provider
The same command gets installed to DIFFERENT paths depending on the provider:
| Provider | Commands pattern | Skills pattern | Agents pattern |
|---|
| Claude | commands/{name}.md | skills/{name}/SKILL.md | agents/{name}.md |
| Codex | skills/{name}/SKILL.md | skills/{name}/SKILL.md | โ |
| Antigrav | skills/{name}/SKILL.md | skills/{name}/SKILL.md | โ |
| KiloCode | workflows/{name}.md | skills/{name}/SKILL.md | โ |
| Copilot | agents/{name}.md | skills/{name}/SKILL.md | โ |
| Gemini | commands/{name}.toml | skills/{name}/SKILL.md | โ |
| Kiro | prompts/{name}.md | skills/{name}/SKILL.md | โ |
| Windsurf | workflows/{name}.md | skills/{name}/SKILL.md | โ |
When agents is null โ provider doesn't support agents โ build.js skips agent installation for that provider.
Format Transformers
Build.js transforms content based on capabilities.nativeFormat:
md transformer (most providers): Wraps content with YAML frontmatter:
---
description: [from provider-map.json]
---
[original content]
If the output path contains SKILL.md (e.g., Codex commands โ skills/{name}/SKILL.md), adds name: field:
---
name: add.build
description: Development execution specialist...
---
toml transformer (Gemini only): Wraps content in TOML format:
description = "Development execution specialist..."
prompt = """
[original content]
"""
Agent passthrough: Agents keep their own frontmatter (name, model, tools, skills, memory) โ no wrapping applied.
Resource Path Variables โ When and How to Use
The problem: You write a command that references another command or skill. If you hardcode .claude/commands/add.plan.md, it breaks for Codex (which puts commands in .agents/skills/add.plan/SKILL.md).
The solution: Build-time variables that resolve per provider.
{{cmd:NAME}} โ Reference a command
<!-- IN YOUR SOURCE FILE (.codeadd/commands/add.build.md): -->
Read {{cmd:add.plan}} for the technical plan.
<!-- AFTER BUILD for Claude: -->
Read .claude/commands/add.plan.md for the technical plan.
<!-- AFTER BUILD for Codex: -->
Read .agents/skills/add.plan/SKILL.md for the technical plan.
<!-- AFTER BUILD for Gemini: -->
Read .gemini/commands/add.plan.toml for the technical plan.
{{skill:NAME/FILE}} โ Reference a skill file
<!-- IN YOUR SOURCE FILE: -->
Load {{skill:add-backend-development/SKILL.md}} before implementation.
<!-- AFTER BUILD for Claude: -->
Load .claude/skills/add-backend-development/SKILL.md before implementation.
<!-- AFTER BUILD for Copilot: -->
Load .github/skills/add-backend-development/SKILL.md before implementation.
Scripts โ NO variable needed
Scripts live at .codeadd/scripts/ and this path is the same for all providers:
bash .codeadd/scripts/status.sh
Provider Capabilities โ What to Check When Writing Commands
Not all providers support all features. When a command uses a capability, it MUST consider providers that lack it:
| Capability | Providers WITHOUT it | Impact on commands |
|---|
agentDispatch | Gemini, Shai, Windsurf | Cannot dispatch subagents โ commands that dispatch @agents won't work |
hooks | Antigrav, KiloCode, Bob, Qwen, Shai, Windsurf | No lifecycle hooks โ pre/post tool hooks unavailable |
mcp | Gemini | No MCP servers โ agents with mcpServers: won't connect |
slashCommands | Codex, Bob, Copilot | No /command invocation โ must use natural language |
When writing a command that dispatches agents:
- The command works on providers with
agentDispatch: true
- On providers without it, the command's content still loads but subagent dispatches will be ignored by the runtime
- Always include fallback guidance: "If agent dispatch is unavailable, execute inline"
Build Process Step by Step (scripts/build.js)
readMap() โ loads framwork/provider-map.json- For each resource (command/skill/agent):
a. Read source from
.codeadd/
b. lintResourcePaths() โ warns if raw .codeadd/commands/ or .codeadd/skills/ paths found (should use {{cmd:}} / {{skill:}})
c. extractInjectionPoints() โ for commands/agents: records each feature:/plugin: marker as a content anchor into framwork/.codeadd/injection-points.json (then the markers are stripped)
d. stripHtmlComments() โ removes ALL <!-- --> comments (incl. injection markers) + collapses blank lines (token savings)
e. resolveResourcePaths() โ replaces {{cmd:NAME}} and {{skill:NAME/FILE}} for each provider
f. Transform โ applies md or toml transformer based on provider's nativeFormat
g. Write โ outputs to provider directory
h. postWrite โ for skills: copies extra subdocs (reference files, scripts, etc.)
Registering New Artefacts
Every new command, skill, or agent MUST be registered in provider-map.json:
"commands": { "add.mycommand": { "description": "What it does in one line" } }
"skills": { "add-my-skill": {} }
"agents": { "my-agent": { "description": "What it does in one line" } }
If not registered, build.js won't process the file and it won't be distributed to any provider.
Selective Provider Distribution
By default, artefacts go to ALL providers. To restrict to specific providers, add a providers array:
"commands": {
"add.mycommand": {
"description": "...",
"providers": ["claude", "codex", "cursor"]
}
}
Pre-Build Validation Checklist
5. Creating New Artefacts
New Command
- Create
framwork/.codeadd/commands/{name}.md following command anatomy
- Register in
framwork/provider-map.json โ commands section
- Run
node scripts/build.js to distribute
- Update
add-ecosystem skill with new command entry
New Skill
- Create
framwork/.codeadd/skills/{name}/SKILL.md following skill anatomy
- For Tier 3: add reference subdocs in same directory
- Register in
framwork/provider-map.json โ skills section
- Run
node scripts/build.js to distribute
- Update
add-ecosystem skill with new skill entry
New Agent
- Create
framwork/.codeadd/agents/{name}-agent.md following agent anatomy
- Register in
framwork/provider-map.json โ agents section
- Run
node scripts/build.js to distribute
- Update
add-ecosystem skill with new agent entry
- Update commands that should dispatch this agent (add
@{name}-agent to dispatch table)
Internal-Only Artefact
- Create directly in
.claude/skills/{name}/SKILL.md or .claude/commands/{name}.md
- Do NOT register in provider-map.json
- Do NOT add to framwork/.codeadd/
- These are NOT distributed by build.js
6. Runtime Behavior โ How Artefacts Interact
How Commands Load Skills
Commands instruct the LLM to read skill files. This is NOT automatic โ it's a prompt instruction:
<!-- In a command source file: -->
## STEP 1: Load Context
Read {{skill:add-backend-development/SKILL.md}} before implementation.
At runtime, the LLM sees the resolved path (e.g., .claude/skills/add-backend-development/SKILL.md) and uses the Read tool to load the file into its context. The skill content then informs subsequent decisions.
Key distinction:
- Command
Read instruction = LLM reads file at runtime (on-demand, costs tokens)
- Agent
skills: frontmatter = skill is preloaded into agent context at spawn (automatic, always present)
How Commands Dispatch Agents
Commands use the Agent tool (formerly Task tool) to spawn subagents:
**DISPATCH AGENT: @backend-agent**
Prompt: You are implementing ${TASK_DESCRIPTION} for feature ${FEATURE_ID}...
The LLM interprets this and calls the Agent tool with subagent_type: "backend-agent". If the agent exists in .claude/agents/, it spawns with its frontmatter config. If not, the fallback (generic subagent) is used.
Parallel dispatch pattern โ commands that dispatch multiple agents MUST instruct:
**CRITICAL:** Send ALL Agent tool calls in a SINGLE message for parallel execution.
How Scripts Are Invoked
Commands invoke scripts via Bash tool:
## STEP 1: Run Context Mapper
```bash
bash .codeadd/scripts/status.sh
status.sh is the most common โ returns project context (feature ID, branch, owner profile, etc.) as key-value pairs that commands parse to set variables like ${FEATURE_ID}, ${OWNER_LEVEL}.
Runtime Loading Order (typical command)
1. Command prompt loaded into LLM context
2. LLM runs status.sh via Bash โ gets project variables
3. LLM reads skill files via Read โ gets domain knowledge
4. LLM dispatches @agents via Agent tool โ specialists execute in isolation
5. LLM waits for agent results โ continues to next step
6. LLM enforces gates โ blocks or proceeds
7. LLM writes output docs via Write/Edit tools
7. Common Errors and How to Prevent Them
Build Pipeline Errors
| Error | Symptom | Prevention |
|---|
| Forgot to register in provider-map.json | File exists in .codeadd/ but never appears in provider dirs | ALWAYS register BEFORE running build |
Used raw path .codeadd/commands/add.plan.md | Works on Claude, breaks on Codex/Gemini/etc. | Use {{cmd:add.plan}} variable |
Used raw path .codeadd/skills/add-x/SKILL.md | Works on Claude, breaks on other providers | Use {{skill:add-x/SKILL.md}} variable |
Agent file not named {name}-agent.md | build.js can't find the source file | Follow naming convention exactly |
Skill dir name doesn't match name: in frontmatter | Confusion between directory and metadata | Keep them identical |
Command Authoring Errors
| Error | Symptom | Prevention |
|---|
| No gates before critical actions | Agent skips validation, produces broken output | Add **GATE CHECK:** before every irreversible step |
| No tool prohibitions | Agent uses Write when it should only Read, or edits wrong files | Add โโโ ABSOLUTE PROHIBITIONS block |
| No fallback for agent dispatch | Command fails on providers without agentDispatch | Always include fallback table with generic subagent option |
| Dispatching agents without loading docs first | Agent gets no context, produces generic output | Add **WAIT:** after doc loading, before dispatch |
Missing MANDATORY SEQUENTIAL EXECUTION block | Agent skips steps or reorders them | Always include the numbered step summary at top |
| No completion/next-steps section | User doesn't know what to do after command finishes | Reference add-ecosystem skill for flow guidance |
Skill Authoring Errors
| Error | Symptom | Prevention |
|---|
| No "When NOT to Use" section | Skill triggers in wrong contexts, wastes tokens | Always list anti-patterns with delegation to correct skill |
| Skill tries to execute (has steps/gates) | Conflicts with command orchestration | Skills teach patterns; commands execute workflows |
| No anti-rationalization section (complex skills) | LLM finds excuses to skip rules | Add Common Rationalizations (BLOCKED) table |
| Tier 3 skill with everything in one file | Too many tokens loaded for simple queries | Split into SKILL.md dispatcher + reference subdocs |
| No structured data (inline JSON) for lookup tables | Verbose markdown wastes tokens | Use minified JSON for checklists, scores, configs |
Agent Authoring Errors
| Error | Symptom | Prevention |
|---|
| Giving Write/Edit to a read-only agent | Reviewer modifies code (anti-pattern) | Use disallowedTools: Write, Edit, NotebookEdit |
No skills: in frontmatter | Agent has no domain knowledge, gives generic responses | Always preload relevant skills |
Using model: haiku for tasks needing deep reasoning | Shallow analysis, missed edge cases | Use inherit or opus for architecture/implementation |
| Agent prompt duplicates skill content | Wastes tokens; content drifts out of sync with skill | Keep prompt minimal; let preloaded skills provide knowledge |
No memory: project for agents that should learn | Agent rediscovers same patterns every session | Add memory for agents that benefit from project context |
8. Patterns to Enforce
Token Efficiency (MANDATORY for all artefacts)
- JSON minified for structured data:
{"key":"value"} not formatted
- Max 10 words per description in technical specs
- No decorative formatting (ASCII art, excessive dashes, emoji headers)
- Reference don't repeat โ use
{{skill:}} and {{cmd:}} variables
- Compress examples: 1 excellent > 3 mediocre
- HTML comments
<!-- --> for source-only notes (stripped by build)
Anti-Rationalization (MANDATORY for commands and complex skills)
LLMs rationalize skipping steps. Every command/skill that controls agent behavior MUST include:
- Explicit tool prohibitions:
โ DO NOT USE: [tool] for [context]
- Gate checks that STOP execution:
**GATE CHECK:** [condition]? IF NO -> STOP.
- Rules section with
ALWAYS: and NEVER: lists
- For complex skills:
Common Rationalizations (BLOCKED) table
Reference: Load building-commands skill for detailed prompt engineering patterns.
Documentation Style Cache (MANDATORY for skills that produce documents)
Read โ Identify existing content โ Preserve โ Complement โ Update metadata.
NEVER recreate a document from scratch โ always extend what exists.
Named Agent Dispatch (MANDATORY for commands that dispatch agents)
Always include fallback table for providers without agent support:
| Area | Named Agent | Fallback |
|------|-------------|----------|
| [area] | @[name]-agent | Generic subagent + skill add-[area]-development |
Cross-Artefact Impact (MANDATORY for any change)
When creating or modifying any artefact, check:
provider-map.json โ is it registered? description accurate?add-ecosystem skill โ does the ecosystem map reflect the change?- Commands that reference it โ do dispatch tables, skill loads, or script calls need updating?
- Agents that preload it โ does the
skills: array need updating?
- Run
node scripts/build.js โ any LINT warnings?
