Project 23: Output Style Library - Shareable Style Ecosystem

Project 23: Output Style Library - Shareable Style Ecosystem

Build a complete ecosystem for sharing, discovering, and managing Claude Code output styles: a CLI tool for search, install, and validation, plus a community registry for style distribution.

Quick Reference

Attribute Value
Difficulty Advanced (Level 3)
Time Estimate 2 weeks
Language Bash + JSON (Alternatives: Python, TypeScript/Bun)
Prerequisites Projects 21-22 completed, Project 14 (skill marketplace) patterns, basic package management understanding
Key Topics Style validation, registry design, version management, community distribution, CLI tools
Claude Code Features Output Styles, YAML frontmatter, ~/.claude/output-styles/ directory

1. Learning Objectives

By completing this project, you will:

  1. Design package ecosystems: Understand how package managers (npm, pip, brew) work and apply those patterns to AI configuration
  2. Implement schema validation: Build validators that verify output styles are correctly formatted and complete
  3. Create distribution systems: Design registries for discovering and sharing community contributions
  4. Build developer-friendly CLIs: Create intuitive command-line interfaces following Unix conventions
  5. Handle versioning: Implement semantic versioning for configuration files
  6. Manage open source workflows: Learn contribution patterns, code review, and community management

2. Deep Theoretical Foundation

2.1 The Problem: Isolated Configuration

Output styles are powerful but currently isolated. Each developer creates their own, with no way to:

  • Discover what others have created
  • Share successful patterns with teammates
  • Benefit from community improvements
  • Ensure consistency across teams
                    CURRENT STATE: ISOLATED STYLES

    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
    │   Developer A   │    │   Developer B   │    │   Developer C   │
    │                 │    │                 │    │                 │
    │  ┌───────────┐  │    │  ┌───────────┐  │    │  ┌───────────┐  │
    │  │tech-writer│  │    │  │tech-docs  │  │    │  │doc-helper │  │
    │  │(v1.0)     │  │    │  │(v2.1)     │  │    │  │(v1.5)     │  │
    │  └───────────┘  │    │  └───────────┘  │    │  └───────────┘  │
    │                 │    │                 │    │                 │
    │  All solving    │    │  Same problem   │    │  Duplicate     │
    │  same problem   │    │  independently  │    │  effort        │
    └─────────────────┘    └─────────────────┘    └─────────────────┘

                                   │
                                   ▼

                    DESIRED STATE: SHARED ECOSYSTEM

    ┌─────────────────────────────────────────────────────────────────┐
    │                    STYLE REGISTRY                                │
    │                                                                  │
    │   ┌───────────────────────────────────────────────────────────┐ │
    │   │ tech-writer@2.1.0                                         │ │
    │   │ "Technical documentation with formal tone"                │ │
    │   │ Downloads: 1,234 | ⭐ 4.8 | Author: @expert_writer         │ │
    │   └───────────────────────────────────────────────────────────┘ │
    │                                                                  │
    │   ┌───────────────────────────────────────────────────────────┐ │
    │   │ code-review@1.5.0                                         │ │
    │   │ "Systematic code review assistant"                        │ │
    │   │ Downloads: 892 | ⭐ 4.6 | Author: @review_pro              │ │
    │   └───────────────────────────────────────────────────────────┘ │
    │                                                                  │
    └────────────────────────────────┬────────────────────────────────┘
                                     │
            ┌────────────────────────┼────────────────────────┐
            │                        │                        │
            ▼                        ▼                        ▼
    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
    │   Developer A   │    │   Developer B   │    │   Developer C   │
    │                 │    │                 │    │                 │
    │  $ claude-styles│    │  $ claude-styles│    │  $ claude-styles│
    │    install      │    │    install      │    │    install      │
    │    tech-writer  │    │    tech-writer  │    │    tech-writer  │
    │                 │    │                 │    │                 │
    │  Same style,    │    │  Consistent     │    │  Community      │
    │  automatic      │    │  across team    │    │  updates        │
    │  updates        │    │                 │    │                 │
    └─────────────────┘    └─────────────────┘    └─────────────────┘

2.2 Package Manager Architecture Patterns

