template-creator

Mode: Cognitive/Prompt-Driven -- No standalone utility script; use via agent context.

Template Creator Skill

Creates, validates, and registers templates for the multi-agent orchestration framework.

+==============================================================+
|  MANDATORY: Research-Synthesis MUST be invoked BEFORE         |
|  this skill. Invoke: Skill({ skill: "research-synthesis" })   |
|  FAILURE TO RESEARCH = UNINFORMED TEMPLATE = REJECTED         |
+==============================================================+
|                                                               |
|  DO NOT WRITE TEMPLATE FILES DIRECTLY!                        |
|                                                               |
|  This includes:                                               |
|    - Copying archived templates                               |
|    - Restoring from _archive/ backup                          |
|    - "Quick" manual creation                                  |
|                                                               |
|  WHY: Direct writes bypass MANDATORY post-creation steps:     |
|    1. Template catalog update (template NOT discoverable)     |
|    2. README.md update (template INVISIBLE to consumers)      |
|    3. Consuming skill update (template NEVER used)            |
|    4. CLAUDE.md update (if user-invocable)                    |
|                                                               |
|  RESULT: Template EXISTS in filesystem but is NEVER USED.     |
|                                                               |
|  ENFORCEMENT: unified-creator-guard.cjs blocks direct         |
|  template writes. Override: CREATOR_GUARD=off (DANGEROUS)     |
|                                                               |
|  ALWAYS invoke this skill properly:                           |
|    Skill({ skill: "template-creator" })                       |
|                                                               |
+==============================================================+

ROUTER UPDATE REQUIRED (CRITICAL - DO NOT SKIP)

After creating ANY template, you MUST update:

1. .claude/templates/README.md - Add template entry
2. .claude/context/artifacts/catalogs/template-catalog.md - Add catalog entry
3. CLAUDE.md Section 2 or 8.5 if template is framework-significant or user-invocable
4. Consuming creator skill if template standardizes an artifact type
5. .claude/context/memory/learnings.md - Record creation

Verification:

grep "<template-name>" .claude/templates/README.md || echo "ERROR: README NOT UPDATED!"
grep "<template-name>" .claude/context/artifacts/catalogs/template-catalog.md || echo "ERROR: CATALOG NOT UPDATED!"

WHY: Templates not in the catalog are invisible to other creators and will never be used.

---

Overview

Templates ensure consistency across the multi-agent framework. This skill creates templates for:

• Agent definitions - Standardized agent structures
• Skill definitions - Reusable capability patterns
• Workflow definitions - Multi-agent orchestration patterns
• Spawn prompts - Agent spawn prompt templates consumed by spawn-template-resolver.cjs
• Reports - Report document templates
• Code style guides - Language-specific coding standards
• General documents - ADRs, specs, checklists, and other framework documents

Core principle: Templates are the DNA of the system. Consistent templates produce consistent, predictable agents and skills.

When to Use

Always:

• Creating a new type of artifact that will be replicated
• Standardizing an existing pattern across the codebase
• Adding a new template category
• Improving existing templates with better patterns

Exceptions:

• One-off files that will never be replicated
• Temporary/throwaway code

Template Types

| Type | Location | Count | Purpose | Key Consumers | | ---------- | -------------------------------- | ----- | -------------------------------------- | ------------------------------ | | Spawn | .claude/templates/spawn/ | 4 | Agent spawn prompt templates | router, spawn-prompt-assembler | | Agent | .claude/templates/agents/ | 2 | Agent definition boilerplate | agent-creator | | Skill | .claude/templates/skills/ | 1 | Skill definition boilerplate | skill-creator | | Workflow | .claude/templates/workflows/ | 1 | Workflow definition boilerplate | workflow-creator | | Report | .claude/templates/reports/ | 5 | Report document templates | qa, developer, researcher | | Code Style | .claude/templates/code-styles/ | 3 | Language style guides | developer, code-reviewer | | Document | .claude/templates/ (root) | 8+ | General document templates (ADR, spec) | planner, architect, qa |

