Claude-Code-Workflow/.claude/skills/skill-generator/templates/skill-md.md

SKILL.md Template

Template for generating new Skill entry files.

Purpose

Generate the entry file (SKILL.md) for new Skills, serving as the main documentation and execution entry point for the Skill.

Usage Context

Phase	Usage
Phase 2 (Structure Generation)	Create SKILL.md entry file
Generation Trigger	config.execution_mode determines architecture diagram style
Output Location	.claude/skills/{skill-name}/SKILL.md

---

Important: YAML Front Matter Specification

CRITICAL: The SKILL.md file MUST begin with YAML front matter, meaning --- must be the first line of the file.

Do NOT use the following formats:

• # Title followed by ## Metadata + yaml code block
• Any content before ---

Correct format: The first line MUST be ---

Ready-to-use Template

The following is a complete SKILL.md template. When generating, directly copy and apply it, replacing {{variables}} with actual values:

---

name: {{skill_name}} description: {{description}}. Triggers on {{triggers}}. allowed-tools: {{allowed_tools}}

{{display_name}}

{{description}}

Architecture Overview

``` {{architecture_diagram}} ```

Key Design Principles

{{design_principles}}

---

Mandatory Prerequisites

Do NOT skip: Before performing any operations, you must completely read the following documents. Proceeding without reading the specifications will result in outputs that do not meet quality standards.

{{mandatory_prerequisites}}

---

Execution Flow

{{execution_flow}}

Directory Setup

```javascript const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, ''); const workDir = `{{output_location}}`;

Bash(`mkdir -p "${workDir}"`); {{additional_dirs}} ```

Output Structure

``` {{output_structure}} ```

Reference Documents by Phase

Important

: Reference documents should be organized by execution phase, clearly marking when and in what scenarios they are used. Avoid listing documents in a flat manner.

{{reference_table}}

---

Variable Descriptions

Variable	Type	Source
{{skill_name}}	string	config.skill_name
{{display_name}}	string	config.display_name
{{description}}	string	config.description
{{triggers}}	string	config.triggers.join(", ")
{{allowed_tools}}	string	config.allowed_tools.join(", ")
{{architecture_diagram}}	string	Generated based on execution_mode (includes Phase 0)
{{design_principles}}	string	Generated based on execution_mode
{{mandatory_prerequisites}}	string	List of mandatory prerequisite reading documents (specs + templates)
{{execution_flow}}	string	Generated from phases/actions (Phase 0 first)
{{output_location}}	string	config.output.location
{{additional_dirs}}	string	Generated based on execution_mode
{{output_structure}}	string	Generated based on configuration
{{reference_table}}	string	Generated from file list

Generation Function

function generateSkillMd(config) {
  const template = Read('templates/skill-md.md');

  return template
    .replace(/\{\{skill_name\}\}/g, config.skill_name)
    .replace(/\{\{display_name\}\}/g, config.display_name)
    .replace(/\{\{description\}\}/g, config.description)
    .replace(/\{\{triggers\}\}/g, config.triggers.map(t => `"${t}"`).join(", "))
    .replace(/\{\{allowed_tools\}\}/g, config.allowed_tools.join(", "))
    .replace(/\{\{architecture_diagram\}\}/g, generateArchitecture(config))  // Includes Phase 0
    .replace(/\{\{design_principles\}\}/g, generatePrinciples(config))
    .replace(/\{\{mandatory_prerequisites\}\}/g, generatePrerequisites(config))  // Mandatory prerequisites
    .replace(/\{\{execution_flow\}\}/g, generateFlow(config))  // Phase 0 first
    .replace(/\{\{output_location\}\}/g, config.output.location)
    .replace(/\{\{additional_dirs\}\}/g, generateAdditionalDirs(config))
    .replace(/\{\{output_structure\}\}/g, generateOutputStructure(config))
    .replace(/\{\{reference_table\}\}/g, generateReferenceTable(config));
}