From “Software Engineering at Google” (Winters et al.), package ecosystems share common patterns:

                    PACKAGE MANAGER ARCHITECTURE

    ┌─────────────────────────────────────────────────────────────────┐
    │                          CLI TOOL                                │
    │                                                                  │
    │   ┌─────────────────────────────────────────────────────────┐   │
    │   │ COMMANDS                                                 │   │
    │   │                                                          │   │
    │   │ search <query>   - Find packages by name/keyword        │   │
    │   │ install <name>   - Download and install package         │   │
    │   │ uninstall <name> - Remove installed package             │   │
    │   │ list             - Show installed packages               │   │
    │   │ update [name]    - Update to latest version              │   │
    │   │ validate <file>  - Check package is well-formed         │   │
    │   │ publish <file>   - Submit to registry                   │   │
    │   └─────────────────────────────────────────────────────────┘   │
    │                              │                                   │
    └──────────────────────────────┼───────────────────────────────────┘
                                   │
                                   ▼
    ┌─────────────────────────────────────────────────────────────────┐
    │                        REGISTRY                                  │
    │                                                                  │
    │   ┌─────────────────┐   ┌─────────────────┐                     │
    │   │ index.json      │   │ Package Storage │                     │
    │   │                 │   │                 │                     │
    │   │ - Package list  │   │ - Raw files     │                     │
    │   │ - Metadata      │   │ - Version dirs  │                     │
    │   │ - Downloads     │   │ - Checksums     │                     │
    │   │ - Ratings       │   │                 │                     │
    │   └─────────────────┘   └─────────────────┘                     │
    │                                                                  │
    │   Protocol: HTTPS                                               │
    │   Format: JSON for metadata, raw files for content              │
    │   Versioning: Semantic versioning (major.minor.patch)           │
    │                                                                  │
    └─────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
    ┌─────────────────────────────────────────────────────────────────┐
    │                     LOCAL STORAGE                                │
    │                                                                  │
    │   ~/.claude/output-styles/                                      │
    │   ├── tech-writer.md                                            │
    │   ├── code-review.md                                            │
    │   └── .registry/                                                │
    │       ├── installed.json  (tracking file)                       │
    │       └── cache/          (downloaded metadata)                 │
    │                                                                  │
    └─────────────────────────────────────────────────────────────────┘

2.3 Style Validation Requirements

Before sharing styles, they must be validated. A valid output style:

---
name: style-name          # REQUIRED: Identifier (a-z, 0-9, hyphens)
description: Description  # OPTIONAL but recommended
keep-coding-instructions: true/false  # OPTIONAL, defaults to true
version: 1.0.0           # REQUIRED for registry (semver)
author: @username        # REQUIRED for registry
license: MIT             # OPTIONAL, defaults to MIT
tags:                    # OPTIONAL for discovery
  - documentation
  - technical
---

# Style Content

[At least 10 lines of meaningful content]