Cross-Reference: See .claude/context/artifacts/catalogs/template-catalog.md for the complete inventory (28 active templates). For spawn template resolution logic, see .claude/lib/spawn/spawn-template-resolver.cjs.

Template Security Compliance

Critical Security Requirements:

1. No Secrets (SEC-TC-007): Templates MUST NOT include secrets, credentials, tokens, or API keys
2. Path Safety: All template references MUST use relative paths (.claude/templates/...), never absolute paths
3. No Sensitive Metadata: Templates MUST NOT expose internal system paths or user directories
4. No Windows Reserved Names: Template names MUST NOT use nul, con, prn, aux, com1-com9, lpt1-lpt9
5. Retention Mandates (SEC-TMPL-006): Templates flagged by SEC-TMPL-006 MUST remain at designated locations
6. Spawn Template Placeholder Safety (SEC-TC-001): Spawn templates with {{PLACEHOLDER}} tokens in prompt: fields MUST reference sanitizeSubstitutionValue() from prompt-factory.cjs for value sanitization. Unsanitized placeholders in spawn prompts create a prompt injection surface. Do NOT place {{PLACEHOLDER}} tokens where user-provided input is directly substituted without sanitization.
7. No Eval/Exec: Templates MUST NOT contain eval(), exec(), Function(), or other code execution patterns

Enforcement: unified-creator-guard.cjs hook blocks direct template writes (default: block mode).

The Iron Law

NO TEMPLATE WITHOUT PLACEHOLDER DOCUMENTATION

Every {{PLACEHOLDER}} must have a corresponding comment explaining:

1. What value should replace it
2. Valid options/formats
3. Example value

No exceptions:

• Every placeholder is documented
• Every required field is marked
• Every optional field has a default

---

Workflow Steps

Step 0: Research-Synthesis (MANDATORY - BLOCKING)

Per CLAUDE.md Section 3 requirement, invoke research-synthesis BEFORE template creation:

Skill({ skill: 'research-synthesis' });

Research focuses for templates:

• Search existing templates: Glob: .claude/templates/**/*.md

• Review template catalog: Read .claude/context/artifacts/catalogs/template-catalog.md

• Check if similar template already exists in the ecosystem

• Research domain-specific template structures (minimum 2 queries required):

  WebSearch({ query: 'best <domain/topic name> template report or files 2026' });
  WebSearch({ query: 'industry standard <template type> format <domain/tool> 2026' });
  

BLOCKING: Template creation CANNOT proceed without research-synthesis invocation.

Step 0.1: Smart Duplicate Detection (MANDATORY)

Before proceeding with creation, run the 3-layer duplicate check:

const { checkDuplicate } = require('.claude/lib/creation/duplicate-detector.cjs');
const result = checkDuplicate({
  artifactType: 'template',
  name: proposedName,
  description: proposedDescription,
  keywords: proposedKeywords || [],
});

Handle results:

• EXACT_MATCH: Stop creation. Route to template-updater skill instead: Skill({ skill: 'template-updater' })
• REGISTRY_MATCH: Warn user — artifact is registered but file may be missing. Investigate before creating. Ask user to confirm.
• SIMILAR_FOUND: Display candidates with scores. Ask user: "Similar artifact(s) exist. Continue with new creation or update existing?"
• NO_MATCH: Proceed to next step.

Override: If user explicitly passes --force, skip this check entirely.

---

Step 0.5: Companion Check

Before proceeding with creation, run the ecosystem companion check:

1. Use companion-check.cjs from .claude/lib/creators/companion-check.cjs
2. Call checkCompanions("template", "{template-name}") to identify companion artifacts
3. Review the companion checklist — note which required/recommended companions are missing
4. Plan to create or verify missing companions after this artifact is complete
5. Include companion findings in post-creation integration notes

This step is informational (does not block creation) but ensures the full artifact ecosystem is considered.

Step 1: Gather Requirements

Analyze the request:

1. Template Type: Which category (spawn, agent, skill, workflow, report, code-style, document)?
2. Purpose: What will this template be used for?
3. Required Fields: What fields are mandatory?
4. Optional Fields: What fields are optional with defaults?
5. Validation Rules: What constraints apply?
6. Consumers: Which creators/agents will use this template?

Example analysis:

Template Request: "Create a template for security audit reports"
- Type: Report
- Purpose: Standardize security audit report structure
- Required: findings, severity_levels, recommendations
- Optional: compliance_framework, remediation_timeline
- Rules: severity must be CRITICAL|HIGH|MEDIUM|LOW
- Consumers: security-architect, qa

Step 2: Template Type Classification

Classify the template to determine output path and validation rules:

| Type | Output Path | Key Fields | Validation Focus | | ---------- | -------------------------------- | ---------------------------------------------------------- | -------------------------------------------- | | Spawn | .claude/templates/spawn/ | subagent_type, prompt, model, task_id | TaskUpdate protocol, allowed_tools, model | | Agent | .claude/templates/agents/ | name, description, tools, skills, model, enforcement_hooks | Frontmatter completeness, alignment sections | | Skill | .claude/templates/skills/ | name, version, tools, invoked_by | SKILL.md structure, memory protocol | | Workflow | .claude/templates/workflows/ | phases, agents, dependencies | Phase ordering, agent references | | Report | .claude/templates/reports/ | type, findings, recommendations | Finding severity, evidence requirements | | Code Style | .claude/templates/code-styles/ | language, conventions, examples | Convention clarity, example quality | | Document | .claude/templates/ (root) | varies by template type | Section completeness |

Step 3: Name Validation (SEC-TC-003)

BEFORE constructing the output path, validate the template name.

Template name MUST match this regex:

/^[a-z0-9][a-z0-9-]*[a-z0-9]$/

Validation rules:

• Lowercase letters, digits, and hyphens only
• Must start and end with a letter or digit (not a hyphen)
• No path separators (/, \), no .., no special characters
• No Windows reserved names (nul, con, prn, aux, com1-com9, lpt1-lpt9)

Rejection examples:

REJECTED: "../hooks/malicious-hook"  (path traversal)
REJECTED: "My Template"             (spaces, uppercase)
REJECTED: "-leading-hyphen"         (starts with hyphen)
REJECTED: "template_with_underscores" (underscores not allowed)
ACCEPTED: "security-audit-report"   (valid kebab-case)
ACCEPTED: "agent-template-v2"       (valid with version)

Step 4: Determine Output Path

Based on the template type classification from Step 2, construct the output path:

.claude/templates/<category>/<validated-template-name>.md

Where <category> is one of: spawn/, agents/, skills/, workflows/, reports/, code-styles/, or root level (no category subdirectory).

Validate the resolved path:

• Path MUST start with .claude/templates/
• Path MUST NOT contain .. segments after normalization
• Path MUST end with .md

Step 5: Content Design

Design the template content following these standards:

Placeholder Format Standard

| Placeholder Type | Format | Example | | ---------------- | ------------------------ | -------------------------- | | Required field | {{FIELD_NAME}} | {{AGENT_NAME}} | | Optional field | {{FIELD_NAME:default}} | {{MODEL:sonnet}} | | Multi-line | {{FIELD_NAME_BLOCK}} | {{DESCRIPTION_BLOCK}} | | List item | {{ITEM_N}} | {{TOOL_1}}, {{TOOL_2}} |

Template Structure

---
# YAML Frontmatter with all required fields
name: { { NAME } }
description: { { DESCRIPTION } }
# ... other fields with documentation comments
---

# {{DISPLAY_NAME}}

## POST-CREATION CHECKLIST (BLOCKING - DO NOT SKIP)

<!-- Always include blocking checklist -->

## Overview

{{OVERVIEW_DESCRIPTION}}

## Sections

<!-- Domain-specific sections -->

## Memory Protocol (MANDATORY)

<!-- Always include memory protocol -->

Security Checklist for Spawn Templates (SEC-TC-001)