// Generate mandatory prerequisites table
function generatePrerequisites(config) {
  const specs = config.specs || [];
  const templates = config.templates || [];

  let result = '### Specification Documents (Required Reading)\n\n';
  result += '| Document | Purpose | When |\n';
  result += '|----------|---------|------|\n';

  specs.forEach((spec, index) => {
    const when = index === 0 ? '**Must read before execution**' : 'Recommended before execution';
    result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${when} |\n`;
  });

  if (templates.length > 0) {
    result += '\n### Template Files (Must read before generation)\n\n';
    result += '| Document | Purpose |\n';
    result += '|----------|---------|\n';
    templates.forEach(tmpl => {
      result += `| [${tmpl.path}](${tmpl.path}) | ${tmpl.purpose} |\n`;
    });
  }

  return result;
}

// Generate phase-by-phase reference document guide
function generateReferenceTable(config) {
  const phases = config.phases || config.actions || [];
  const specs = config.specs || [];
  const templates = config.templates || [];

  let result = '';

  // Generate document navigation for each execution phase
  phases.forEach((phase, index) => {
    const phaseNum = index + 1;
    const phaseTitle = phase.display_name || phase.name;

    result += `### Phase ${phaseNum}: ${phaseTitle}\n`;
    result += `Documents to reference when executing Phase ${phaseNum}\n\n`;

    // List documents related to this phase
    const relatedDocs = filterDocsByPhase(specs, phase, index);
    if (relatedDocs.length > 0) {
      result += '| Document | Purpose | When to Use |\n';
      result += '|----------|---------|-------------|\n';
      relatedDocs.forEach(doc => {
        result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context || 'Reference content'} |\n`;
      });
      result += '\n';
    }
  });

  // Troubleshooting section
  result += '### Debugging & Troubleshooting\n';
  result += 'Documents to reference when encountering issues\n\n';
  result += '| Issue | Solution Document |\n';
  result += '|-------|-------------------|\n';
  result += `| Phase execution failed | Refer to the relevant Phase documentation |\n`;
  result += `| Output does not meet expectations | [specs/quality-standards.md](specs/quality-standards.md) - Verify quality standards |\n`;
  result += '\n';

  // In-depth learning reference
  result += '### Reference & Background\n';
  result += 'For understanding the original implementation and design decisions\n\n';
  result += '| Document | Purpose | Notes |\n';
  result += '|----------|---------|-------|\n';
  templates.forEach(tmpl => {
    result += `| [${tmpl.path}](${tmpl.path}) | ${tmpl.purpose} | Reference during generation |\n`;
  });

  return result;
}

// Helper function: Get Phase emoji (removed)
// Note: Emoji support has been removed. Consider using Phase numbers instead.

// Helper function: Filter documents by Phase
function filterDocsByPhase(specs, phase, phaseIndex) {
  // Simple filtering logic: match phase name keywords
  const keywords = phase.name.toLowerCase().split('-');
  return specs.filter(spec => {
    const specName = spec.path.toLowerCase();
    return keywords.some(kw => specName.includes(kw));
  });
}

Sequential Mode Example

---
name: api-docs-generator
description: Generate API documentation from source code. Triggers on "generate api docs", "api documentation".
allowed-tools: Task, Read, Write, Glob, Grep, Bash
---

# API Docs Generator

Generate API documentation from source code.

## Architecture Overview

\`\`\`
Phase 0: Specification Study (Mandatory prerequisite - Read and understand design specifications)
          ↓
Phase 1: Scanning        → endpoints.json
         ↓
Phase 2: Parsing         → schemas.json
         ↓
Phase 3: Generation      → api-docs.md
\`\`\`

## Mandatory Prerequisites

> **Do NOT skip**: Before performing any operations, you **must** completely read the following documents.

### Specification Documents (Required Reading)

| Document | Purpose | Priority |
|----------|---------|----------|
| [specs/api-standards.md](specs/api-standards.md) | API documentation standards specification | **P0 - Highest** |

### Template Files (Must read before generation)

| Document | Purpose |
|----------|---------|
| [templates/endpoint-doc.md](templates/endpoint-doc.md) | Endpoint documentation template |

Autonomous Mode Example

---
name: task-manager
description: Interactive task management with CRUD operations. Triggers on "manage tasks", "task list".
allowed-tools: Task, AskUserQuestion, Read, Write
---

# Task Manager

Interactive task management with CRUD operations.

## Architecture Overview

\`\`\`
Phase 0: Specification Study (Mandatory prerequisite)
         ↓
┌────────────────────────────────────────┐
│  Orchestrator (State-driven decision)  │
└────────────┬───────────────────────────┘
             │
    ┌────────┼────────┬────────┐
    ↓        ↓        ↓        ↓
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ List   │ │ Create │ │ Edit   │ │ Delete │
└────────┘ └────────┘ └────────┘ └────────┘
\`\`\`

## Mandatory Prerequisites

> **Do NOT skip**: Before performing any operations, you **must** completely read the following documents.

### Specification Documents (Required Reading)

| Document | Purpose | Priority |
|----------|---------|----------|
| [specs/task-schema.md](specs/task-schema.md) | Task data structure specification | **P0 - Highest** |
| [specs/action-catalog.md](specs/action-catalog.md) | Action catalog | P1 |

### Template Files (Must read before generation)

| Document | Purpose |
|----------|---------|
| [templates/orchestrator-base.md](templates/orchestrator-base.md) | Orchestrator template |
| [templates/action-base.md](templates/action-base.md) | Action template |