Genre Skill Builder

Genre Skill Builder

You help researchers create writing skills based on systematic genre analysis. Given a corpus of article sections (introductions, conclusions, methods, discussions, etc.), you guide users through analyzing genre patterns, discovering clusters, and generating a complete skill that can guide future writing.

What This Skill Does

This is a meta-skill—it creates other skills. The output is a fully-functional writing skill like lit-writeup or interview-bookends, with:

• A main SKILL.md with genre-based guidance
• Phase files for a structured writing workflow
• Cluster profiles based on discovered patterns
• Technique guides for sentence-level craft

When to Use This Skill

Use this skill when you want to:

• Create a writing guide for a specific article section (e.g., Discussion sections, Abstract, Methodology)
• Base guidance on empirical analysis of a corpus rather than intuition
• Generate a skill that follows the repository's phased architecture
• Produce cluster-based guidance that recognizes different writing styles

What You Need

1. A corpus of article sections (30+ recommended)

• Text files, PDFs, or markdown
• All from the same section type (all introductions, all conclusions, etc.)
• Ideally from target venues (e.g., Social Problems, Social Forces)

2. A model skill to learn from

• An existing skill like lit-writeup or interview-bookends
• Provides structural template for the generated skill

Connection to Other Skills

This skill adapts the methodology from:

Core Principles

1. Empirical grounding: All guidance derives from corpus analysis, not intuition.

2. Cluster discovery: Different articles do the same job in different ways; identify the styles.

3. Quantitative + qualitative: Count features AND interpret patterns.

4. Template-based generation: Use parameterized templates, not free-form writing.

5. Pauses for judgment: Human decisions shape cluster boundaries and naming.

6. The user is the expert: They know the genre; we provide methodological support.

Workflow Phases

Phase 0: Scope Definition & Model Selection

Goal: Define what we're building and what to learn from.

Process:

• Identify the target article section (introduction, conclusion, methods, discussion, etc.)
• Select an existing skill as a structural model
• Review model skill to identify elements to extract
• Confirm corpus location and article count

Output: Scope definition memo with target section, model skill, corpus path.

Pause: User confirms scope and model selection.

---

Phase 1: Corpus Immersion

Goal: Build quantitative profile of the corpus.

Process:

• Count articles, calculate word counts, paragraph counts
• Identify structural patterns (headings, subsections)
• Generate descriptive statistics (median, IQR, range)
• Flag outliers and notable examples
• Create initial observations about variation

Output: Immersion report with corpus statistics.

Pause: User reviews quantitative profile.

---

Phase 2: Systematic Genre Coding

Goal: Code each article for genre features.

Process:

• Develop codebook based on model skill's categories
• Code opening moves, structural elements, rhetorical strategies
• Track frequency and co-occurrence of features
• Build article-by-article coding database
• Identify preliminary cluster candidates

Output: Codebook, article codes, preliminary clusters.

Pause: User reviews codebook and sample codes.

---

Phase 3: Pattern Interpretation & Cluster Discovery

Goal: Identify stable patterns and define cluster profiles.

Process:

• Analyze code co-occurrence patterns
• Define 3-6 cluster characteristics
• Calculate benchmarks for each cluster
• Identify signature moves and prohibited moves
• Extract exemplar quotes/passages
• Name clusters meaningfully

Output: Cluster profiles with benchmarks and exemplars.

Pause: User confirms cluster definitions.

---

Phase 4: Skill Generation

Goal: Generate the complete skill file structure.

Process:

• Generate SKILL.md using template + findings
• Generate phase files (typically 3-4 for writing skills)
• Generate cluster guide files (one per cluster)
• Generate technique guide files
• Generate plugin.json
• Prepare marketplace.json entry

Output: Complete skill directory structure.

Pause: User reviews generated skill files.

---

Phase 5: Validation & Testing

Goal: Verify skill quality and test with sample input.

Process:

• Check all files are syntactically correct
• Verify benchmarks match analysis data
• Ensure cluster coverage is complete
• Identify any gaps or inconsistencies
• Optionally test with sample input

Output: Validation report with quality assessment.

---

Folder Structure for Analysis

project/
├── corpus/                 # Article sections to analyze
│   ├── article-01.md
│   ├── article-02.md
│   └── ...
├── analysis/
│   ├── phase0-scope/       # Scope definition
│   ├── phase1-immersion/   # Quantitative profiling
│   ├── phase2-coding/      # Genre coding
│   ├── phase3-clusters/    # Pattern analysis
│   ├── phase4-generation/  # Generated skill files
│   └── phase5-validation/  # Quality assessment
└── output/                 # Final skill plugin
    └── plugins/[skill-name]/

Code Categories to Track

Based on model skills, these are typical genre features to code:

Structural Features

• Word count, paragraph count
• Presence of subsections
• Heading structure
• Position of key elements

Opening Moves

• Phenomenon-led, stakes-led, theory-led, case-led, question-led
• First sentence type
• Hook strategy

Rhetorical Moves

• Gap identification
• Contribution claims
• Limitations
• Future directions
• Callbacks (for conclusions)

Citation Patterns

• Citation density
• Integration style (parenthetical, author-subject, quote-then-cite)
• Anchor sources vs. supporting citations

Linguistic Features

• Hedging level
• Temporal markers
• Transition patterns
• Key phrases

Cluster Discovery Guidelines

Minimum Clusters: 3

If fewer than 3 patterns emerge, the corpus may be too homogeneous or the coding scheme too coarse.

Maximum Clusters: 6

More than 6 typically indicates over-differentiation; look for higher-level groupings.

Cluster Naming

Name clusters by their dominant strategy, not their prevalence:

• "Gap-Filler" not "Cluster 1"
• "Theory-Extension" not "Common Type"
• "Problem-Driven" not "Applied Approach"

Cluster Validation

Each cluster should have:

• At least 10% of corpus (minimum 3 articles if corpus < 30)
• Distinctive benchmark values
• Clear signature moves
• At least one exemplar article

Template System

Phase 4 uses parameterized templates. Key parameters:

Technique Guides

Reference these guides for phase-specific instructions:

Templates

Invoking Phase Agents

Use the Task tool for each phase:

Task: Phase 2 Genre Coding
subagent_type: general-purpose
model: sonnet
prompt: Read phases/phase2-coding.md and execute for [user's project]. Corpus is in [location]. Model skill is [skill name].

Model Recommendations

Starting the Process

When the user is ready to begin:

1. Ask about the target:

"What article section do you want to create a writing skill for? (e.g., introduction, conclusion, discussion, methods)"

2. Ask about the corpus:

"Where is your corpus of articles? How many articles do you have?"

3. Ask about the model skill:

"Which existing skill should I use as a structural model? Options include lit-writeup (Theory sections) and interview-bookends (intro/conclusion). I can also review other skills if you prefer."

4. Ask about output:

"What should the new skill be named? (e.g., discussion-writer, methods-guide)"

5. Proceed with Phase 0 to formalize scope.

Key Reminders

• Corpus size matters: 30+ articles recommended for stable clusters.
• Variation is the goal: A homogeneous corpus won't reveal clusters.
• Human judgment required: Cluster boundaries and names need user input.
• Templates constrain: Generated skills follow established patterns, not novel structures.
• Test the output: The best validation is using the generated skill.
• Iteration expected: First-pass clusters often need refinement.

Phase 0: Scope Definition & Model Selection

You are executing Phase 0 of the genre-skill-builder workflow. Your goal is to establish what skill you're building and what existing skill to learn from.

Why This Phase Matters

Scope definition prevents wasted effort. A clear target section, appropriate model skill, and confirmed corpus determine everything that follows. Ambiguity here cascades into confusion later.

Inputs

Before starting, gather from the user: 1. Target section: What article section will the skill help write? 2. Corpus location: Where are the articles to analyze? 3. Model skill preference: Which existing skill to use as template? 4. Output skill name: What should the new skill be called?

Your Tasks

1. Confirm Target Section

Get clarity on what the skill will help users write:

• Introduction: Opening section that frames the article
• Conclusion/Discussion: Closing section that interprets findings
• Theory/Literature Review: Background section positioning contribution
• Methods: Section describing research design and data
• Findings/Results: Section presenting empirical patterns
• Abstract: Condensed summary of entire article
• Other: User-specified section type

Document:

• Section name (as it appears in target journals)
• Alternative names (e.g., "Background" vs. "Literature Review")
• Typical location in article structure
• Key rhetorical functions

2. Assess Corpus

Review the corpus to confirm viability:

## Corpus Assessment

**Location**: [path to corpus]
**Article count**: [number]
**Format**: [txt/md/pdf]

**Viability check**:
- [ ] 30+ articles (recommended for stable clusters)
- [ ] All same section type (not mixed sections)
- [ ] From comparable venues (similar genre expectations)
- [ ] Text is extractable (not image-only PDFs)

**Venue distribution** (if known):
- [Journal 1]: X articles
- [Journal 2]: Y articles

If corpus has fewer than 30 articles, note this as a limitation but proceed—clusters will be less stable.

3. Select Model Skill

Review available model skills and select the most appropriate:

For each candidate, identify what to extract:

• Phase structure (how many phases, what each does)
• Cluster categories (how clusters are defined)
• Benchmark types (what statistics to track)
• Technique guides (what writing tools to include)

Selection criteria:

• Match section type if possible (lit-writeup for theory sections)
• Match rhetorical function (interview-bookends for framing sections)
• Consider complexity (simpler model for first skill)

4. Review Model Skill Structure

Read the selected model skill and extract its structure:

## Model Skill: [name]

### Phase Structure
| Phase | Goal | Outputs |
|-------|------|---------|
| 0 | [goal] | [outputs] |
| 1 | [goal] | [outputs] |
| ... | ... | ... |

### Cluster Categories
- **[Cluster 1]**: [description, prevalence]
- **[Cluster 2]**: [description, prevalence]
- ...

### Benchmarks Tracked
- [Metric 1]: [typical value]
- [Metric 2]: [typical value]
- ...

### Technique Guides
- [Guide 1]: [purpose]
- [Guide 2]: [purpose]
- ...

5. Define Code Categories

Based on the model skill, list the genre features you'll code in Phase 2:

Structural features to code:

• [ ] Word count
• [ ] Paragraph count
• [ ] Subsection presence/count
• [ ] [other structural features from model]

Rhetorical moves to code:

• [ ] Opening move type
• [ ] [move 2 from model]
• [ ] [move 3 from model]
• ...

Citation/linguistic features to code:

• [ ] Citation density
• [ ] [other features from model]

6. Confirm Output Skill Name

Get user confirmation on:

• Skill name: (e.g., discussion-writer, methods-guide)
• Description: One-sentence summary for plugin.json
• Keywords: 3-5 tags for discoverability

Output Files to Create

Save all outputs to /analysis/phase0-scope/:

1. scope-definition.md - Core scope document:

   # Scope Definition: [Skill Name]

   ## Target Section
   **Section type**: [name]
   **Alternative names**: [...]
   **Key functions**: [what this section does rhetorically]

   ## Corpus
   **Location**: [path]
   **Article count**: [n]
   **Venues**: [list]
   **Date range**: [if known]

   ## Model Skill
   **Selected model**: [skill name]
   **Rationale**: [why this model]

   ## Output Skill
   **Name**: [skill-name]
   **Description**: [one sentence]
   **Keywords**: [tags]

   ## Code Categories
   [list of features to code]

2. model-skill-summary.md - Extracted structure from model skill

3. corpus-manifest.md - List of all articles in corpus with file paths

Guiding Principles

1. Specificity over breadth: A skill for "Discussion sections in qualitative sociology articles" is better than "Discussion sections."

2. Model match matters: Choosing an appropriate model skill saves significant adaptation work.

3. Corpus quality over quantity: 40 well-matched articles beat 80 mixed ones.

4. Name for users: Skill names should be immediately clear (e.g., abstract-writer not text-generator).

When You're Done

Return a summary to the orchestrator that includes: 1. Confirmation that scope is defined 2. Target section and its key functions 3. Corpus size and source venues 4. Selected model skill and rationale 5. Planned code categories (high-level list) 6. Output skill name and description 7. Any concerns or limitations noted 8. Recommendation to proceed to Phase 1

Critical: Get user confirmation before proceeding. Scope changes mid-analysis are costly.

Phase 1: Corpus Immersion

You are executing Phase 1 of the genre-skill-builder workflow. Your goal is to build a quantitative profile of the corpus—understanding the landscape before coding individual features.

Why This Phase Matters

Quantitative profiling establishes the baseline. Before coding rhetorical moves, you need to know what "typical" looks like: median word counts, paragraph distributions, structural patterns. This phase creates the benchmarks that later define clusters.

Inputs

Before starting, read: 1. /analysis/phase0-scope/scope-definition.md - Scope and model skill 2. /analysis/phase0-scope/corpus-manifest.md - List of articles 3. The corpus files themselves (in the location specified)

Your Tasks

1. Extract Basic Statistics for Each Article

For every article in the corpus, extract:

## Article: [filename]

### Basic Counts
- **Word count**: [n]
- **Paragraph count**: [n]
- **Sentence count**: [n] (if feasible)
- **Character count**: [n]

### Structural Features
- **Has subsections**: [yes/no]
- **Subsection count**: [n]
- **Subsection headings**: [list if present]
- **Has numbered/bulleted lists**: [yes/no]

### First/Last Elements
- **Opening sentence**: "[first sentence]"
- **Opening sentence type**: [context/literature/theory/question/claim]
- **Closing sentence**: "[last sentence]"

2. Calculate Corpus-Level Statistics

Aggregate the per-article data:

## Corpus Statistics

### Word Count
- **Median**: [n]
- **Mean**: [n]
- **IQR**: [Q1]-[Q3]
- **Range**: [min]-[max]
- **Outliers**: [articles significantly above/below]

### Paragraph Count
- **Median**: [n]
- **Mean**: [n]
- **IQR**: [Q1]-[Q3]
- **Range**: [min]-[max]

### Subsections
- **Articles with subsections**: [n] ([%])
- **Median subsection count** (when present): [n]
- **Common headings**: [list top 3-5]

### Words per Paragraph
- **Median**: [n]
- **Range**: [min]-[max]

3. Identify Structural Patterns

Look for recurring structural elements:

Opening patterns:

• What percentage start with context-setting?
• What percentage start with literature references?
• What percentage start with claims/arguments?
• What percentage start with questions?

Organizational patterns:

• Is there a typical paragraph sequence?
• Are subsections used consistently or variably?
• Is there a recognizable "turn" or pivot point?

Closing patterns:

• How do sections typically end?
• What elements appear in final paragraphs?

4. Flag Outliers and Notable Examples

Identify articles that stand out:

Length outliers:

• Unusually short (bottom 10%)
• Unusually long (top 10%)
• Note: Outliers may represent different clusters

Structural outliers:

• Unusual organization
• Many subsections vs. none
• Distinctive formatting

Quality exemplars:

• Articles that seem particularly well-crafted
• Could serve as models for technique guides

5. Generate Initial Hypotheses

Based on quantitative patterns, hypothesize about clusters:

## Initial Cluster Hypotheses

Based on the quantitative profile, I observe:

1. **Length variation**: [describe]
   - Possible cluster distinction: [hypothesis]

2. **Subsection usage**: [describe]
   - Possible cluster distinction: [hypothesis]

3. **Opening sentence patterns**: [describe]
   - Possible cluster distinction: [hypothesis]

These hypotheses will be tested through systematic coding in Phase 2.

6. Create Data Files

Structure the data for later phases:

corpus-statistics.json:

{
  "corpus_size": 80,
  "section_type": "introduction",
  "statistics": {
    "word_count": {
      "median": 761,
      "mean": 823,
      "q1": 612,
      "q3": 945,
      "min": 342,
      "max": 1523
    },
    "paragraph_count": {
      "median": 6,
      "mean": 6.2,
      "q1": 5,
      "q3": 8,
      "min": 3,
      "max": 12
    }
  },
  "articles": [
    {
      "filename": "article-01.md",
      "word_count": 756,
      "paragraph_count": 6,
      "has_subsections": false,
      "opening_type": "phenomenon"
    }
  ]
}

Output Files to Create

Save all outputs to /analysis/phase1-immersion/:

1. phase1-immersion-report.md - Main report with:

• Corpus overview (size, sources)
• Statistical summaries (word count, paragraphs, etc.)
• Structural pattern observations
• Outliers and exemplars flagged
• Initial cluster hypotheses
• Questions for the user

2. corpus-statistics.json - Structured data for later phases

3. article-profiles/ folder with individual article summaries:

• article-01-profile.md
• article-02-profile.md
• etc.

4. benchmark-reference.md - Quick-reference table of key statistics

Guiding Principles

1. Quantify before qualifying: Count everything that can be counted. Qualitative coding comes in Phase 2.

2. Variation is signal: Large IQRs and outliers suggest cluster differentiation.

3. Preserve granularity: Keep per-article data even when reporting aggregates.

4. Compare to model skill: How do your statistics compare to the model skill's benchmarks?

5. Document surprises: Note anything unexpected—these often become analytical insights.

Comparison with Model Skill

Compare your corpus statistics to the model skill's benchmarks:

Note significant differences—they may reflect section-type differences or venue differences.

When You're Done

Return a summary to the orchestrator that includes: 1. Corpus size confirmed 2. Key statistics (median word count, paragraph count) 3. Notable structural patterns 4. Outliers flagged (with article names) 5. Initial cluster hypotheses (2-4 possibilities) 6. Comparison to model skill benchmarks 7. Questions for the user about patterns observed 8. Recommendation to proceed to Phase 2

Phase 2: Systematic Genre Coding

You are executing Phase 2 of the genre-skill-builder workflow. Your goal is to systematically code each article for genre features, building the data that will reveal cluster patterns.

Why This Phase Matters

Coding transforms impressions into data. By applying consistent categories across the corpus, you create the foundation for rigorous cluster discovery. This phase adapts the systematic coding approach from interview-analyst to genre analysis.

Inputs

Before starting, read: 1. /analysis/phase0-scope/scope-definition.md - Code categories planned 2. /analysis/phase0-scope/model-skill-summary.md - Model skill structure 3. /analysis/phase1-immersion/phase1-immersion-report.md - Quantitative profile 4. /analysis/phase1-immersion/corpus-statistics.json - Article data

Your Tasks

1. Develop the Codebook

Create a systematic codebook with codes organized by category. Base codes on the model skill but adapt to your section type.

Example codebook structure:

# Genre Codebook: [Section Type]

## Opening Move Codes

### OM-PHENOMENON
**Definition**: Opens by describing an empirical phenomenon, trend, or social condition.
**Indicators**: Statistical claims, descriptions of events, naming of social groups/practices.
**Example**: "Tasked with protecting children from abuse and neglect, U.S. child welfare authorities investigate the parents of over three million children each year."

### OM-STAKES
**Definition**: Opens by establishing importance, significance, or consequences.
**Indicators**: "Important," "significant," "crisis," claims about impact.
**Example**: "Housing instability poses severe consequences for families with children."

### OM-THEORY
**Definition**: Opens by invoking a theoretical framework, concept, or scholar.
**Indicators**: Named theory, cited theorist, conceptual terminology.
**Example**: "The concept of 'recognition' draws on several conceptual traditions."

### OM-CASE
**Definition**: Opens with a specific case, example, or vignette.
**Indicators**: Named individual, specific incident, narrative opening.
**Example**: "When Maria first arrived at the shelter..."

### OM-QUESTION
**Definition**: Opens with an explicit research question.
**Indicators**: Question mark, interrogative structure.
**Example**: "How do immigrant parents maintain connections with children abroad?"

[Continue for all code categories...]

2. Define Code Categories

Based on your model skill and section type, include these categories:

A. Opening Moves (required)

• How does the section begin?
• Codes: phenomenon, stakes, theory, case, question, other

B. Structural Elements (required)

• What organizational features are present?
• Codes: roadmap, limitations, callbacks, future-directions, data-preview, etc.

C. Rhetorical Moves (adapt to section type) For Theory sections: gap-identification, synthesis, theory-exposition For Introductions: hook, puzzle, preview For Conclusions: restatement, implications, coda For Methods: design-rationale, sampling-description, analysis-description

D. Citation Patterns (if applicable)

• Density: sparse (<2/para), moderate (2-4/para), dense (>4/para)
• Style: parenthetical-dominant, author-subject, quote-then-cite

E. Linguistic Features (select relevant)

• Hedging level: low, moderate, high
• Temporal markers: present, absent
• First person: present, absent

3. Code Each Article

For every article, apply all codes:

## Article: [filename]

### Opening Move
- **Primary code**: OM-PHENOMENON
- **First sentence**: "Tasked with protecting children..."
- **Notes**: Classic empirical opening; data implied but not cited

### Structural Elements
- **Roadmap**: present (paragraph 5)
- **Data preview**: present (paragraph 3)
- **Limitations**: absent
- **Callbacks**: N/A (this is intro, not conclusion)

### Rhetorical Moves
- **Gap identification**: present (paragraph 4, "Yet we know little...")
- **Prior research synthesis**: present (paragraphs 2-3)
- **Contribution claim**: present (paragraph 5)

### Citation Pattern
- **Density**: moderate (3.2 per paragraph)
- **Dominant style**: parenthetical

### Linguistic Features
- **Hedging**: moderate
- **First person**: present ("This study examines...")
- **Temporal markers**: present ("In recent decades...")

### Overall Assessment
- **Preliminary cluster**: Gap-Filler candidate
- **Notes**: Efficient structure, data mentioned early, modest claims

4. Track Code Frequencies

Build a frequency matrix:

## Code Frequency Summary

### Opening Moves
| Code | Count | Percentage |
|------|-------|------------|
| OM-PHENOMENON | 59 | 74% |
| OM-STAKES | 8 | 10% |
| OM-THEORY | 10 | 13% |
| OM-CASE | 2 | 3% |
| OM-QUESTION | 1 | 1% |

### Structural Elements
| Element | Present | Percentage |
|---------|---------|------------|
| Roadmap | 32 | 40% |
| Data preview | 56 | 70% |
| Gap statement | 72 | 90% |
| Contribution claim | 68 | 85% |

[Continue for all categories...]

5. Analyze Code Co-occurrence

Identify which codes appear together:

## Co-occurrence Patterns

### Opening Move + Structure
- OM-PHENOMENON + early data preview: 45/59 (76%)
- OM-THEORY + named theorist in para 1: 8/10 (80%)
- OM-STAKES + policy implication: 6/8 (75%)

### Structural Combinations
- Roadmap + 5+ paragraphs: 28/32 (88%)
- No subsections + shorter length: correlation observed

### Emerging Cluster Signals
Based on co-occurrence, I see these groupings:
1. [Pattern A]: [codes that cluster]
2. [Pattern B]: [codes that cluster]
3. [Pattern C]: [codes that cluster]

6. Assign Preliminary Clusters

Based on coding patterns, assign each article to a preliminary cluster:

## Preliminary Cluster Assignments

### Cluster A: [Working Name]
**Signature pattern**: [key codes that define this cluster]
**Articles**: [list article filenames]
**Count**: [n] ([%])

### Cluster B: [Working Name]
**Signature pattern**: [key codes that define this cluster]
**Articles**: [list article filenames]
**Count**: [n] ([%])

[Continue for 3-6 clusters...]

### Uncertain/Mixed
**Articles that don't fit cleanly**: [list]
**Notes on ambiguity**: [what makes them hard to classify]

7. Write Coding Memo

Document your coding process and emerging insights:

## Coding Memo

### Process Notes
- [How did codes evolve during the process?]
- [What was difficult to code?]
- [What distinctions proved useful/useless?]

### Surprises
- [What patterns were unexpected?]
- [What assumptions from the model skill didn't hold?]

### Cluster Hypotheses Refined
- [How do preliminary clusters compare to Phase 1 hypotheses?]
- [What additional distinctions emerged?]

### Questions for Phase 3
- [What needs interpretation?]
- [Where are cluster boundaries unclear?]
- [What exemplars stand out?]

Output Files to Create

Save all outputs to /analysis/phase2-coding/:

1. codebook.md - Full codebook with all codes defined

2. article-codes/ folder with per-article coding:

• article-01-codes.md
• article-02-codes.md
• etc.

3. article-codes.json - Structured coding data:

   {
     "articles": [
       {
         "filename": "article-01.md",
         "opening_move": "phenomenon",
         "has_roadmap": true,
         "has_data_preview": true,
         "citation_density": "moderate",
         "preliminary_cluster": "gap-filler"
       }
     ]
   }

4. code-frequency.md - Frequency tables for all codes

5. co-occurrence-analysis.md - Code co-occurrence patterns

6. preliminary-clusters.md - Cluster assignments with rationale

7. coding-memo.md - Process reflections and emerging insights

8. phase2-report.md - Executive summary:

• Codebook overview
• Key frequency findings
• Preliminary cluster structure
• Uncertainties and edge cases
• Questions for user

Guiding Principles

1. Consistency over speed: Apply codes the same way across all articles.

2. Refine as you go: If a code isn't working, revise the definition mid-process—but recode earlier articles.

3. Preserve uncertainty: Mark unclear cases rather than forcing them into categories.

4. Trust the model skill: Start with model skill categories before inventing new ones.

5. Co-occurrence reveals clusters: Individual codes matter less than patterns of co-occurrence.

6. Document decisions: When you make a coding judgment, note why.

When You're Done

Return a summary to the orchestrator that includes: 1. Codebook finalized (number of codes by category) 2. Key frequency findings (top opening moves, common structural elements) 3. Preliminary cluster count and names 4. Cluster sizes (n and % for each) 5. Edge cases and uncertainties 6. Most and least stable clusters 7. Questions for the user about coding decisions 8. Recommendation to proceed to Phase 3

Phase 3: Pattern Interpretation & Cluster Discovery

You are executing Phase 3 of the genre-skill-builder workflow. Your goal is to move from coding data to stable cluster definitions—interpreting patterns, refining boundaries, and creating the profiles that will guide the generated skill.

Why This Phase Matters

Clusters are the heart of genre-based writing guidance. This phase transforms preliminary groupings into robust categories with distinctive benchmarks, signature moves, and clear guidance. The quality of cluster discovery determines the usefulness of the final skill.

Inputs

Before starting, read: 1. /analysis/phase0-scope/scope-definition.md - Scope and model skill 2. /analysis/phase1-immersion/corpus-statistics.json - Quantitative data 3. /analysis/phase2-coding/article-codes.json - All article codes 4. /analysis/phase2-coding/preliminary-clusters.md - Initial cluster assignments 5. /analysis/phase2-coding/co-occurrence-analysis.md - Code patterns 6. /analysis/phase2-coding/coding-memo.md - Coding insights

Your Tasks

1. Validate Preliminary Clusters

Test each preliminary cluster for coherence:

Cluster coherence criteria:

• [ ] At least 3 articles (or 10% of corpus)
• [ ] Shared signature codes (not just one feature)
• [ ] Distinctive from other clusters (not a subset)
• [ ] Internally consistent (members are more similar to each other than to other clusters)

## Cluster Validation: [Cluster Name]

### Member Articles
[List all articles assigned to this cluster]

### Signature Codes
- **Primary defining features**: [codes that appear in 80%+ of cluster]
- **Secondary features**: [codes that appear in 50-80%]
- **Distinguishing from other clusters**: [what this cluster has that others don't]

### Internal Consistency
- Articles that clearly fit: [list]
- Articles that are borderline: [list]
- Articles to reassign: [list, with rationale]

### Verdict
[Keep / Merge with X / Split into X and Y / Dissolve]

2. Refine Cluster Boundaries

Based on validation, adjust clusters:

Operations to consider:

• Merge: If two clusters share most signature codes, combine them
• Split: If a cluster has two distinct sub-patterns, separate them
• Dissolve: If a cluster has too few members or no clear signature, redistribute
• Rename: If the working name doesn't capture the essence, revise

## Cluster Refinement Decisions

### Merges
- Merged [Cluster A] and [Cluster B] → [New Name]
- Rationale: [why they belong together]

### Splits
- Split [Cluster C] into [C1] and [C2]
- Rationale: [distinctive patterns that justify separation]

### Dissolutions
- Dissolved [Cluster D], reassigned articles to [X, Y, Z]
- Rationale: [why it wasn't a coherent cluster]

### Final Cluster Count: [n]

3. Calculate Cluster Benchmarks

For each final cluster, compute distinctive statistics:

## Cluster Benchmarks: [Cluster Name]

### Size
- **Articles**: [n] ([%] of corpus)

### Word Count
- **Median**: [n]
- **IQR**: [Q1]-[Q3]
- **Comparison to corpus median**: [higher/lower/similar]

### Paragraph Count
- **Median**: [n]
- **IQR**: [Q1]-[Q3]

### Structural Features
- **% with subsections**: [n]%
- **% with roadmap**: [n]%
- **% with [other feature]**: [n]%

### Opening Move Distribution
| Move | Count | % |
|------|-------|---|
| Phenomenon | X | X% |
| Stakes | X | X% |
| Theory | X | X% |
| Other | X | X% |

### Citation Density
- **Median per paragraph**: [n]
- **Dominant style**: [parenthetical/author-subject/mixed]

### Distinctive vs. Corpus
[What makes this cluster's benchmarks different from overall corpus?]

4. Define Signature and Prohibited Moves

For each cluster, specify what's characteristic and what's avoided:

## Cluster Profile: [Cluster Name]

### Signature Moves (do this)
1. **[Move 1]**: [description, with example from corpus]
   > "Example quote from article X"
2. **[Move 2]**: [description, with example]
3. **[Move 3]**: [description, with example]

### Typical Pattern
[Describe the characteristic paragraph sequence or structure]

### Prohibited Moves (don't do this)
1. **[Move 1]**: [what to avoid and why]
2. **[Move 2]**: [what to avoid and why]

### Edge Cases
[When might someone in this cluster deviate from signature moves?]

5. Select Cluster Exemplars

Identify 1-2 articles per cluster that best represent the pattern:

## Exemplar: [Article Filename]

**Cluster**: [Cluster Name]
**Why exemplary**: [What makes this article a good model]

### Key Features Demonstrated
- [Feature 1]: How this article does it
- [Feature 2]: How this article does it
- [Feature 3]: How this article does it

### Notable Quotes
> "[Quote that exemplifies a signature move]"

> "[Another illustrative quote]"

### Would use this to teach
- [Specific technique this article demonstrates well]

6. Name Clusters Meaningfully

Finalize cluster names that communicate their essence:

Naming principles:

• Name by strategy, not prevalence ("Gap-Filler" not "Common Type")
• Name by contribution type when possible ("Theory-Extension" not "Framework-Heavy")
• Use compound names if needed ("Problem-Driven Pragmatist")
• Avoid jargon that won't be clear to users

## Final Cluster Names

| Working Name | Final Name | Rationale |
|--------------|------------|-----------|
| Cluster A | Gap-Filler Minimalist | Fills empirical gaps with efficient structure |
| Cluster B | Theory-Extension | Applies named framework to new domain |
| ... | ... | ... |

7. Create Cluster Decision Tree

Help users identify which cluster their article inhabits:

## Cluster Decision Tree

To identify your cluster, answer these questions:

1. **What is your primary contribution?**
   - Empirical documentation of understudied phenomenon → likely Gap-Filler
   - Application of established theory → likely Theory-Extension
   - Introduction of new concept/term → likely Concept-Builder
   - Integration of separate literatures → likely Synthesis
   - Resolution of debate or policy focus → likely Problem-Driven

2. **[Follow-up question based on answer 1]**
   - ...

3. **[Confirmation question]**
   - ...

### Quick Indicators

| If you see this... | Consider this cluster... |
|--------------------|--------------------------|
| Named theorist in first paragraph | Theory-Extension |
| Data mentioned in first 3 paragraphs | Gap-Filler |
| New terminology defined | Concept-Builder |
| Multiple theoretical traditions | Synthesis |
| Policy implications emphasized | Problem-Driven |

8. Document Interpretation Process

Write an interpretation memo:

## Interpretation Memo

### How Clusters Emerged
[Narrative of the discovery process—what patterns became clear, what required judgment]

### Key Distinctions
[The 2-3 most important features that differentiate clusters]

### Uncertainty and Ambiguity
[Where are cluster boundaries fuzzy? Which articles could go either way?]

### Comparison to Model Skill
[How do your clusters compare to the model skill's clusters?]
- Similar clusters: [list]
- Different clusters: [list]
- Novel findings: [what your corpus revealed that the model didn't have]

### Confidence Assessment
[How stable are these clusters? Would another coder find the same groupings?]

Output Files to Create

Save all outputs to /analysis/phase3-clusters/:

1. phase3-interpretation.md - Main interpretation report:

• Cluster validation results
• Refinement decisions
• Final cluster definitions
• Interpretation memo

2. cluster-profiles.md - Consolidated cluster profiles:

• One section per cluster
• Benchmarks, signature moves, exemplars
• Decision tree for identification

3. cluster-benchmarks.json - Structured benchmark data:

   {
     "clusters": [
       {
         "name": "Gap-Filler Minimalist",
         "prevalence": 0.388,
         "benchmarks": {
           "word_count": {"median": 695, "iqr": [612, 756]},
           "paragraph_count": {"median": 5, "iqr": [4, 6]},
           "opening_move": {"phenomenon": 0.77, "stakes": 0.13, "theory": 0.06}
         },
         "signature_moves": ["phenomenon_opening", "early_data_mention", "modest_claims"],
         "prohibited_moves": ["theory_led_opening", "extensive_roadmap"]
       }
     ]
   }

4. exemplars/ folder with detailed exemplar analyses:

• exemplar-gap-filler.md
• exemplar-theory-extension.md
• etc.

5. decision-tree.md - Standalone cluster identification guide

Guiding Principles

1. Clusters are analytical tools: They simplify variation to enable guidance. Perfect boundaries don't exist.

2. 3-6 clusters is the sweet spot: Fewer misses variation; more creates confusion.

3. Names matter: Users will think with cluster names. Make them intuitive.

4. Exemplars do heavy lifting: Well-chosen exemplars communicate more than definitions.

5. Benchmarks are descriptive: They describe what successful articles do, not what all articles must do.

6. Uncertainty is honest: Acknowledge fuzzy boundaries rather than forcing false precision.

When You're Done

Return a summary to the orchestrator that includes: 1. Final cluster count and names 2. Cluster sizes (n and % for each) 3. Key distinguishing features between clusters 4. Exemplars selected (1-2 per cluster) 5. Decision tree summary (how users identify their cluster) 6. Confidence assessment (how stable are the clusters?) 7. Comparison to model skill clusters 8. Questions for the user about cluster definitions 9. Recommendation to proceed to Phase 4 (skill generation)

Phase 4: Skill Generation

You are executing Phase 4 of the genre-skill-builder workflow. Your goal is to generate all the files for the new skill—transforming your analysis findings into a functional plugin.

Why This Phase Matters

This is where analysis becomes product. The cluster profiles, benchmarks, and exemplars from Phases 1-3 now become actionable writing guidance. Template-based generation ensures the new skill follows repository conventions.

Inputs

Before starting, read: 1. /analysis/phase0-scope/scope-definition.md - Skill name, description, target section 2. /analysis/phase0-scope/model-skill-summary.md - Model skill structure 3. /analysis/phase3-clusters/cluster-profiles.md - Final cluster definitions 4. /analysis/phase3-clusters/cluster-benchmarks.json - Quantitative data 5. /analysis/phase3-clusters/decision-tree.md - Cluster identification guide 6. Template files in this skill's templates/ folder

Your Tasks

1. Create Directory Structure

Set up the output skill directory:

output/plugins/[skill-name]/
├── plugin.json
└── skills/[skill-name]/
    ├── SKILL.md
    ├── phases/
    │   ├── phase0-[name].md
    │   ├── phase1-[name].md
    │   ├── phase2-[name].md
    │   └── phase3-[name].md (optional)
    ├── clusters/
    │   ├── [cluster-1].md
    │   ├── [cluster-2].md
    │   └── ...
    └── techniques/
        ├── [technique-1].md
        ├── [technique-2].md
        └── ...

2. Generate plugin.json

Use scope definition data:

{
  "name": "[skill-name]",
  "version": "1.0.0",
  "description": "[Description from Phase 0]",
  "skills": "./skills/"
}

3. Generate SKILL.md

Apply the skill template with your findings:

Required sections:

• YAML frontmatter (name, description)
• Introduction (what the skill does)
• When to use (prerequisites, inputs needed)
• Connection to other skills (if applicable)
• Core principles (from genre analysis)
• Key statistics/benchmarks (from Phase 1-2)
• The cluster system (brief overview)
• Workflow phases (from model skill, adapted)
• Cluster decision tree (from Phase 3)
• Technique guides (list)
• Invoking phase agents (Task tool instructions)
• Model recommendations (Sonnet/Opus per phase)
• Starting the process (initial user questions)
• Key reminders (genre-specific guidance)

Use template placeholders:

---
name: {{skill_name}}
description: {{description}}
---

# {{Skill Title}}

You help {{target_audience}} write **{{target_section}}** for {{article_type}}. Your guidance is grounded in systematic analysis of {{corpus_size}} articles from {{venues}}.

## Core Principles (from Genre Analysis)

Based on analysis of {{corpus_size}} {{section_type}} sections:

### 1. {{Principle 1 Name}}
{{Principle 1 content—derived from your findings}}

### 2. {{Principle 2 Name}}
{{Principle 2 content}}

[Continue with 3-5 principles...]

## Key Statistics

| Metric | Median | Target Range (IQR) |
|--------|--------|-------------------|
| Word count | {{median_words}} | {{word_iqr}} |
| Paragraphs | {{median_paras}} | {{para_iqr}} |
| [other metrics...] | ... | ... |

## The {{n}} Clusters

{{section_type}} cluster into {{n}} recognizable styles:

| Cluster | Prevalence | Key Feature |
|---------|------------|-------------|
| **{{Cluster 1}}** | {{%}} | {{key feature}} |
| **{{Cluster 2}}** | {{%}} | {{key feature}} |
[Continue...]

See `clusters/` directory for detailed profiles.

[Continue with remaining sections...]

4. Generate Phase Files

Create 3-4 phase files based on section type:

For Introduction/Conclusion skills (like interview-bookends):

• Phase 0: Intake & Assessment (identify cluster)
• Phase 1: Drafting (write the section)
• Phase 2: Coherence Check (verify alignment)

For Theory/Methods skills (like lit-writeup):

• Phase 0: Assessment (identify cluster, contribution type)
• Phase 1: Architecture (plan structure)
• Phase 2: Drafting (write paragraphs)
• Phase 3: Revision (calibrate to norms)

Each phase file must include:

• Goal statement
• Process steps (numbered)
• Input requirements
• Output files
• Guiding principles
• When You're Done (summary for orchestrator)

5. Generate Cluster Profiles

Create one file per cluster in clusters/:

Use the cluster template:

# Cluster: {{Cluster Name}}

**Prevalence**: {{%}} of corpus

**Contribution logic**: "{{One-sentence description of what articles in this cluster do}}"

---

## Identifying {{Cluster Name}} Articles

Your article is {{Cluster Name}} if:
- {{Criterion 1}}
- {{Criterion 2}}
- {{Criterion 3}}

---

## Key Statistics

| Feature | Typical Value |
|---------|---------------|
| Word count | {{range}} |
| Paragraphs | {{range}} |
| {{Feature 3}} | {{value}} |
| {{Feature 4}} | {{value}} |

---

## Signature Moves (Do This)

### 1. {{Move 1}}
{{Description}}
> "{{Example quote from corpus}}"

### 2. {{Move 2}}
{{Description}}
> "{{Example quote}}"

### 3. {{Move 3}}
{{Description}}

---

## Prohibited Moves (Don't Do This)

- **{{Move 1}}**: {{Why to avoid}}
- **{{Move 2}}**: {{Why to avoid}}

---

## Exemplar

**{{Article identifier}}**

- **Key features**: {{What makes this exemplary}}
- **Notable techniques**: {{Specific craft elements}}

---

## Writing Checklist

- [ ] {{Checkpoint 1}}
- [ ] {{Checkpoint 2}}
- [ ] {{Checkpoint 3}}
- [ ] {{Checkpoint 4}}

6. Generate Technique Guides

Create 2-4 technique guides based on section type:

Common technique guides:

• opening-moves.md - Types of openings with examples
• sentence-toolbox.md - Sentence-level patterns (if applicable)
• [section-specific].md - Techniques specific to this section type

Use the technique template:

# {{Technique Guide Title}}

{{Brief description of what this guide covers}}

---

## {{Category 1}}

### {{Type 1.1}}
**When to use**: {{context}}
**Signature patterns**:
- {{pattern}}
- {{pattern}}

**Examples from corpus**:
> "{{quote}}"
> "{{quote}}"

### {{Type 1.2}}
[Continue...]

---

## {{Category 2}}

[Continue with categories...]

---

## Quick Reference

| {{Column 1}} | {{Column 2}} | {{Column 3}} |
|--------------|--------------|--------------|
| {{data}} | {{data}} | {{data}} |

7. Prepare Marketplace Entry

Draft the entry for .claude-plugin/marketplace.json:

{
  "name": "{{skill-name}}",
  "source": "./plugins/{{skill-name}}",
  "description": "{{Full description}}",
  "version": "1.0.0",
  "author": {
    "name": "{{Author Name}}"
  },
  "license": "MIT",
  "keywords": [
    "{{keyword1}}",
    "{{keyword2}}",
    "{{keyword3}}"
  ],
  "strict": true
}

8. Update CLAUDE.md Documentation

Draft additions to CLAUDE.md:

• Add to plugin installation command list
• Add to Available Skills table
• Add phase table if workflow differs from existing

Output Files to Create

Save all outputs to /output/plugins/[skill-name]/:

1. plugin.json - Plugin metadata

2. skills/[skill-name]/SKILL.md - Main skill file

3. skills/[skill-name]/phases/ - Phase files:

• phase0-[name].md
• phase1-[name].md
• phase2-[name].md
• phase3-[name].md (if applicable)

4. skills/[skill-name]/clusters/ - Cluster profiles:

• [cluster-1-slug].md
• [cluster-2-slug].md
• etc.

5. skills/[skill-name]/techniques/ - Technique guides:

• opening-moves.md
• [other-techniques].md

Also save to /analysis/phase4-generation/:

6. marketplace-entry.json - Ready-to-add marketplace entry

7. claudemd-additions.md - Documentation updates for CLAUDE.md

8. generation-log.md - Record of what was generated and any decisions made

Quality Checks

Before finishing, verify:

• [ ] All files use consistent skill name
• [ ] Benchmarks match Phase 1-2 data
• [ ] Cluster names match Phase 3 definitions
• [ ] Phase files follow repository conventions
• [ ] Technique guides have corpus examples (not invented ones)
• [ ] Decision tree matches cluster definitions
• [ ] Model recommendations are appropriate
• [ ] YAML frontmatter is valid
• [ ] JSON files are valid

Guiding Principles

1. Templates constrain: Follow the template structure; don't invent novel formats.

2. Data drives content: Every benchmark, percentage, and example should trace to analysis.

3. Consistency over creativity: Match existing skill conventions for user familiarity.

4. Examples from corpus: Use real quotes from analyzed articles, not invented examples.

5. Appropriate scope: Generate what the model skill has; don't add extra components.

When You're Done

Return a summary to the orchestrator that includes: 1. Files generated (complete list) 2. Skill structure (number of phases, clusters, techniques) 3. Key benchmarks included 4. Any adaptation decisions (where you deviated from model skill) 5. Files ready for review (SKILL.md, cluster profiles) 6. Marketplace entry ready 7. CLAUDE.md updates drafted 8. Recommendation to proceed to Phase 5 (validation)

Phase 5: Validation & Testing

You are executing Phase 5 of the genre-skill-builder workflow. Your goal is to verify the generated skill's quality and optionally test it with sample input.

Why This Phase Matters

Validation catches errors before the skill is used. A skill with incorrect benchmarks, mismatched cluster definitions, or broken file references will mislead users. This phase ensures quality and builds confidence.

Inputs

Before starting, read: 1. All files in /output/plugins/[skill-name]/ 2. /analysis/phase3-clusters/cluster-benchmarks.json - Source data 3. /analysis/phase4-generation/generation-log.md - Generation decisions 4. The model skill (for comparison)

Your Tasks

1. Syntax Validation

Check all files for correct formatting:

YAML frontmatter:

# Each SKILL.md must have valid YAML
---
name: skill-name
description: Description here
---

• [ ] SKILL.md has valid YAML frontmatter
• [ ] Name matches plugin.json
• [ ] Description is present and reasonable length

JSON files:

• [ ] plugin.json is valid JSON
• [ ] All required fields present (name, version, description, skills)

Markdown structure:

• [ ] All headers use consistent levels (# for title, ## for sections)
• [ ] All tables have valid markdown syntax
• [ ] All code blocks are properly fenced

2. Data Accuracy Validation

Verify benchmarks match analysis data:

## Benchmark Verification

### SKILL.md Statistics
| Metric | In SKILL.md | In Analysis | Match? |
|--------|-------------|-------------|--------|
| Median word count | [X] | [Y] | [✓/✗] |
| Median paragraphs | [X] | [Y] | [✓/✗] |
| [Other metrics...] | ... | ... | ... |

### Cluster Prevalences
| Cluster | In SKILL.md | In Analysis | Match? |
|---------|-------------|-------------|--------|
| [Cluster 1] | [X]% | [Y]% | [✓/✗] |
| [Cluster 2] | [X]% | [Y]% | [✓/✗] |

Flag any discrepancies for correction.

3. Cluster Coverage Validation

Verify all clusters are properly documented:

## Cluster Coverage

| Cluster | In SKILL.md | Has Profile | Has Exemplar | Complete? |
|---------|-------------|-------------|--------------|-----------|
| [Cluster 1] | ✓ | ✓ | ✓ | ✓ |
| [Cluster 2] | ✓ | ✓ | ✓ | ✓ |

• [ ] All clusters mentioned in SKILL.md have profile files
• [ ] All cluster profiles have benchmarks section
• [ ] All cluster profiles have signature moves
• [ ] All cluster profiles have exemplars
• [ ] Decision tree covers all clusters

4. Internal Consistency Validation

Check cross-file consistency:

Naming consistency:

• [ ] Cluster names match across SKILL.md and cluster profile filenames
• [ ] Skill name matches across all files
• [ ] Phase names match between SKILL.md and phase files

Reference integrity:

• [ ] All file references in SKILL.md point to existing files
• [ ] Technique guide references match actual technique files
• [ ] Cluster guide references match actual cluster files

Phase flow:

• [ ] Phase numbers are sequential
• [ ] Phase goals align with overall workflow
• [ ] Pause points are marked

5. Content Quality Validation

Assess the quality of generated content:

SKILL.md quality:

• [ ] Introduction clearly explains what the skill does
• [ ] Core principles are specific to this genre (not generic)
• [ ] Key statistics are prominently displayed
• [ ] Cluster decision tree is actionable
• [ ] Model recommendations are appropriate

Cluster profile quality:

• [ ] Each cluster has distinctive characteristics
• [ ] Signature moves include concrete examples
• [ ] Prohibited moves explain why to avoid
• [ ] Checklists are actionable

Technique guide quality:

• [ ] Techniques are specific to this section type
• [ ] Examples are from the corpus (not invented)
• [ ] Quick references are usable

6. Comparison to Model Skill

Compare generated skill to its model:

## Model Skill Comparison

### Structure Match
| Component | Model Skill | Generated Skill | Match? |
|-----------|-------------|-----------------|--------|
| Phase count | [n] | [n] | [✓/✗] |
| Cluster count | [n] | [n] | [✓/✗] |
| Technique guides | [n] | [n] | [✓/✗] |

### Quality Comparison
- [ ] SKILL.md is similar length and depth
- [ ] Cluster profiles have comparable detail
- [ ] Phase files follow same structure
- [ ] Technique guides have similar comprehensiveness

### Intentional Differences
[Document any deliberate departures from model and why]

7. Marketplace Validation

Run the same validation that CI uses to ensure the plugin will pass automated checks:

# Run this validation script before pushing
import json
from pathlib import Path

# Paths - adjust skill_name as needed
skill_name = "[skill-name]"
plugin_root = Path(f"output/plugins/{skill_name}")
manifest = plugin_root / ".claude-plugin" / "plugin.json"

# Check 1: plugin.json exists
if not manifest.exists():
    print(f"❌ CRITICAL: Missing {manifest}")
else:
    manifest_data = json.loads(manifest.read_text())

    # Check 2: Name matches
    if manifest_data.get("name") != skill_name:
        print(f"❌ CRITICAL: plugin.json name '{manifest_data.get('name')}' doesn't match '{skill_name}'")
    else:
        print(f"✓ Name matches: {skill_name}")

    # Check 3: Skills is a string path (NOT an array)
    skills_path = manifest_data.get("skills")
    if not skills_path:
        print("❌ CRITICAL: plugin.json missing 'skills' field")
    elif isinstance(skills_path, list):
        print("❌ CRITICAL: 'skills' must be a string path (e.g., './skills/'), not an array")
    elif not (plugin_root / skills_path).exists():
        print(f"❌ CRITICAL: skills path '{skills_path}' doesn't exist")
    else:
        print(f"✓ Skills path valid: {skills_path}")

# Check 4: Validate marketplace entry format
marketplace_entry = Path(f"analysis/phase4-generation/marketplace-entry.json")
if marketplace_entry.exists():
    entry = json.loads(marketplace_entry.read_text())
    if entry.get("strict") is not True:
        print("❌ CRITICAL: marketplace entry must have 'strict': true")
    else:
        print("✓ Marketplace entry has strict: true")
    if not entry.get("source", "").startswith("./plugins/"):
        print(f"❌ WARNING: source should be './plugins/{skill_name}'")
    else:
        print(f"✓ Source path correct")

Checklist:

• [ ] plugin.json exists at correct location
• [ ] plugin.json name matches skill name
• [ ] plugin.json has "skills": "./skills/" (string, not array)
• [ ] Skills directory exists at that path
• [ ] Marketplace entry has "strict": true
• [ ] Marketplace entry has correct source path

Common Errors to Avoid:

8. Optional: Test Run

If the user provides a sample article or writing task, test the skill:

## Test Run Results

### Test Input
- **Task**: [What user asked skill to help with]
- **User's draft/notes**: [What they provided]

### Skill Application
1. **Cluster identification**: Applied decision tree → [Cluster X]
2. **Benchmark check**: User's draft has [n] words vs. target [range]
3. **Guidance relevance**: [How well did cluster guidance apply?]

### Issues Identified
- [Any problems encountered during test]
- [Guidance that didn't quite fit]
- [Missing elements]

### Test Verdict
[Pass / Pass with notes / Needs revision]

9. Generate Validation Report

Compile all findings:

# Validation Report: [Skill Name]

## Summary
- **Files generated**: [n]
- **Validation checks passed**: [n]/[total]
- **Critical issues**: [n]
- **Minor issues**: [n]
- **Overall status**: [Ready / Needs revision]

## Critical Issues (must fix)
1. [Issue description and location]
2. [Issue description and location]

## Minor Issues (should fix)
1. [Issue description and location]
2. [Issue description and location]

## Warnings (consider fixing)
1. [Issue description and location]

## Verified Components
- [x] plugin.json valid
- [x] plugin.json uses string skills path (not array)
- [x] Marketplace entry has strict: true
- [x] SKILL.md structure correct
- [x] All cluster profiles present
- [x] Benchmarks accurate
- [x] [etc.]

## Recommendations
[Final recommendations for the skill]

Output Files to Create

Save all outputs to /analysis/phase5-validation/:

1. validation-report.md - Complete validation findings

2. benchmark-verification.md - Data accuracy checks

3. consistency-check.md - Cross-file consistency results

4. test-run-results.md - Test results (if test was run)

5. corrections-needed.md - List of issues to fix (if any)

Issue Severity Definitions

Critical (must fix before use):

• Incorrect benchmarks that would mislead users
• Missing cluster profiles
• Broken file references
• Invalid JSON/YAML
• plugin.json uses array for skills (must be string path)
• Marketplace entry missing strict: true

Minor (should fix):

• Inconsistent capitalization
• Missing examples in technique guides
• Vague guidance in cluster profiles

Warning (consider fixing):

• Cluster with very low prevalence (<10%)
• Unusually long/short files compared to model
• Missing optional components

Guiding Principles

1. Accuracy over completeness: Better to flag an issue than let errors through.

2. User perspective: Would a user following this skill get good results?

3. Compare to model: Significant departures from model skill need justification.

4. Document everything: Even minor issues should be noted for future reference.

5. Test if possible: Real-world testing reveals problems validation misses.

When You're Done

Return a summary to the orchestrator that includes: 1. Overall validation status (Ready / Needs revision) 2. Critical issues count and description 3. Minor issues count 4. Files verified 5. Benchmark accuracy confirmed 6. Marketplace validation passed (plugin.json format, strict: true) 7. Test results (if tested) 8. Recommendations for improvement 9. Next steps (fix issues / finalize / publish)

If issues were found, provide specific guidance on what to fix before the skill is ready for use.

Cluster Profile Template

Use this template when generating cluster profile files for a new writing skill. Each cluster gets its own file in the clusters/ directory.

---

# Cluster {{N}}: {{Cluster Name}}

**Prevalence**: {{percentage}}% of corpus ({{rank: most common / second most common / etc.}})

**Contribution logic**: "{{One-sentence description of what articles in this cluster accomplish}}"

---

## Identifying {{Cluster Name}} Articles

Your article is {{Cluster Name}} if:
- {{Primary criterion—must be true}}
- {{Secondary criterion}}
- {{Tertiary criterion}}

**Key indicators**:
- {{Observable feature 1}}
- {{Observable feature 2}}
- {{Observable feature 3}}

---

## {{Section Type}} Signature

### Key Statistics
| Feature | Typical Value |
|---------|---------------|
| Word count | {{range}} ({{comparison to corpus: shortest/longest/typical}}) |
| Paragraphs | {{range}} |
| {{Feature 3}} | {{value}} |
| {{Feature 4}} | {{value}} |
| {{Feature 5}} | {{value}} |

### Opening Move
**Use {{dominant opening type}}** ({{percentage}}% of {{Cluster Name}} do this).

> "{{Example opening sentence from corpus}}"

{{#if alternative_acceptable}}
Alternative: {{alternative opening type}} is acceptable when {{condition}}.
{{/if}}

### Structure
1. **{{Element 1}}** ({{length guidance}}): {{What it does}}
2. **{{Element 2}}** ({{length guidance}}): {{What it does}}
3. **{{Element 3}}** ({{length guidance}}): {{What it does}}
4. **{{Element 4}}** ({{length guidance}}): {{What it does}}
{{#if more elements}}
5. **{{Element 5}}** ({{length guidance}}): {{What it does}}
{{/if}}

### {{Distinctive Feature}}
{{Description of what makes this cluster's approach distinctive}}

> "{{Example quote demonstrating the feature}}"

### Tone
- {{Tone characteristic 1}}
- {{Tone characteristic 2}}
- {{Tone characteristic 3}}

---

## Signature Moves (Do This)

### 1. {{Move 1 Name}}
{{Description of the move and why it's characteristic}}

> "{{Example from corpus}}"
> — {{Article identifier if appropriate}}

### 2. {{Move 2 Name}}
{{Description of the move}}

> "{{Example from corpus}}"

### 3. {{Move 3 Name}}
{{Description of the move}}

> "{{Example from corpus}}"

{{#if move4}}
### 4. {{Move 4 Name}}
{{Description of the move}}

> "{{Example from corpus}}"
{{/if}}

---

## Prohibited Moves (Don't Do This)

### 1. {{Prohibited Move 1}}
**Why to avoid**: {{Explanation}}

### 2. {{Prohibited Move 2}}
**Why to avoid**: {{Explanation}}

### 3. {{Prohibited Move 3}}
**Why to avoid**: {{Explanation}}

---

## Coherence Pattern (if applicable for intro/conclusion)

### Dominant Type
**{{Coherence type}}** ({{percentage}}%): {{Description of what this means}}

### {{Alternative Type}} Risk
**{{Risk level: Low/Moderate/High}}** ({{percentage}}%): {{When this might happen}}

### {{Another Type}}
**{{Occurrence}}** ({{percentage}}%): {{Description}}

---

## Exemplar

**{{Article identifier or filename}}**

- **{{Section type}}**: {{word count}}, {{key features}}
- **What makes it exemplary**: {{Why this article represents the cluster well}}

**Key techniques demonstrated**:
- {{Technique 1}}
- {{Technique 2}}
- {{Technique 3}}

**Notable quote**:
> "{{Quote that exemplifies the cluster's approach}}"

---

## Writing Checklist

### {{Section Type}}
- [ ] {{Checkpoint 1—opening}}
- [ ] {{Checkpoint 2—structure}}
- [ ] {{Checkpoint 3—content}}
- [ ] {{Checkpoint 4—length}}
- [ ] {{Checkpoint 5—tone}}

{{#if second_section}}
### {{Second Section Type}} (if applicable)
- [ ] {{Checkpoint 1}}
- [ ] {{Checkpoint 2}}
- [ ] {{Checkpoint 3}}
{{/if}}

### Coherence (if applicable)
- [ ] {{Coherence checkpoint 1}}
- [ ] {{Coherence checkpoint 2}}
- [ ] {{Coherence checkpoint 3}}

---

Variables Reference

---

Cluster Naming Conventions

Name clusters by their primary strategy:

Add modifiers for distinctiveness:

• "Gap-Filler Minimalist" (efficient structure)
• "Theory-Extension Framework Applier" (applies named framework)
• "Problem-Driven Pragmatist" (practical orientation)

Phase File Template

Use this template when generating phase files for a new writing skill. Adapt structure based on the phase's purpose.

---

# Phase {{N}}: {{Phase Name}}

You are executing Phase {{N}} of {{skill_name}}. Your goal is to {{goal statement}}.

## Why This Phase Matters

{{1-2 sentences explaining the purpose of this phase in the overall workflow}}

## Inputs

Before starting, {{read/gather}}:
1. {{Input 1 with path}}
2. {{Input 2 with path}}
3. {{Input 3 with path}}

## Your Tasks

### 1. {{Task 1 Name}}

{{Description of what to do}}

{{#if has_example}}
**Example**:

{{example content}}

{{/if}}

{{#if has_checklist}}
**Checklist**:
- [ ] {{Item 1}}
- [ ] {{Item 2}}
- [ ] {{Item 3}}
{{/if}}

### 2. {{Task 2 Name}}

{{Description of what to do}}

{{#if has_subtasks}}
**Sub-tasks**:
- {{Sub-task a}}
- {{Sub-task b}}
- {{Sub-task c}}
{{/if}}

### 3. {{Task 3 Name}}

{{Description of what to do}}

{{#if needs_cluster_handling}}
**Cluster-specific considerations**:
- **{{Cluster 1}}**: {{special handling}}
- **{{Cluster 2}}**: {{special handling}}
- **{{Cluster 3}}**: {{special handling}}
{{/if}}

### 4. {{Task 4 Name}} (if applicable)

{{Description}}

## Output Files to Create

Save all outputs to `{{output_path}}/`:

1. **{{file1.md}}** - {{description}}
   {{#if has_structure_example}}

{{Section}}

{{content structure}}

   {{/if}}

2. **{{file2.md}}** - {{description}}

3. **{{file3.md}}** - {{description}}

## Guiding Principles

1. **{{Principle 1 name}}**: {{Principle 1 description}}

2. **{{Principle 2 name}}**: {{Principle 2 description}}

3. **{{Principle 3 name}}**: {{Principle 3 description}}

4. **{{Principle 4 name}}**: {{Principle 4 description}}

## {{Section-specific guidance}} (if applicable)

{{Additional guidance relevant to the section type being written}}

## When You're Done

Return a summary to the orchestrator that includes:
1. {{Summary item 1}}
2. {{Summary item 2}}
3. {{Summary item 3}}
4. {{Summary item 4}}
5. Questions for the user about {{topic}}
6. Recommendation to proceed to Phase {{N+1}}

---

Phase Type Templates

Assessment Phase (Phase 0)

For phases that identify cluster and confirm scope:

Key tasks:

• Review user inputs (theory section, findings, etc.)
• Apply decision tree to identify cluster
• Confirm cluster with user
• Note any special considerations

Key outputs:

• Cluster identification memo
• Scope confirmation

Drafting Phase (Phase 1 or 2)

For phases that produce written content:

Key tasks:

• Apply cluster-specific guidance
• Follow structural template for section type
• Incorporate benchmarks (word count, paragraph count)
• Use appropriate rhetorical moves

Key outputs:

• Draft of section
• Notes on choices made

Revision/Coherence Phase (Phase 2 or 3)

For phases that review and refine:

Key tasks:

• Check against benchmarks
• Verify coherence (with other sections, with cluster norms)
• Identify gaps or issues
• Polish prose

Key outputs:

• Revised draft
• Revision memo
• Quality checklist

---

Variables Reference

SKILL.md Template

Use this template when generating the main SKILL.md file for a new writing skill. Replace all {{placeholders}} with actual values from the analysis.

---

---
name: {{skill_name}}
description: {{description}}
---

# {{Skill Title}}

You help {{target_audience}} write **{{target_section}}** for {{article_type}}. Your guidance is grounded in systematic analysis of {{corpus_size}} articles from {{venues}}.

## When to Use This Skill

Use this skill when users want to:
- {{Use case 1}}
- {{Use case 2}}
- {{Use case 3}}

This skill assumes {{prerequisites}}.

## Connection to Other Skills

| Skill | Purpose | Key Output |
|-------|---------|------------|
| **{{Related Skill 1}}** | {{Purpose}} | {{Output}} |
| **{{Related Skill 2}}** | {{Purpose}} | {{Output}} |

## Core Principles (from Genre Analysis)

Based on systematic analysis of {{corpus_size}} {{section_type}} sections:

### 1. {{Principle 1 Name}}
{{Principle 1 description—derived from analysis findings}}

### 2. {{Principle 2 Name}}
{{Principle 2 description}}

### 3. {{Principle 3 Name}}
{{Principle 3 description}}

### 4. {{Principle 4 Name}}
{{Principle 4 description}}

## Key Statistics (Benchmarks)

### {{Section Type}} Benchmarks

| Feature | Typical Value |
|---------|---------------|
| Word count | {{word_range}} |
| Paragraphs | {{para_range}} |
| {{Feature 3}} | {{value}} |
| {{Feature 4}} | {{value}} |
| {{Feature 5}} | {{value}} |

## The {{n}} Clusters

{{Section type}} sections cluster into {{n}} recognizable styles based on {{distinguishing criteria}}:

| Cluster | Prevalence | Key Feature | When to Use |
|---------|------------|-------------|-------------|
| **{{Cluster 1}}** | {{%}} | {{feature}} | {{when}} |
| **{{Cluster 2}}** | {{%}} | {{feature}} | {{when}} |
| **{{Cluster 3}}** | {{%}} | {{feature}} | {{when}} |
{{#if more clusters}}
| **{{Cluster 4}}** | {{%}} | {{feature}} | {{when}} |
| **{{Cluster 5}}** | {{%}} | {{feature}} | {{when}} |
{{/if}}

See `clusters/` directory for detailed profiles with benchmarks, signature moves, and exemplars.

## Workflow Phases

### Phase 0: {{Phase 0 Name}}
**Goal**: {{Phase 0 goal}}

**Process**:
- {{Step 1}}
- {{Step 2}}
- {{Step 3}}

**Output**: {{Phase 0 outputs}}

> **Pause**: {{What user confirms}}

---

### Phase 1: {{Phase 1 Name}}
**Goal**: {{Phase 1 goal}}

**Process**:
- {{Step 1}}
- {{Step 2}}
- {{Step 3}}

**Guides**:
- `phases/phase1-{{name}}.md` (main workflow)
- `clusters/` (cluster-specific guidance)

**Output**: {{Phase 1 outputs}}

> **Pause**: {{What user reviews}}

---

### Phase 2: {{Phase 2 Name}}
**Goal**: {{Phase 2 goal}}

**Process**:
- {{Step 1}}
- {{Step 2}}
- {{Step 3}}

**Guide**: `phases/phase2-{{name}}.md`

**Output**: {{Phase 2 outputs}}

{{#if phase3}}
> **Pause**: {{What user reviews}}

---

### Phase 3: {{Phase 3 Name}}
**Goal**: {{Phase 3 goal}}

**Process**:
- {{Step 1}}
- {{Step 2}}
- {{Step 3}}

**Guide**: `phases/phase3-{{name}}.md`

**Output**: {{Phase 3 outputs}}
{{/if}}

---

## Cluster Decision Tree

To identify which cluster your article inhabits:

1. **{{Question 1}}**
   - {{Answer A}} → likely {{Cluster X}}
   - {{Answer B}} → likely {{Cluster Y}}
   - {{Answer C}} → go to question 2

2. **{{Question 2}}**
   - {{Answer A}} → {{Cluster X}}
   - {{Answer B}} → {{Cluster Y}}

### Quick Indicators

| If you see this... | Consider this cluster... |
|--------------------|--------------------------|
| {{Indicator 1}} | {{Cluster}} |
| {{Indicator 2}} | {{Cluster}} |
| {{Indicator 3}} | {{Cluster}} |

## Cluster Profiles

Reference these guides for cluster-specific writing:

| Guide | Cluster |
|-------|---------|
| `clusters/{{cluster-1-slug}}.md` | {{Cluster 1}} ({{%}}) |
| `clusters/{{cluster-2-slug}}.md` | {{Cluster 2}} ({{%}}) |
| `clusters/{{cluster-3-slug}}.md` | {{Cluster 3}} ({{%}}) |

## Technique Guides

| Guide | Purpose |
|-------|---------|
| `techniques/{{technique-1}}.md` | {{Purpose}} |
| `techniques/{{technique-2}}.md` | {{Purpose}} |
| `techniques/{{technique-3}}.md` | {{Purpose}} |

## Prohibited Moves

### In {{Section Type}}
- {{Prohibited move 1}}
- {{Prohibited move 2}}
- {{Prohibited move 3}}

## Output Expectations

Provide the user with:
- {{Output 1}}
- {{Output 2}}
- {{Output 3}}

## Invoking Phase Agents

Use the Task tool for each phase:

Task: Phase 1 {{Phase 1 Name}} subagent_type: general-purpose model: {{recommended_model}} prompt: Read phases/phase1-{{name}}.md and the relevant cluster guide, then {{task description}}. User's {{input type}} is provided.

**Model recommendations**:
- Phase 0 ({{name}}): {{Model}}
- Phase 1 ({{name}}): {{Model}}
- Phase 2 ({{name}}): {{Model}}
{{#if phase3}}
- Phase 3 ({{name}}): {{Model}}
{{/if}}

## Starting the Process

When the user is ready to begin:

1. **Ask about the project**:
   > "{{Opening question 1}}"

2. **Ask about inputs**:
   > "{{Opening question 2}}"

3. **Identify cluster**:
   > Based on your answers, apply the decision tree and recommend a cluster.

4. **Proceed with Phase 0**.

## Key Reminders

- {{Reminder 1}}
- {{Reminder 2}}
- {{Reminder 3}}
- {{Reminder 4}}
- {{Reminder 5}}

---

Template Variables Reference

Technique Guide Template

Use this template when generating technique guides for a new writing skill. Technique guides provide sentence-level and paragraph-level craft guidance.

---

# {{Technique Guide Title}}

{{1-2 sentence description of what this guide covers and when to use it}}

---

## {{Category 1}}

### {{Type 1.1 Name}}

**When to use**: {{Context in which this technique is appropriate}}

**Signature patterns**:
- "{{Pattern A}}..."
- "{{Pattern B}}..."
- "{{Pattern C}}..."

**Examples from corpus**:
> "{{Full example sentence or passage}}"
> — {{Source if appropriate}}

> "{{Another example}}"

**Best for**: {{Which clusters or situations benefit most}}

---

### {{Type 1.2 Name}}

**When to use**: {{Context}}

**Signature patterns**:
- "{{Pattern A}}..."
- "{{Pattern B}}..."

**Examples from corpus**:
> "{{Example}}"

> "{{Example}}"

**Best for**: {{Clusters/situations}}

---

### {{Type 1.3 Name}}

**When to use**: {{Context}}

**Signature patterns**:
- "{{Pattern A}}..."
- "{{Pattern B}}..."

**Examples from corpus**:
> "{{Example}}"

**Best for**: {{Clusters/situations}}

---

## {{Category 2}}

### {{Type 2.1 Name}}

**When to use**: {{Context}}

**Signature patterns**:
- "{{Pattern A}}..."
- "{{Pattern B}}..."

**Examples from corpus**:
> "{{Example}}"

---

### {{Type 2.2 Name}}

**When to use**: {{Context}}

**Signature patterns**:
- "{{Pattern A}}..."

**Examples from corpus**:
> "{{Example}}"

---

## {{Category 3}} (if applicable)

### {{Subcategory 3.1}}

{{Content}}

### {{Subcategory 3.2}}

{{Content}}

---

## Quick Reference

### {{Reference Table 1 Title}}

| {{Column 1}} | {{Column 2}} | {{Column 3}} |
|--------------|--------------|--------------|
| {{data}} | {{data}} | {{data}} |
| {{data}} | {{data}} | {{data}} |
| {{data}} | {{data}} | {{data}} |

### {{Reference Table 2 Title}} (if applicable)

| {{Column 1}} | {{Column 2}} |
|--------------|--------------|
| {{data}} | {{data}} |
| {{data}} | {{data}} |

---

## Cluster-Specific Guidance

### {{Cluster 1}}
- {{Guidance specific to this cluster's use of these techniques}}
- {{Additional guidance}}

### {{Cluster 2}}
- {{Guidance specific to this cluster}}
- {{Additional guidance}}

### {{Cluster 3}}
- {{Guidance specific to this cluster}}
- {{Additional guidance}}

---

## Common Mistakes

### {{Mistake 1}}
**Problem**: {{What goes wrong}}
**Solution**: {{How to fix it}}

### {{Mistake 2}}
**Problem**: {{What goes wrong}}
**Solution**: {{How to fix it}}

---

Common Technique Guide Types

1. Opening Moves Guide

For any section with distinctive openings:

Categories:

• Phenomenon-led openings
• Stakes-led openings
• Theory-led openings
• Case-led openings
• Question-led openings

2. Sentence Toolbox

For prose-heavy sections:

Categories:

• Opening sentence types (literature-announcing, context-setting, etc.)
• Transition markers (additive, contrastive, temporal, causal)
• Hedging calibration
• Cluster-specific patterns

3. Structural Elements Guide

For sections with multiple components:

Categories:

• Roadmaps
• Limitations
• Future directions
• Callbacks/Codas
• Data mentions

4. Citation Patterns Guide

For theory-heavy sections:

Categories:

• Parenthetical strings
• Author-as-subject
• Quote-then-cite
• Citation density guidance

5. Coherence Guide

For paired sections (intro/conclusion):

Categories:

• Parallel coherence
• Escalation
• Bookend structure
• Vocabulary echoing
• Callback techniques

---

Variables Reference

---

Quality Criteria for Technique Guides

• [ ] All examples come from the analyzed corpus (not invented)
• [ ] Patterns are specific enough to be usable
• [ ] Categories are mutually exclusive
• [ ] Cluster-specific guidance is included
• [ ] Quick reference tables enable fast lookup
• [ ] Common mistakes address real pitfalls