Collection

---
name: writing-rules
description: Extract and manage writing rules (style, structure, persona, publisher, custom) (project)
---

# Writing Rules Skill

## Overview

Unified system for extracting writing rules AND managing the extensible rule type registry. Handles both rule extraction operations and registry management operations.

**For usage examples and workflows, see `CLAUDE.md`.**

---

## Operations

### Extraction Operations

**style** - Extract style guidelines (voice, tone, word choice)
- Entry: `writing-rules-skill style --type <mode> --auto-discover`
- Modes: primary, technical-docs, blog, etc.
- Output: `rules/style/<descriptive-name>.md`

**structure** - Extract structure templates (document organization, section flow)
- Entry: `writing-rules-skill structure --type <mode> --auto-discover`
- Modes: tutorial, landing-page, api-reference, etc.
- Output: `rules/structure/<descriptive-name>.md`

**persona** - Extract target personas (audience roles, pain points, preferences)
- Entry: `writing-rules-skill persona --audience-type <type> --auto-discover`
- Types: technical, business, all, etc.
- Output: `rules/personas/<descriptive-name>.md`

**publisher** - Extract publisher profile (company identity, messaging, positioning)
- Entry: `writing-rules-skill publisher --auto-discover`
- Output: `rules/publisher/publisher-profile.md` (single file)

**[custom-type]** - Extract custom rule types (if configured in registry)
- Entry: `writing-rules-skill <custom-type> --type <mode> --auto-discover`
- Output: `rules/<custom-type>/<descriptive-name>.md`

### Update Operations (Feedback-Driven)

**style --update** - Update existing style rule based on recent feedback
- Entry: `writing-rules-skill style --type <type> --update`
- Requires: Existing style rule + recent tone/style feedback
- Output: Updated style rule with backup
- Subskill: `subskills/update-style.md`

**structure --update** - Update existing structure template based on recent feedback
- Entry: `writing-rules-skill structure --type <type> --update`
- Requires: Existing structure template + recent structure/organization feedback
- Output: Updated structure template with backup
- Subskill: `subskills/update-structure.md`

**persona --update** - Update existing persona based on recent feedback
- Entry: `writing-rules-skill persona --audience-type <type> --update`
- Requires: Existing persona + recent info/length/comprehension feedback
- Output: Updated persona with backup
- Subskill: `subskills/update-persona.md`

### Management Operations

**list** - List all rule types (built-in + custom) with extraction status
- Entry: `writing-rules-skill list`

**show** - Show details about a specific rule type
- Entry: `writing-rules-skill show <type>`

**add** - Add new custom rule type (interactive wizard with conflict detection)
- Entry: `writing-rules-skill add`

**validate** - Validate registry configuration and file system consistency
- Entry: `writing-rules-skill validate`

**generate-subskill** - Generate extraction subskill for custom type
- Entry: `writing-rules-skill generate-subskill <custom-type>`

**onboard** - Onboarding wizard for new teams
- Entry: `writing-rules-skill onboard`

---

## Technical Details

### Routing Logic

1. **Parse arguments** - Determine operation type and parameters
2. **Load context:**
   - Registry: Read `rules/rules-config.yaml`
   - Project context (if available)
   - Source content status
   - Existing rules
   - Feedback data (for update operations)
3. **Route to subskill:**
   - Management ops → `subskills/manage-<operation>.md`
   - Extraction ops → `subskills/extract-<type>.md`
   - Update ops (--update flag) → `subskills/update-<type>.md`
4. **Pass context** - Provide all necessary info to subskill

### Preview Mode (Iterative Extraction)

When invoked from extract-rules subskill:

**Pattern:** Analyze → Preview → Approve → Extract

1. **Analyze available content** - Group indexed documents by type, domain, date
2. **Preview sample documents** - Show 3-5 examples with coverage stats
3. **Get approval** - User can approve, refine (use different docs), or skip
4. **Execute extraction** - Run with --auto-discover on approved document set
5. **Review results** - Show extracted rule file and key characteristics

**Why preview?**
- Ensures right documents analyzed
- Shows coverage before expensive AI analysis
- Allows refinement if wrong documents selected

### Registry Configuration

**Location:** `rules/rules-config.yaml`

**Defines:**
- Which rule types are enabled (built-in + custom)
- What each type extracts and governs
- Directory locations for each type
- Extraction settings (discovery modes, sample size)

**Built-in types** (always available):
- style, structure, persona, publisher

**Custom types** (team-configurable):
- verticals, use-cases, channels, journey-stages, etc.

### Extraction Modes

**Incremental** (default - recommended):
- Compares with existing rules
- Creates new files only if distinct patterns found
- Safe, additive approach

**Overwrite** (nuclear option):
- Deletes existing rules in category
- Performs fresh analysis
- Use when rules are outdated

---

## Integration with Other Skills

**Called by:**
- **extract-rules subskill** - Routes extraction requests here with preview mode
- **check-onboarding subskill** - For extracting core rules (publisher, primary voice, personas)
- **feedback-skill patterns subskill** - Recommends update operations when patterns emerge
- Direct invocation for rule extraction or updates

**Delegates to:**
- **Extraction subskills** - Type-specific extraction logic in `subskills/extract-<type>.md`
- **Update subskills** - Feedback-driven updates in `subskills/update-<type>.md`
- **Management subskills** - Registry operations in `subskills/manage-<operation>.md`

**Works with:**
- **project-management-skill** - Rules are referenced in project.md
- **content-writing-skill** - Rules are applied during content creation
- **feedback-skill** - Provides feedback data to drive rule updates

---

## Key Principles

1. **Registry as source of truth** - All rule types defined in rules-config.yaml
2. **Extensibility** - Custom types via registry configuration
3. **Preview before extraction** - Always show sample documents for approval
4. **Incremental by default** - Don't overwrite existing rules unless explicitly requested
5. **Quality over quantity** - Need 3-5 documents minimum for reliable extraction
6. **Type-specific extraction** - Each type has specialized extraction logic
7. **Feedback-driven updates** - Use real user feedback to improve rules over time
8. **User control** - Always show diff preview and get approval before updating rules

---

For usage examples and workflows, see **`CLAUDE.md`**.
For registry configuration details, see `README.md` in this skill directory.