Validation Rules:

                    VALIDATION CHECKLIST

    ┌─────────────────────────────────────────────────────────────────┐
    │                    FRONTMATTER VALIDATION                        │
    ├─────────────────────────────────────────────────────────────────┤
    │                                                                  │
    │   [ ] name: Required                                            │
    │       - Format: lowercase, alphanumeric, hyphens only           │
    │       - Length: 2-50 characters                                 │
    │       - Must be unique in registry                              │
    │                                                                  │
    │   [ ] version: Required for registry                            │
    │       - Format: semver (X.Y.Z)                                  │
    │       - Must be higher than existing versions                   │
    │                                                                  │
    │   [ ] description: Recommended                                  │
    │       - Length: 10-200 characters                               │
    │       - No markdown in description                              │
    │                                                                  │
    │   [ ] keep-coding-instructions: Optional                        │
    │       - Must be boolean if present                              │
    │                                                                  │
    │   [ ] author: Required for registry                             │
    │       - Format: @username or email                              │
    │                                                                  │
    │   [ ] tags: Optional                                            │
    │       - Array of lowercase strings                              │
    │       - Max 5 tags                                              │
    │                                                                  │
    └─────────────────────────────────────────────────────────────────┘

    ┌─────────────────────────────────────────────────────────────────┐
    │                     CONTENT VALIDATION                           │
    ├─────────────────────────────────────────────────────────────────┤
    │                                                                  │
    │   [ ] Markdown body exists and is non-empty                     │
    │                                                                  │
    │   [ ] Minimum 10 lines of content (excluding empty lines)       │
    │                                                                  │
    │   [ ] At least one heading (# or ##)                            │
    │                                                                  │
    │   [ ] No obvious placeholder text ("TODO", "XXX")               │
    │                                                                  │
    │   [ ] No sensitive data (API keys, passwords)                   │
    │                                                                  │
    │   [ ] Valid markdown syntax                                     │
    │                                                                  │
    └─────────────────────────────────────────────────────────────────┘

2.4 Registry Design

A simple registry uses GitHub as a backend:

                    GITHUB-BASED REGISTRY

    github.com/claude-styles/registry/
    │
    ├── index.json                    # Main registry index
    │   {
    │     "styles": [
    │       {
    │         "name": "tech-writer",
    │         "version": "2.1.0",
    │         "description": "Technical documentation...",
    │         "author": "@expert_writer",
    │         "url": "https://raw.githubusercontent.com/...",
    │         "downloads": 1234,
    │         "rating": 4.8,
    │         "tags": ["documentation", "technical"]
    │       },
    │       ...
    │     ],
    │     "updated": "2025-01-15T10:30:00Z"
    │   }
    │
    ├── styles/                       # Raw style files
    │   ├── tech-writer/
    │   │   ├── 2.1.0.md             # Versioned files
    │   │   ├── 2.0.0.md
    │   │   └── 1.0.0.md
    │   │
    │   ├── code-review/
    │   │   └── 1.5.0.md
    │   │
    │   └── ...
    │
    └── README.md                     # Contribution guide

Index Schema:

interface StyleIndex {
  styles: StyleMetadata[];
  updated: string;  // ISO 8601 timestamp
}

interface StyleMetadata {
  name: string;
  version: string;
  description: string;
  author: string;
  url: string;
  downloads: number;
  rating: number;
  tags: string[];
  created: string;
  updated: string;
  dependencies?: string[];  // Other styles this depends on
}

2.5 Version Management with Semantic Versioning

From the semver specification:

                    SEMANTIC VERSIONING

    MAJOR.MINOR.PATCH
    │     │     │
    │     │     └── Bug fixes, clarifications
    │     │         (2.1.0 → 2.1.1)
    │     │
    │     └────── New features, backward compatible
    │             (2.0.0 → 2.1.0)
    │
    └────────── Breaking changes
                (1.x.x → 2.0.0)

    For Output Styles:
    ─────────────────

    MAJOR bump when:
    • Fundamentally different output format
    • Removed sections or requirements
    • Changed tone significantly

    MINOR bump when:
    • Added new optional sections
    • Enhanced existing behavior
    • Added new keywords/patterns

    PATCH bump when:
    • Fixed typos
    • Clarified instructions
    • Minor wording improvements

2.6 Installation and Conflict Resolution

                    INSTALLATION WORKFLOW

    ┌──────────────────────────────────────────────────────────────────┐
    │                                                                   │
    │   $ claude-styles install tech-writer@2.1.0                      │
    │                                                                   │
    └───────────────────────────────┬──────────────────────────────────┘
                                    │
                                    ▼
    ┌──────────────────────────────────────────────────────────────────┐
    │                    1. FETCH METADATA                              │
    │                                                                   │
    │   GET https://registry/index.json                                │
    │   → Find style "tech-writer" version "2.1.0"                     │
    │   → Get download URL                                              │
    │                                                                   │
    └───────────────────────────────┬──────────────────────────────────┘
                                    │
                                    ▼
    ┌──────────────────────────────────────────────────────────────────┐
    │                    2. CHECK CONFLICTS                             │
    │                                                                   │
    │   Does ~/.claude/output-styles/tech-writer.md exist?             │
    │                                                                   │
    │   IF YES:                                                        │
    │   ├── Is it the same version? → Already installed, skip         │
    │   ├── Is it a different version? → Ask: upgrade or keep?        │
    │   └── Is it a local file (no version)? → Warn and backup        │
    │                                                                   │
    └───────────────────────────────┬──────────────────────────────────┘
                                    │
                                    ▼
    ┌──────────────────────────────────────────────────────────────────┐
    │                    3. DOWNLOAD AND VALIDATE                       │
    │                                                                   │
    │   GET https://registry/styles/tech-writer/2.1.0.md               │
    │   → Validate frontmatter                                         │
    │   → Check content requirements                                   │
    │   → Verify checksum (if provided)                                │
    │                                                                   │
    └───────────────────────────────┬──────────────────────────────────┘
                                    │
                                    ▼
    ┌──────────────────────────────────────────────────────────────────┐
    │                    4. INSTALL                                     │
    │                                                                   │
    │   WRITE ~/.claude/output-styles/tech-writer.md                   │
    │   UPDATE ~/.claude/output-styles/.registry/installed.json        │
    │                                                                   │
    │   installed.json:                                                │
    │   {                                                              │
    │     "tech-writer": {                                             │
    │       "version": "2.1.0",                                        │
    │       "installed": "2025-01-15T10:30:00Z",                       │
    │       "source": "registry"                                       │
    │     }                                                            │
    │   }                                                              │
    │                                                                   │
    └───────────────────────────────┬──────────────────────────────────┘
                                    │
                                    ▼
    ┌──────────────────────────────────────────────────────────────────┐
    │                    5. CONFIRM                                     │
    │                                                                   │
    │   ✅ Installed tech-writer@2.1.0                                  │
    │   Use with: claude --output-style tech-writer                    │
    │                                                                   │
    └──────────────────────────────────────────────────────────────────┘

3. The Core Question You’re Answering

“How can I create an ecosystem for sharing and discovering output styles, enabling community contributions?”

Output styles are powerful but currently isolated. This project creates infrastructure for the Claude Code community to share, discover, and collaborate on behavior customizations.

4. Concepts You Must Understand First

Stop and research these before coding:

4.1 Style Validation

  • What makes a valid output style?
  • Required frontmatter fields?
  • Markdown body requirements?
  • Reference: Claude Code Docs - Output Styles

4.2 Registry Design

  • How to organize styles (categories, tags)?
  • Metadata for discovery (ratings, downloads)?
  • Version management?
  • Reference: npm registry patterns, Homebrew tap structure

4.3 Installation Workflow

  • Where do styles get installed (~/.claude/output-styles/)?
  • How to handle conflicts?
  • User vs project scope?

4.4 CLI Design

  • Unix command conventions
  • User-friendly output formatting
  • Error handling and messaging
  • Reference: “The Art of Unix Programming” by Eric Raymond

5. Questions to Guide Your Design

Before implementing, think through these:

5.1 Registry Storage

Where should the registry live?

  • GitHub: Simple, free, PRs for contributions
  • Custom Server: More control, requires hosting
  • Distributed: Multiple registries, federation

5.2 Metadata Structure

What information is needed for each style?

  • Name, version, description
  • Author, license
  • Download count, ratings
  • Tags for categorization
  • Dependencies (optional)

5.3 Update Strategy

How do users get updates?

  • Manual: claude-styles update tech-writer
  • Check on use: Warn if newer version available
  • Automatic: Background updates (risky)

6. Thinking Exercise

Design Your Registry Schema

Before writing code, sketch out the data structures:

// index.json structure
{
  "styles": [
    {
      "name": "tech-writer",
      "version": "2.1.0",
      "description": "...",
      // What other fields?
    }
  ]
}

# tech-writer.md - The actual output style
---
name: tech-writer
description: Technical writing assistant
keep-coding-instructions: true
version: 2.1.0
author: @expert_writer
tags:
  - documentation
  - technical
---

[Style content here]

Design Questions:

  1. Should metadata be in the style file or separate?
    • In file: Self-contained, version always matches
    • Separate: Easier to query, but can become inconsistent
  2. How do you handle style updates?
    • Immutable versions (new file for each version)
    • Mutable (overwrite existing)
  3. What about style dependencies?
    • Style A requires Style B to be installed
    • Shared base styles extended by specific ones

7. Real World Outcome

7.1 Example CLI Session

$ claude-styles search "documentation"

Found 5 output styles:

📝 tech-writer (v2.1.0)
   Technical documentation with formal tone
   ⭐ 4.8 | Downloads: 1,234 | Tags: documentation, technical

📝 api-docs (v1.5.0)
   REST API documentation generator
   ⭐ 4.6 | Downloads: 892 | Tags: api, documentation

📝 changelog (v1.0.3)
   Structured changelog entries
   ⭐ 4.5 | Downloads: 567 | Tags: changelog, releases

📝 tutorial-writer (v1.2.0)
   Step-by-step tutorial creator
   ⭐ 4.3 | Downloads: 445 | Tags: tutorial, education

📝 readme-generator (v2.0.0)
   README.md file generator
   ⭐ 4.1 | Downloads: 321 | Tags: readme, documentation

---

$ claude-styles install tech-writer

📦 Installing tech-writer@2.1.0...
   Downloaded from github.com/claude-styles/registry
   Validated frontmatter and content
   Installed to ~/.claude/output-styles/tech-writer.md

✅ Installed! Use with: claude --output-style tech-writer

---

$ claude-styles list

Installed Output Styles:
  ├── tech-writer   2.1.0   Technical documentation with formal tone
  ├── code-review   1.2.0   Code review assistant
  └── learning      1.0.0   Educational explanations

3 styles installed

---

$ claude-styles validate ./my-custom-style.md

Validating my-custom-style.md...

✅ Frontmatter:
   ├── name: my-custom-style ✓
   ├── version: 1.0.0 ✓
   ├── description: "Custom style for my team" ✓
   └── keep-coding-instructions: true ✓

✅ Content:
   ├── Line count: 45 (minimum 10) ✓
   ├── Has headings: yes ✓
   └── No placeholder text: yes ✓

✅ Valid output style! Ready for use or publication.

---

$ claude-styles update tech-writer

Checking for updates...

tech-writer: 2.1.0 → 2.2.0 available

Changes in 2.2.0:
  • Added RFC-style proposal templates
  • Improved ASCII diagram guidelines
  • Fixed typo in example output

Update? [Y/n] y

📦 Updating tech-writer to 2.2.0...
   Downloaded new version
   Backed up previous version to tech-writer.2.1.0.bak

✅ Updated to tech-writer@2.2.0

---

$ claude-styles publish ./my-custom-style.md

Publishing my-custom-style@1.0.0...

✅ Validated style
✅ Checked name availability
✅ Created pull request: github.com/claude-styles/registry/pull/42

Your style will be reviewed and published once approved.
Track status: https://github.com/claude-styles/registry/pull/42

8. The Interview Questions They’ll Ask

  1. “How would you design a registry for AI behavior templates?”
    • Discuss storage options (GitHub, custom server, distributed)
    • Explain metadata requirements for discovery
    • Address trust and security concerns
  2. “What metadata is needed for style discovery?”
    • Name, description, tags for search
    • Downloads, ratings for popularity
    • Version, author for provenance
    • Dependencies for complex styles
  3. “How do you handle versioning for behavior configurations?”
    • Semantic versioning principles
    • What constitutes breaking changes for styles
    • Upgrade paths and migration
  4. “What are the security considerations for user-contributed styles?”
    • Styles can contain instructions that change AI behavior
    • Review process before publishing
    • Sandboxing or limiting what styles can do
    • Provenance and author verification
  5. “How would you implement style validation?”
    • Schema validation for frontmatter
    • Content requirements (minimum length, headings)
    • Security checks (no sensitive data)
    • Linting for common issues

9. Hints in Layers

Hint 1: Reuse Skill Marketplace Patterns

The architecture from Project 14 (skill marketplace) applies here with modifications:

  • Registry index structure
  • CLI command patterns
  • Installation workflow

Hint 2: Validate Frontmatter with YAML Parser

Use a proper YAML parser, don’t regex:

# In Python
import yaml
with open(style_file) as f:
    content = f.read()
    # Split frontmatter from content
    if content.startswith('---'):
        _, frontmatter, body = content.split('---', 2)
        meta = yaml.safe_load(frontmatter)

Hint 3: Simple GitHub Registry

Start simple - a JSON file listing styles with GitHub raw URLs is enough:

REGISTRY_URL="https://raw.githubusercontent.com/claude-styles/registry/main/index.json"
curl -s "$REGISTRY_URL" | jq '.styles[] | select(.name == "tech-writer")'

Hint 4: Add Categories

Allow filtering by tags: documentation, review, learning, creative, code, etc.

10. Complete Implementation

10.1 CLI Tool Structure

Create the CLI at ~/.local/bin/claude-styles:

#!/usr/bin/env bash
#
# claude-styles - Output style package manager for Claude Code
#
# Usage:
#   claude-styles search <query>
#   claude-styles install <name>[@version]
#   claude-styles uninstall <name>
#   claude-styles list
#   claude-styles update [name]
#   claude-styles validate <file>
#   claude-styles publish <file>
#

set -euo pipefail

# Configuration
STYLES_DIR="${HOME}/.claude/output-styles"
REGISTRY_DIR="${STYLES_DIR}/.registry"
INSTALLED_FILE="${REGISTRY_DIR}/installed.json"
REGISTRY_URL="${CLAUDE_STYLES_REGISTRY:-https://raw.githubusercontent.com/claude-styles/registry/main/index.json}"

# Ensure directories exist
mkdir -p "${STYLES_DIR}" "${REGISTRY_DIR}"

# Initialize installed.json if it doesn't exist
if [[ ! -f "${INSTALLED_FILE}" ]]; then
    echo '{}' > "${INSTALLED_FILE}"
fi

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Logging functions
log_info() { echo -e "${BLUE}$1${NC}"; }
log_success() { echo -e "${GREEN}$1${NC}"; }
log_warn() { echo -e "${YELLOW}$1${NC}"; }
log_error() { echo -e "${RED}$1${NC}" >&2; }

# Fetch registry index
fetch_registry() {
    curl -sf "${REGISTRY_URL}" 2>/dev/null || {
        log_error "Failed to fetch registry from ${REGISTRY_URL}"
        exit 1
    }
}

# Command: search
cmd_search() {
    local query="${1:-}"

    if [[ -z "$query" ]]; then
        log_error "Usage: claude-styles search <query>"
        exit 1
    fi

    log_info "Searching for '${query}'..."
    echo

    local registry
    registry=$(fetch_registry)

    local results
    results=$(echo "$registry" | jq -r --arg q "$query" '
        .styles[] |
        select(
            (.name | test($q; "i")) or
            (.description | test($q; "i")) or
            (.tags[]? | test($q; "i"))
        ) |
        "📝 \(.name) (v\(.version))\n   \(.description)\n   ⭐ \(.rating // "N/A") | Downloads: \(.downloads // 0) | Tags: \(.tags // [] | join(", "))\n"
    ')

    if [[ -z "$results" ]]; then
        echo "No styles found matching '${query}'"
    else
        local count
        count=$(echo "$registry" | jq --arg q "$query" '
            [.styles[] | select(
                (.name | test($q; "i")) or
                (.description | test($q; "i")) or
                (.tags[]? | test($q; "i"))
            )] | length
        ')
        echo "Found ${count} output styles:"
        echo
        echo -e "$results"
    fi
}

# Command: install
cmd_install() {
    local spec="${1:-}"

    if [[ -z "$spec" ]]; then
        log_error "Usage: claude-styles install <name>[@version]"
        exit 1
    fi

    # Parse name@version
    local name version
    if [[ "$spec" == *@* ]]; then
        name="${spec%@*}"
        version="${spec#*@}"
    else
        name="$spec"
        version=""
    fi

    log_info "Installing ${name}${version:+@$version}..."

    local registry
    registry=$(fetch_registry)

    # Find the style
    local style_meta
    if [[ -n "$version" ]]; then
        style_meta=$(echo "$registry" | jq -r --arg n "$name" --arg v "$version" '
            .styles[] | select(.name == $n and .version == $v)
        ')
    else
        # Get latest version
        style_meta=$(echo "$registry" | jq -r --arg n "$name" '
            [.styles[] | select(.name == $n)] | sort_by(.version) | last
        ')
    fi

    if [[ -z "$style_meta" || "$style_meta" == "null" ]]; then
        log_error "Style '${name}${version:+@$version}' not found in registry"
        exit 1
    fi

    local found_version url
    found_version=$(echo "$style_meta" | jq -r '.version')
    url=$(echo "$style_meta" | jq -r '.url')

    local target_file="${STYLES_DIR}/${name}.md"

    # Check for existing installation
    if [[ -f "$target_file" ]]; then
        local installed_version
        installed_version=$(jq -r --arg n "$name" '.[$n].version // "unknown"' "$INSTALLED_FILE")

        if [[ "$installed_version" == "$found_version" ]]; then
            log_warn "${name}@${found_version} is already installed"
            exit 0
        else
            log_warn "Existing installation found: ${name}@${installed_version}"
            read -rp "Replace with ${found_version}? [Y/n] " confirm
            if [[ "${confirm:-Y}" != [Yy]* ]]; then
                echo "Installation cancelled"
                exit 0
            fi
            # Backup existing
            cp "$target_file" "${target_file}.${installed_version}.bak"
        fi
    fi

    # Download the style
    log_info "   Downloading from ${url}..."
    local content
    content=$(curl -sf "$url") || {
        log_error "Failed to download style"
        exit 1
    }

    # Validate
    if ! validate_content "$content" >/dev/null 2>&1; then
        log_error "Downloaded style failed validation"
        exit 1
    fi

    # Install
    echo "$content" > "$target_file"

    # Update installed.json
    local now
    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
    jq --arg n "$name" --arg v "$found_version" --arg t "$now" \
        '.[$n] = {"version": $v, "installed": $t, "source": "registry"}' \
        "$INSTALLED_FILE" > "${INSTALLED_FILE}.tmp"
    mv "${INSTALLED_FILE}.tmp" "$INSTALLED_FILE"

    echo
    log_success "✅ Installed ${name}@${found_version}"
    echo "   Use with: claude --output-style ${name}"
}

# Command: uninstall
cmd_uninstall() {
    local name="${1:-}"

    if [[ -z "$name" ]]; then
        log_error "Usage: claude-styles uninstall <name>"
        exit 1
    fi

    local target_file="${STYLES_DIR}/${name}.md"

    if [[ ! -f "$target_file" ]]; then
        log_error "Style '${name}' is not installed"
        exit 1
    fi

    read -rp "Remove ${name}? [Y/n] " confirm
    if [[ "${confirm:-Y}" != [Yy]* ]]; then
        echo "Uninstallation cancelled"
        exit 0
    fi

    rm "$target_file"

    # Update installed.json
    jq --arg n "$name" 'del(.[$n])' "$INSTALLED_FILE" > "${INSTALLED_FILE}.tmp"
    mv "${INSTALLED_FILE}.tmp" "$INSTALLED_FILE"

    log_success "✅ Uninstalled ${name}"
}

# Command: list
cmd_list() {
    log_info "Installed Output Styles:"
    echo

    local count=0

    for file in "${STYLES_DIR}"/*.md; do
        [[ -f "$file" ]] || continue

        local name
        name=$(basename "$file" .md)

        # Skip hidden files
        [[ "$name" == .* ]] && continue

        local version description
        version=$(jq -r --arg n "$name" '.[$n].version // "local"' "$INSTALLED_FILE")

        # Extract description from file
        description=$(grep -A1 '^description:' "$file" 2>/dev/null | head -1 | sed 's/^description: *//' || echo "No description")

        printf "  ├── %-15s %-8s %s\n" "$name" "$version" "$description"
        ((count++))
    done

    echo
    echo "${count} style(s) installed"
}

# Command: update
cmd_update() {
    local name="${1:-}"

    local registry
    registry=$(fetch_registry)

    if [[ -n "$name" ]]; then
        # Update specific style
        update_single "$name" "$registry"
    else
        # Update all
        log_info "Checking for updates..."
        echo

        for file in "${STYLES_DIR}"/*.md; do
            [[ -f "$file" ]] || continue
            local style_name
            style_name=$(basename "$file" .md)
            [[ "$style_name" == .* ]] && continue

            update_single "$style_name" "$registry" || true
        done
    fi
}

update_single() {
    local name="$1"
    local registry="$2"

    local installed_version
    installed_version=$(jq -r --arg n "$name" '.[$n].version // "unknown"' "$INSTALLED_FILE")

    if [[ "$installed_version" == "unknown" ]]; then
        log_warn "${name}: Local style, skipping"
        return 0
    fi

    local latest_version
    latest_version=$(echo "$registry" | jq -r --arg n "$name" '
        [.styles[] | select(.name == $n)] | sort_by(.version) | last | .version // "N/A"
    ')

    if [[ "$latest_version" == "N/A" ]]; then
        log_warn "${name}: Not found in registry"
        return 0
    fi

    if [[ "$installed_version" == "$latest_version" ]]; then
        echo "${name}: Up to date (${installed_version})"
        return 0
    fi

    log_info "${name}: ${installed_version} → ${latest_version} available"

    read -rp "Update? [Y/n] " confirm
    if [[ "${confirm:-Y}" != [Yy]* ]]; then
        return 0
    fi

    cmd_install "${name}@${latest_version}"
}

# Command: validate
cmd_validate() {
    local file="${1:-}"

    if [[ -z "$file" || ! -f "$file" ]]; then
        log_error "Usage: claude-styles validate <file>"
        exit 1
    fi

    log_info "Validating ${file}..."
    echo

    local content
    content=$(cat "$file")

    validate_content "$content"
}

# Validate content helper
validate_content() {
    local content="$1"
    local errors=0

    echo "Frontmatter:"

    # Check for frontmatter
    if [[ ! "$content" =~ ^---[[:space:]] ]]; then
        log_error "  ✗ Missing YAML frontmatter"
        ((errors++))
    else
        # Extract frontmatter
        local frontmatter
        frontmatter=$(echo "$content" | sed -n '/^---$/,/^---$/p' | sed '1d;$d')

        # Check name
        if echo "$frontmatter" | grep -q '^name:'; then
            local name_value
            name_value=$(echo "$frontmatter" | grep '^name:' | sed 's/^name: *//')
            if [[ "$name_value" =~ ^[a-z0-9-]+$ ]]; then
                log_success "  ├── name: ${name_value} ✓"
            else
                log_error "  ├── name: Invalid format (use lowercase, alphanumeric, hyphens)"
                ((errors++))
            fi
        else
            log_error "  ├── name: MISSING (required)"
            ((errors++))
        fi

        # Check version
        if echo "$frontmatter" | grep -q '^version:'; then
            local version_value
            version_value=$(echo "$frontmatter" | grep '^version:' | sed 's/^version: *//')
            if [[ "$version_value" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
                log_success "  ├── version: ${version_value} ✓"
            else
                log_error "  ├── version: Invalid semver format (use X.Y.Z)"
                ((errors++))
            fi
        else
            log_warn "  ├── version: Missing (required for registry)"
        fi

        # Check description
        if echo "$frontmatter" | grep -q '^description:'; then
            log_success "  ├── description: present ✓"
        else
            log_warn "  ├── description: Missing (recommended)"
        fi

        # Check keep-coding-instructions
        if echo "$frontmatter" | grep -q '^keep-coding-instructions:'; then
            local kci_value
            kci_value=$(echo "$frontmatter" | grep '^keep-coding-instructions:' | sed 's/^keep-coding-instructions: *//')
            if [[ "$kci_value" =~ ^(true|false)$ ]]; then
                log_success "  └── keep-coding-instructions: ${kci_value} ✓"
            else
                log_error "  └── keep-coding-instructions: Invalid (use true or false)"
                ((errors++))
            fi
        else
            log_success "  └── keep-coding-instructions: not set (defaults to true) ✓"
        fi
    fi

    echo
    echo "Content:"

    # Extract body (after second ---)
    local body
    body=$(echo "$content" | sed -n '/^---$/,/^---$/d;p')

    # Check line count
    local line_count
    line_count=$(echo "$body" | grep -c '[^[:space:]]' || echo "0")
    if [[ $line_count -ge 10 ]]; then
        log_success "  ├── Line count: ${line_count} (minimum 10) ✓"
    else
        log_error "  ├── Line count: ${line_count} (minimum 10 required)"
        ((errors++))
    fi

    # Check for headings
    if echo "$body" | grep -q '^#'; then
        log_success "  ├── Has headings: yes ✓"
    else
        log_error "  ├── Has headings: no (at least one required)"
        ((errors++))
    fi

    # Check for placeholder text
    if echo "$body" | grep -iqE '(TODO|XXX|FIXME|placeholder)'; then
        log_warn "  └── Contains placeholder text"
    else
        log_success "  └── No placeholder text: yes ✓"
    fi

    echo

    if [[ $errors -gt 0 ]]; then
        log_error "✗ Validation failed with ${errors} error(s)"
        return 1
    else
        log_success "✅ Valid output style! Ready for use or publication."
        return 0
    fi
}

# Command: publish (placeholder)
cmd_publish() {
    local file="${1:-}"

    if [[ -z "$file" || ! -f "$file" ]]; then
        log_error "Usage: claude-styles publish <file>"
        exit 1
    fi

    log_info "Publishing style..."

    # Validate first
    if ! cmd_validate "$file"; then
        log_error "Style must pass validation before publishing"
        exit 1
    fi

    echo
    log_info "To publish your style:"
    echo "1. Fork https://github.com/claude-styles/registry"
    echo "2. Add your style to the styles/ directory"
    echo "3. Update index.json with your style metadata"
    echo "4. Submit a pull request"
    echo
    echo "Contribution guide: https://github.com/claude-styles/registry#contributing"
}

# Main dispatcher
main() {
    local cmd="${1:-help}"
    shift || true

    case "$cmd" in
        search)     cmd_search "$@" ;;
        install)    cmd_install "$@" ;;
        uninstall)  cmd_uninstall "$@" ;;
        list)       cmd_list "$@" ;;
        update)     cmd_update "$@" ;;
        validate)   cmd_validate "$@" ;;
        publish)    cmd_publish "$@" ;;
        help|--help|-h)
            echo "claude-styles - Output style package manager for Claude Code"
            echo
            echo "Usage:"
            echo "  claude-styles search <query>        Search for styles"
            echo "  claude-styles install <name>        Install a style"
            echo "  claude-styles uninstall <name>      Remove a style"
            echo "  claude-styles list                  Show installed styles"
            echo "  claude-styles update [name]         Update style(s)"
            echo "  claude-styles validate <file>       Validate a style file"
            echo "  claude-styles publish <file>        Publish to registry"
            echo
            echo "Examples:"
            echo "  claude-styles search documentation"
            echo "  claude-styles install tech-writer"
            echo "  claude-styles install tech-writer@2.1.0"
            echo "  claude-styles list"
            ;;
        *)
            log_error "Unknown command: $cmd"
            echo "Run 'claude-styles help' for usage"
            exit 1
            ;;
    esac
}