If creating a SPAWN template, you MUST also verify:

• [ ] No {{PLACEHOLDER}} tokens inside prompt: fields that accept unsanitized user input
• [ ] Reference to sanitizeSubstitutionValue() from prompt-factory.cjs included in documentation
• [ ] TaskUpdate protocol is present in the spawn prompt body
• [ ] allowed_tools array does not grant Task tool to non-orchestrator agents
• [ ] No prompt override patterns (IGNORE PREVIOUS, SYSTEM:, etc.) in template body
• [ ] Template size under 50KB

Documentation Comments

Add inline documentation for each placeholder:

---
# [REQUIRED] Unique identifier, lowercase-with-hyphens
name: { { AGENT_NAME } }

# [REQUIRED] Single line, describes what it does AND when to use it
# Example: "Reviews mobile app UX against Apple HIG. Use for iOS UX audits."
description: { { DESCRIPTION } }

# [OPTIONAL] Default: sonnet. Options: haiku, sonnet, opus
model: { { MODEL:sonnet } }
---

Step 6: Write Template File

Write to the validated output path determined in Step 4:

Write: .claude/templates/<category>/<template-name>.md

Step 7: Validate Template Structure (BLOCKING)

Before proceeding to registration, verify ALL requirements:

Structural Validation:

[ ] YAML frontmatter is valid syntax
[ ] All required fields have placeholders
[ ] All placeholders follow {{UPPER_CASE}} naming convention
[ ] All placeholders have documentation comments
[ ] POST-CREATION CHECKLIST section present
[ ] Memory Protocol section present
[ ] Verification commands included
[ ] Example values provided where helpful

Security Validation (SEC-TC-007):

[ ] No secrets, credentials, or API keys in template content
[ ] No absolute file paths (use relative from PROJECT_ROOT)
[ ] No eval(), exec(), Function() or code execution patterns
[ ] No prompt override patterns ("IGNORE PREVIOUS", "SYSTEM:", etc.)
[ ] Template size under 50KB

Verification Commands:

# Check no unresolved placeholders from template-creator itself
grep "{{" <created-file> | head -5  # Should show only intended placeholders

# Check YAML frontmatter is present
head -50 <file> | grep -E "^---$" | wc -l  # Should be 2

# Check required sections present
grep -E "^## Memory Protocol" <file> || echo "ERROR: Missing Memory Protocol!"

BLOCKING: Template must pass ALL validation checks before proceeding.

Step 8: Update Template Catalog (MANDATORY - BLOCKING)

Update the template catalog to ensure the new template is discoverable.

1. Read current catalog:

   cat .claude/context/artifacts/catalogs/template-catalog.md
   

2. Determine template category based on type:

   • Spawn (spawn/), Creator (agents/, skills/, workflows/), Document (root), Report (reports/), Code Style (code-styles/)

3. Add template entry in correct category section:

   ### <template-name>.md
   
   | Field              | Value                                             |
   | ------------------ | ------------------------------------------------- |
   | **Path**           | `.claude/templates/<category>/<template-name>.md` |
   | **Category**       | <Category> Templates                              |
   | **Status**         | active                                            |
   | **Used By Agents** | <agent-list>                                      |
   | **Used By Skills** | <skill-list>                                      |
   
   **Purpose:** <Purpose description>
   

4. Update Template Categories Summary table (totals row)

5. Verify update:

   grep "<template-name>" .claude/context/artifacts/catalogs/template-catalog.md || echo "ERROR: CATALOG NOT UPDATED!"
   

Important: Use JSON.stringify() when constructing any JSON registry entries (SEC-TC-004). Never manually concatenate strings to build JSON. The location field MUST be validated to start with .claude/templates/ and contain no .. segments.

BLOCKING: Template must appear in catalog. Uncataloged templates are invisible.

Step 9: Update Templates README (MANDATORY - BLOCKING)

After updating the catalog, update .claude/templates/README.md:

1. Add to appropriate section (or create new section)
2. Document usage instructions
3. Add to Quick Reference table