main "$@"

10.2 Sample Registry Index

Create a sample index.json for testing:

{
  "styles": [
    {
      "name": "tech-writer",
      "version": "2.1.0",
      "description": "Technical documentation with formal tone",
      "author": "@expert_writer",
      "url": "https://raw.githubusercontent.com/claude-styles/registry/main/styles/tech-writer/2.1.0.md",
      "downloads": 1234,
      "rating": 4.8,
      "tags": ["documentation", "technical", "formal"],
      "created": "2024-06-01T00:00:00Z",
      "updated": "2025-01-15T10:30:00Z"
    },
    {
      "name": "code-review",
      "version": "1.5.0",
      "description": "Systematic code review assistant",
      "author": "@review_pro",
      "url": "https://raw.githubusercontent.com/claude-styles/registry/main/styles/code-review/1.5.0.md",
      "downloads": 892,
      "rating": 4.6,
      "tags": ["review", "code", "quality"],
      "created": "2024-08-15T00:00:00Z",
      "updated": "2025-01-10T14:00:00Z"
    },
    {
      "name": "learning",
      "version": "1.0.0",
      "description": "Educational explanations with analogies",
      "author": "@teacher_ai",
      "url": "https://raw.githubusercontent.com/claude-styles/registry/main/styles/learning/1.0.0.md",
      "downloads": 567,
      "rating": 4.5,
      "tags": ["learning", "education", "beginner"],
      "created": "2024-09-01T00:00:00Z",
      "updated": "2024-12-01T09:00:00Z"
    }
  ],
  "updated": "2025-01-15T10:30:00Z"
}

10.3 Installation Script

Create an installation script:

#!/usr/bin/env bash
#
# Install claude-styles CLI
#

set -euo pipefail

INSTALL_DIR="${HOME}/.local/bin"
SCRIPT_URL="https://raw.githubusercontent.com/claude-styles/cli/main/claude-styles"

echo "Installing claude-styles..."

# Create install directory
mkdir -p "$INSTALL_DIR"

# Download script
curl -sf "$SCRIPT_URL" -o "${INSTALL_DIR}/claude-styles"
chmod +x "${INSTALL_DIR}/claude-styles"

# Check if in PATH
if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
    echo
    echo "Add this to your shell profile:"
    echo "  export PATH=\"\$HOME/.local/bin:\$PATH\""
fi

echo
echo "✅ Installed claude-styles to ${INSTALL_DIR}/claude-styles"
echo
echo "Run 'claude-styles help' to get started"

11. Books That Will Help

Topic Book Chapter/Section
Package management “Software Engineering at Google” by Winters et al. Ch. 21: Dependency Management
Open source patterns “Producing Open Source Software” by Karl Fogel Ch. 5: Technical Infrastructure
Registry design npm documentation Architecture section
CLI design “The Art of Unix Programming” by Eric Raymond Ch. 10: Command-Line Interface
Bash scripting “The Linux Command Line” by William Shotts Part 4: Shell Scripts