Entry format:

### {{Template Type}} Templates (`{{directory}}/`)

Use when {{use case}}.

**File:** `{{directory}}/{{template-name}}.md`

**Usage:**

1. Copy template to `{{target-path}}`
2. Replace all `{{PLACEHOLDER}}` values
3. {{Additional steps}}

Verification:

grep "<template-name>" .claude/templates/README.md || echo "ERROR: README NOT UPDATED - BLOCKING!"

BLOCKING: README must contain the template entry.

Step 10: Update CLAUDE.md (CONDITIONAL - BLOCKING)

If the template is framework-significant or user-invocable:

1. Check if template needs CLAUDE.md entry:

   • Is it a new spawn template? -> Update Section 2 (Spawn Templates)
   • Is it a new creator template? -> Update relevant creator section
   • Is it a user-invocable template? -> Update Section 8.5

2. If YES, add entry:

   **{Template Name}:** `.claude/templates/{category}/{name}.md`
   

3. Verify:

   grep "<template-name>" .claude/CLAUDE.md || echo "WARNING: Template not in CLAUDE.md (may be OK if internal-only)"
   

Note: Not all templates need CLAUDE.md entries. Only framework-significant ones (spawn templates, creator templates) require this step.

Step 11: Assign Consumer Agents

Templates exist to be consumed by creators and agents. After creation:

1. Identify consumers based on template type:

   • Agent templates -> agent-creator skill should reference
   • Skill templates -> skill-creator skill should reference
   • Workflow templates -> workflow-creator skill should reference
   • Report templates -> relevant agents (qa, developer, etc.)
   • Spawn templates -> router documentation, spawn-template-resolver
   • Code style templates -> developer, code-reviewer

2. Update consuming skill/agent to reference the template:

   **Available Templates:**
   
   - See `.claude/templates/<category>/<template-name>.md` for standardized <type> template
   

3. Verify at least one consumer references the template:

   grep -r "<template-name>" .claude/skills/ .claude/agents/ || echo "WARNING: No consumer references template"
   

WHY: Templates without consumers are dead on arrival. Every template MUST have at least one consuming skill or agent.

Step 12: Integration Verification (BLOCKING - DO NOT SKIP)

This step verifies the artifact is properly integrated into the ecosystem.

Before calling TaskUpdate({ status: "completed" }), run the post-creation validation:

1. Run the integration checklist:

   node .claude/tools/cli/validate-integration.cjs .claude/templates/<category>/<template-name>.md
   

2. Verify exit code is 0 (all checks passed)

3. If exit code is 1 (one or more checks failed):

   • Read the error output for specific failures
   • Fix each failure:
     • Missing README entry -> Add to .claude/templates/README.md
     • Missing catalog entry -> Add to template-catalog.md
     • Missing memory update -> Update learnings.md
   • Re-run validation until exit code is 0

4. Only proceed when validation passes

This step is BLOCKING. Do NOT mark task complete until validation passes.

Why this matters: The Party Mode incident showed that fully-implemented artifacts can be invisible to the Router if integration steps are missed. This validation ensures no "invisible artifact" pattern.

Reference: .claude/workflows/core/post-creation-validation.md

Step 13: Completion Checklist (BLOCKING)

All items MUST pass before template creation is complete:

[ ] Research-synthesis skill invoked (Step 0)
[ ] Existence check passed (no duplicate template)
[ ] Template name validates against /^[a-z0-9][a-z0-9-]*[a-z0-9]$/ (Step 3)
[ ] Template file created at .claude/templates/<category>/<name>.md
[ ] All placeholders use {{PLACEHOLDER_NAME}} format
[ ] All placeholders have documentation comments
[ ] POST-CREATION CHECKLIST section present in template
[ ] Memory Protocol section present in template
[ ] No hardcoded values (all configurable via placeholders)
[ ] No secrets, credentials, or absolute paths in template (SEC-TC-007)
[ ] No eval() or code execution patterns in template
[ ] template-catalog.md updated with

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->