12. Common Pitfalls and Solutions

Pitfall Symptom Solution
No validation Broken styles get installed Always validate before install
Version conflicts Old version overwrites new Track installed versions in metadata
Network dependency Offline use fails Cache registry index locally
No backup Overwritten styles lost Backup before replacing
Path issues Script not found Ensure ~/.local/bin is in PATH
jq not installed Script fails Check dependencies at start

13. Self-Assessment Checklist

Understanding Verification

  • I can explain how package managers work (registry, metadata, installation)
  • I understand semantic versioning and when to bump major/minor/patch
  • I can describe what makes a valid output style
  • I understand the difference between user and project scope installation
  • I can explain the security considerations for user-contributed styles

Implementation Verification

  • Search command finds styles by name, description, and tags
  • Install command downloads and validates styles
  • Uninstall command removes styles and updates tracking
  • List command shows installed styles with versions
  • Update command checks for and applies updates
  • Validate command checks frontmatter and content

Integration Verification

  • CLI is installed and accessible from terminal
  • Installed styles work with claude --output-style
  • Version tracking persists across sessions
  • Error messages are helpful and actionable

14. Extensions and Challenges

14.1 Beginner Extensions

  • Add claude-styles info <name> to show detailed style info
  • Add download count tracking for local installs
  • Create colorized output for better readability

14.2 Intermediate Extensions

  • Implement local caching of registry index
  • Add --dry-run flag to preview actions
  • Support multiple registries (like npm scopes)
  • Add claude-styles init to create new style template

14.3 Advanced Extensions

  • Build a web UI for browsing styles
  • Implement style dependencies (A requires B)
  • Add cryptographic signatures for style verification
  • Create GitHub Action for style publishing

15. Completion Criteria

Minimum Viable Completion

  • CLI with search, install, list commands
  • Basic validation of frontmatter
  • Local tracking of installed styles
  • Works with mock registry data

Full Completion

  • All commands implemented (search, install, uninstall, list, update, validate, publish)
  • Full validation of frontmatter and content
  • Version management with updates
  • Conflict detection and backup
  • Helpful error messages

Excellence (Going Above and Beyond)

  • Actual GitHub registry set up
  • Multiple registries support
  • Web UI for browsing
  • Automated publishing workflow
  • Comprehensive test suite
  • Documentation for contributors

This guide was expanded from CLAUDE_CODE_MASTERY_40_PROJECTS.md. For the complete learning path, see the README.