Skill Documentarian

You are the skill-documentarian, guardian of the Claude Skills showcase website. You ensure every skill in .claude/skills/ has matching documentation, accurate metadata, proper tags, and that greatness is captured in artifacts.

Core Mission

1. Source of Truth: .claude/skills/ defines what exists. Website reflects it. 2. README Maintainer: Keep README.md accurate with skill counts, categories, and install instructions. 3. Tag Taxonomy Owner: Assign and maintain skill tags for discoverability. 4. Badge Manager: Track NEW/UPDATED badges with proper lifecycle. 5. Artifact Creator: Capture multi-skill collaborations in blog-style docs. 6. Validation Enforcer: Run scripts that catch drift and mismatches. 7. Subpage Sync Guardian: Ensure skill reference docs are exposed as browsable subpages. 8. Category Enforcer: Ensure every skill has a valid category for browse page filtering.

Quick Reference: Key Files

Automated Sync (Pre-commit Hooks)

The pre-commit hook automatically:

• Validates README.md skill counts match actual skill count
• Syncs SKILL.md frontmatter → doc file SkillHeader
• Regenerates skillMetadata.json with git dates
• Regenerates OG image with updated skill count (pixel art + Press Start 2P font)
• Validates angle brackets in markdown
• Auto-adds changed files to commit

Manual batch sync: cd website && npm run sync:skills Manual README sync: cd website && npm run sync:readme Manual subpage sync: cd website && npm run sync:subpages Manual OG image: cd website && bash scripts/generate-og-image.sh

OG Image Maintenance (Social Preview)

The OG image (og-image.png) is the social media preview shown when sharing the site on Twitter, LinkedIn, Facebook, etc.

How It Works

1. Background: Pixel art generated by Ideogram (Windows 3.1 + vaporwave aesthetic) 2. Text overlay: ImageMagick composites text using Press Start 2P font 3. Dynamic count: Reads skill count from skillMetadata.json 4. Auto-update: Pre-commit hook regenerates when skills change

Dependencies

• ImageMagick: brew install imagemagick
• Press Start 2P font: Install from Google Fonts to ~/Library/Fonts/
• Node.js: For reading skill count from JSON

Regenerating Background

If the background needs updating (style refresh, etc.):

# Use Ideogram to generate new background
mcp__ideogram__generate_image with prompt:
"Pixel art retro computer workspace with filing cabinets,
floppy disks, synthwave sunset gradient sky, Windows 3.1 aesthetic,
16-bit graphics, vaporwave colors, no text"

# Save to: website/static/img/og-background_TIMESTAMP.png
# Update BG_IMAGE path in scripts/generate-og-image.sh

Manual Generation

cd website
bash scripts/generate-og-image.sh
# Output: static/img/og-image.png

Subpage Sync (Ancillary Documentation)

Skills with references/, templates/, examples/, or guides/ folders get their markdown files exposed as browsable subpages in the documentation.

How It Works

1. Detection: Script scans .claude/skills/*/ for supported subfolders 2. Conversion: Flat skill_name.md becomes folder skill_name/index.md 3. Sync: Markdown files from source subfolders are copied to doc subfolders 4. Frontmatter: Auto-generated if missing (title, sidebar_label, sidebar_position) 5. Safety: Angle brackets escaped to prevent MDX compilation errors

Folder Structure

.claude/skills/hr-network-analyst/          website/docs/skills/hr_network_analyst/
├── SKILL.md                          →     ├── index.md (main skill page)
├── references/                             ├── references/
│   ├── data-sources.md               →     │   ├── _category_.json
│   └── graph-metrics.md              →     │   ├── data-sources.md
└── guides/                                 │   └── graph-metrics.md
    └── quickstart.md                 →     └── guides/
                                                ├── _category_.json
                                                └── quickstart.md

Run Subpage Sync

# During prebuild (automatic)
npm run prebuild  # Includes subpage sync

# Manual sync
npm run sync:subpages

# Or directly
npx tsx scripts/syncSkillSubpages.ts

Docusaurus Doc IDs

Folder-based docs have IDs like skills/skill_name/skill_name (not /index). When updating sidebars.ts, use the skill folder name twice:

// ✅ Correct
'skills/hr_network_analyst/hr_network_analyst'

// ❌ Wrong
'skills/hr_network_analyst/index'

Adding a New Skill to Website

# 1. Create doc file
touch website/docs/skills/skill_name.md  # Note: underscores!

# 2. Add to ALL_SKILLS array in skills.ts
{
  id: 'skill-name',
  title: 'Skill Title',
  category: 'Category Name',
  path: '/docs/skills/skill_name',
  description: 'Brief description',
  tags: ['tag1', 'tag2', 'tag3'],
  badge: 'NEW'  // Optional
}

# 3. Generate hero image
mcp__ideogram__generate_image  # Windows 3.1 + vaporwave aesthetic

# 4. Verify sync
echo "Skills: $(ls -d .claude/skills/*/ | wc -l)"
echo "In skills.ts: $(grep "{ id:" website/src/data/skills.ts | wc -l)"

Tag Management

3-5 tags per skill from these types:

• Skill Type (purple): research, analysis, creation, coaching, validation, automation, orchestration
• Domain (blue): design, code, ml, cv, audio, 3d, robotics, photography, finance, health, devops...
• Complexity (orange): beginner-friendly, advanced, production-ready
• Integration (pink): mcp, elevenlabs, accessibility

Full taxonomy: See references/tag-taxonomy.md

Badge Management

Full details: See references/badge-metadata-management.md

Artifact Creation

Create artifacts when:

• Multi-skill collaboration produces something cool
• New pattern emerges (first time X + Y work together)
• Interactive feature demonstrates capabilities

Structure: See references/artifact-structure.md Preservation guide: See guides/ARTIFACT_PRESERVATION.md

README Maintenance

The main README.md must stay in sync with actual skill inventory. Key sections:

1. Skill count in header: "46+ production-ready skills" 2. Category tables with accurate skill lists 3. MCP server configs with correct JSON 4. Install instructions for marketplace, manual, and download options

Validation check:

# Count actual skills vs README claim
ACTUAL=$(ls -d .claude/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
echo "Actual skills: $ACTUAL"

# Check if README needs update (look for skill count pattern)
grep -E '\d+\+ production-ready skills' README.md

When README needs updating:

• New skill added to .claude/skills/
• Skill renamed or removed
• Category reorganization
• MCP server changes
• Install method changes

Frontmatter Validation (CRITICAL)

When skills are uploaded to Claude's skill marketplace, only these frontmatter keys are allowed:

• name - Required, lowercase-hyphenated
• description - Required, includes activation keywords and NOT clause
• license - Optional (e.g., "MIT")
• allowed-tools - Comma-separated tool names
• metadata - Optional object for custom key-value pairs

Invalid keys will cause upload failure:

❌ integrates_with, triggers, tools, outputs, coordinates_with, python_dependencies
❌ Any custom YAML keys in frontmatter

Move custom info to the skill body instead:

## Integrations
Works with: orchestrator, team-builder, swift-executor

## Triggers
Activates on: "document", "sync skills", "create artifact"

Validation command:

# Find skills with invalid frontmatter keys
for skill in .claude/skills/*/SKILL.md; do
  invalid=$(sed -n '/^---$/,/^---$/p' "$skill" | grep -E "^[a-zA-Z_-]+:" | cut -d: -f1 | grep -vE "^(name|description|license|allowed-tools|metadata)$")
  if [ -n "$invalid" ]; then
    echo "=== $(dirname "$skill" | xargs basename) ==="
    echo "$invalid"
  fi
done

Category Validation (CRITICAL)

Skills must have a valid category for the browse page to be useful. Invalid or missing categories make skills invisible to users filtering by category.

Valid Categories

Category Validation Command

# Check all skills have valid categories
VALID_CATS="AI & Machine Learning|Code Quality & Testing|Content & Writing|Data & Analytics|Design & Creative|DevOps & Site Reliability|Business & Monetization|Research & Analysis|Productivity & Meta|Lifestyle & Personal"

for skill in .claude/skills/*/SKILL.md; do
  cat=$(grep -m1 "^category:" "$skill" | sed 's/category: *//')
  if [ -z "$cat" ]; then
    echo "❌ MISSING category: $(dirname "$skill" | xargs basename)"
  elif ! echo "$cat" | grep -qE "^($VALID_CATS)$"; then
    echo "❌ INVALID category '$cat': $(dirname "$skill" | xargs basename)"
  fi
done && echo "✅ All categories valid"

When to Validate Categories

• Before accepting skill submissions (automated workflow checks this)
• After running `npm run skills:generate` (regenerates skills.ts)
• When browse page filtering seems broken

Fixing Invalid Categories

1. Edit the skill's SKILL.md frontmatter 2. Change category: to one of the 10 valid values above 3. Run cd website && npm run skills:generate to regenerate skills.ts 4. Verify on browse page at /skills

Validation Commands

# Find skills missing from skills.ts
for skill in .claude/skills/*/; do
  name=$(basename "$skill")
  grep -q "id: '$name'" website/src/data/skills.ts || echo "Missing: $name"
done

# Find skills without hero images
for skill in .claude/skills/*/; do
  name=$(basename "$skill")
  [ -f "website/static/img/skills/$name-hero.png" ] || echo "No hero: $name"
done

# Count badge usage
echo "NEW: $(grep "badge: 'NEW'" website/src/data/skills.ts | wc -l)"
echo "UPDATED: $(grep "badge: 'UPDATED'" website/src/data/skills.ts | wc -l)"

# Validate README skill count
ACTUAL=$(ls -d .claude/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
README_COUNT=$(grep -oE '\d+\+? production-ready skills' README.md | grep -oE '\d+' | head -1)
[ "$ACTUAL" -gt "$README_COUNT" ] && echo "⚠️  README outdated: $ACTUAL skills exist, README says $README_COUNT"

# Find skills with subfolders not yet synced
for skill in .claude/skills/*/; do
  name=$(basename "$skill")
  docname="${name//-/_}"
  for sub in references templates examples guides; do
    if [ -d "$skill$sub" ]; then
      [ -d "website/docs/skills/$docname/$sub" ] || echo "Missing subpages: $name/$sub"
    fi
  done
done

When to Use This Skill

Use for:

• Keeping README.md accurate (skill counts, categories, install instructions)
• Assigning and updating skill tags
• Validating skill categories (ensure browse page filtering works)
• Creating artifact documentation
• Validating skill-to-website sync
• Generating hero images
• Maintaining OG image (social preview with dynamic skill count)
• Writing changelogs and API docs
• Managing NEW/UPDATED badges
• Syncing skill subpages (references, guides, templates, examples)

Do NOT use for:

• Writing code (use domain-specific skills)
• Creating designs (use web-design-expert)
• Testing (use test-automator)
• Project planning (use orchestrator, team-builder)

Anti-Patterns

Anti-Pattern: Code Comments as Documentation

What it looks like: "The code is self-documenting" Why it's wrong: Code shows HOW, not WHY. Comments for implementers, docs for users. Instead: Separate code comments from user documentation.

Anti-Pattern: Stale Documentation

What it looks like: Docs describe features that no longer exist Why it's wrong: Erodes trust, wastes user time Instead: Version docs with code, add timestamps, run CI checks.

Anti-Pattern: Wall of Text

What it looks like: Dense paragraphs with no structure Why it's wrong: Intimidating, unscannable Instead: Headers, lists, code examples, diagrams.

Anti-Pattern: Assuming Context

What it looks like: "Just run the script and it works" Why it's wrong: Assumes reader knows which script, where, what args Instead: Exact commands, full paths, expected output.

Reference Files

• references/tag-taxonomy.md - Complete tag type reference
• references/documentation-templates.md - README, tutorial, API templates
• references/badge-metadata-management.md - Badge lifecycle and metadata
• references/artifact-structure.md - Artifact JSON schema and workflow
• guides/ARTIFACT_PRESERVATION.md - Complete preservation guide
• guides/ARTIFACT_QUICKREF.md - Quick checklist

Documentation Quality Rules

5-Minute Rule: Can someone unfamiliar understand basics in 5 minutes? 6-Month Rule: Will YOU understand this in 6 months without context?

---

Remember: Documentation is a love letter to your future self and your users. Write it with care, maintain it with discipline, and it will compound value over time.

Changelog

[2.0.0] - 2024-01-XX

Changed

• BREAKING: Restructured from monolithic 1124-line file to progressive disclosure architecture
• Fixed frontmatter format: tools: → allowed-tools: (comma-separated)
• Added NOT clause to description for precise activation boundaries
• Reduced SKILL.md from 1124 lines to 182 lines (84% reduction)

Added

• references/automation-scripts.md - Git hooks, sync scripts, validation
• references/documentation-templates.md - MDX templates, frontmatter specs
• references/workflow-integration.md - Orchestrator patterns, CI/CD integration
• Anti-patterns section with "What it looks like / Why wrong / Instead" format
• Clear integration points with skill-coach and orchestrator

Removed

• Inline code examples (moved to references)
• Verbose workflow descriptions (condensed to quick reference)
• Redundant documentation patterns

Migration Guide

Reference files are now in /references/ directory. Import patterns:

• Automation scripts → references/automation-scripts.md
• MDX templates → references/documentation-templates.md
• Workflow patterns → references/workflow-integration.md

Artifact Preservation Guide

Welcome! This guide will help you preserve and share examples of Claude Skills in action.

What is an Artifact?

An artifact is a preserved demonstration of Claude Skills working on real tasks. It captures:

• The before state (initial code, design, or content)
• The after state (improved result)
• The process (how skills were used)
• Learnings (insights gained)

Types of Artifacts

1. Single-Skill Artifacts

Demonstrates one skill working independently.

Example: skill-coach improving itself through iterations

Structure:

/single-skill/{skill-name}/{number-name}/
  ├── artifact.json          # Metadata
  ├── README.md              # Overview
  ├── transcript.md          # Conversation log (optional)
  ├── before/                # Initial state
  │   ├── {file1}.md
  │   └── {file2}.md
  ├── after/                 # Final state
  │   ├── {file1}.md
  │   └── {file2}.md
  └── assets/                # Screenshots, diagrams
      ├── {image1}.png
      └── {diagram}.svg

2. Multi-Skill Artifacts (Orchestration)

Shows multiple skills working together.

Example: vibe-matcher → web-design-expert → frontend-developer pipeline

Structure:

/multi-skill/{project-name}/{number-name}/
  ├── artifact.json          # Metadata with phases
  ├── README.md              # Orchestration overview
  ├── transcript.md          # Full conversation
  ├── phase-1-{skill}/       # Each phase separate
  │   ├── before/
  │   └── after/
  ├── phase-2-{skill}/
  │   ├── before/
  │   └── after/
  └── assets/

3. Front-End Component Artifacts (Before/After UI)

Special structure for visual component improvements with interactive previews.

Example: Winamp player audio engineering improvements

Structure:

/frontend/{component-name}/{number-name}/
  ├── artifact.json
  ├── README.md
  ├── before/
  │   ├── components/        # React components
  │   │   ├── WinampModal.tsx
  │   │   └── MusicPlayerContext.tsx
  │   ├── data/              # Data files
  │   │   └── musicMetadata.ts
  │   ├── assets/            # Images, styles
  │   │   └── screenshot.png
  │   └── demo.html          # Standalone preview (optional)
  ├── after/
  │   ├── components/
  │   ├── data/
  │   ├── assets/
  │   └── demo.html
  └── comparison/            # Side-by-side assets
      ├── feature-comparison.md
      └── visual-comparison.png

---

Creating an Artifact: Step by Step

Step 1: Choose Your Artifact Type

Ask yourself:

• One skill or many? → Single vs Multi
• Code, design, or research? → Determines category
• Visual component? → Consider frontend type for live previews

Step 2: Set Up the Folder Structure

# Navigate to artifacts directory
cd website/src/data/artifacts

# Create your artifact folder
mkdir -p {type}/{skill-or-project}/{number-name}

# Example:
mkdir -p single-skill/sound-engineer/001-winamp-fft
mkdir -p multi-skill/portfolio-redesign/001-vibe-to-pixels
mkdir -p frontend/winamp-player/001-audio-engineering

Step 3: Capture the "Before" State

Critical: Preserve the initial state EXACTLY as it was before improvements.

For code artifacts:

# Copy current files to before/ folder
cp path/to/Component.tsx before/components/
cp path/to/data.ts before/data/
cp path/to/styles.css before/assets/

For design artifacts:

• Export Figma frames as PNG/SVG
• Screenshot current live site
• Save HTML/CSS snapshots

For research artifacts:

• Save initial prompt and context
• Preserve any existing research notes
• Capture data sources

Pro Tip: Add a before/NOTE.md explaining what exists and what problems need solving.

Step 4: Do the Work with Skills

Now use Claude Skills to improve your artifact. Document:

• Which skills you invoke
• What you ask them to do
• Key decisions made
• Iterations and refinements

Save your transcript:

# Copy conversation to transcript.md
# (Optional but highly recommended)

Step 5: Capture the "After" State

After improvements are complete:

# Copy improved files to after/ folder
cp path/to/Component.tsx after/components/
cp path/to/data.ts after/data/
cp path/to/styles.css after/assets/

Step 6: Create artifact.json

This is the most important file. It defines your artifact's metadata.

Template:

{
  "id": "{type}-{skill}-{number}-{slug}",
  "title": "Descriptive Title: What Was Achieved",
  "description": "2-3 sentence summary. What was the goal? Which skills were used? What was the outcome?",
  "type": "single-skill | multi-skill | comparison",
  "skills": [
    {
      "name": "skill_name",
      "role": "What this skill did in the project"
    }
  ],
  "category": "design | development | ai-ml | research | writing | meta",
  "tags": ["tag1", "tag2", "tag3"],
  "difficulty": "beginner | intermediate | advanced",

  "phases": [
    {
      "name": "Phase 1: Foundation",
      "skills": ["skill_name"],
      "duration": "1 iteration",
      "outcome": "What was accomplished"
    }
  ],

  "outcome": {
    "summary": "Overall result achieved",
    "metrics": [
      { "label": "Metric Name", "value": "123" }
    ],
    "learned": [
      "Key insight 1",
      "Key insight 2"
    ]
  },

  "files": {
    "transcript": "transcript.md",
    "before": ["before/file1.md", "before/file2.tsx"],
    "after": ["after/file1.md", "after/file2.tsx"],
    "assets": ["assets/screenshot.png"]
  },

  "createdAt": "2024-11-24T23:00:00Z",
  "featured": false,
  "viewCount": 0
}

Field Guide:

• id: Unique identifier (lowercase, dash-separated)
• title: Should be compelling and descriptive
• type: single-skill, multi-skill, or comparison
• skills: List ALL skills used with their specific roles
• category: Choose one that fits best
• tags: 5-10 relevant keywords
• difficulty: Honest assessment of complexity
• phases: For multi-step work, break into phases
• metrics: Quantifiable outcomes (LOC, time, iterations, etc.)
• learned: Key insights for others to learn from
• featured: Set to true for exceptional artifacts (curated by maintainers)

Step 7: Write README.md

The README is your artifact's landing page. Structure:

# {Artifact Title}

## Overview
Brief summary of what this artifact demonstrates.

## Context
Why was this work done? What problem needed solving?

## Skills Used
- **skill_name**: What role it played

## Process
High-level steps taken:
1. First phase
2. Second phase
3. Final phase

## Key Decisions
- **Decision 1**: Why it was made
- **Decision 2**: Alternative considered

## Results
Quantifiable outcomes and qualitative improvements.

### Metrics
- Before: X
- After: Y
- Improvement: Z%

## Learnings
What insights emerged from this work?

## Files
- `before/`: Initial state
- `after/`: Improved state
- `transcript.md`: Full conversation (optional)

Step 8: Add Visual Assets

Great artifacts have visual elements:

Screenshots:

# Before/after screenshots
before/assets/ui-before.png
after/assets/ui-after.png
comparison/side-by-side.png

Diagrams:

• Architecture diagrams
• Flow charts
• Decision trees
• Process visualizations

Videos (for complex UI):

• Screen recordings of before/after
• Interaction demonstrations

Step 9: Test the Preview

Front-end artifacts should include standalone previews:

<!-- demo.html template -->
<!DOCTYPE html>
<html>
<head>
  <title>{Component Name} - Before/After Demo</title>
  <style>
    /* Inline all critical CSS */
  </style>
</head>
<body>
  <div id="demo">
    <!-- Embedded component preview -->
  </div>
  <script>
    // Embedded JavaScript for interactivity
  </script>
</body>
</html>

Step 10: Submit for Review

1. Test locally:

   npm run start
   # Navigate to /artifacts
   # Verify your artifact appears and renders correctly

2. Commit your artifact:

   git add website/src/data/artifacts/{type}/{name}
   git commit -m "Add artifact: {title}"

3. Submit pull request:

• Title: Add artifact: {title}
• Description: Link to artifact preview, brief summary
• Reviewers will check: structure, quality, learnings

---

Front-End Component Artifacts (Special Guide)

Front-end before/after artifacts require special attention to preserve full functionality.

What to Preserve

Components:

• All React/Vue/Svelte component files
• TypeScript/JavaScript source
• Component tests

Data:

• Mock data used by components
• API response fixtures
• Configuration files

Styles:

• CSS/SCSS files
• CSS modules
• Styled components

Assets:

• Images, icons, fonts
• SVG graphics
• Audio/video files (if small)

Context:

• React Context providers
• State management (Redux, Zustand)
• Custom hooks

Creating Interactive Previews

For complex components, create standalone HTML previews:

Steps: 1. Bundle component with all dependencies 2. Inline critical CSS 3. Embed assets as data URLs (for small files) 4. Create self-contained HTML file 5. Test in isolation

Example: Winamp Player Demo

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Winamp Player - Audio Engineering Improvements</title>
  <style>
    /* Inline all component CSS */
    .winamp-modal { /* styles */ }
    .visualizer { /* styles */ }
  </style>
</head>
<body>
  <h1>Before: Fake CSS Animations</h1>
  <div id="before-demo">
    <!-- Before component -->
  </div>

  <h1>After: Real FFT Analysis</h1>
  <div id="after-demo">
    <!-- After component -->
  </div>

  <script>
    // Embed JavaScript
    // Include Web Audio API setup
    // Demonstrate real-time FFT
  </script>
</body>
</html>

Performance Considerations

Front-end artifacts can be large. Guidelines:

File Size Limits:

• Component code: No limit (it's source code)
• Images: < 500KB each (compress with ImageOptim)
• Audio/MIDI: < 1MB each
• Videos: Link to external (YouTube, Vimeo)
• Total artifact: Aim for < 10MB

Optimization:

• Compress screenshots (PNG → WebP if possible)
• Use SVG for diagrams (smaller than PNG)
• Host large videos externally
• Reference CDN dependencies instead of bundling

Rendering Strategy

The artifacts page can display front-end components:

Option 1: Screenshot + Link

• Show before/after screenshots
• Link to live demo (deployed separately)
• Best for: Complex, large components

Option 2: Embedded Iframe

• Embed demo.html in iframe
• Users interact directly on artifacts page
• Best for: Simple, self-contained components

Option 3: Code Sandbox

• Link to CodeSandbox/StackBlitz
• Full editing + preview experience
• Best for: Educational artifacts

---

Winamp Player Artifact Example

Here's how to structure the upcoming Winamp audio improvements:

/frontend/winamp-player/001-audio-engineering/
├── artifact.json
├── README.md
├── transcript.md
│
├── before/
│   ├── components/
│   │   ├── WinampModal.tsx          # Current modal with fake visualizer
│   │   ├── MinifiedMusicPlayer.tsx  # Navbar widget
│   │   └── MusicPlayerContext.tsx   # Current audio context (broken volume)
│   ├── hooks/
│   │   └── useWinampSkin.ts
│   ├── data/
│   │   └── musicMetadata.ts
│   ├── styles/
│   │   └── WinampModal.module.css
│   ├── assets/
│   │   ├── screenshot-full.png      # Full modal screenshot
│   │   ├── screenshot-visualizer.png # Fake CSS animation bars
│   │   └── screenshot-volume.png    # Broken volume control
│   └── NOTE.md                       # What's broken and why
│
├── after/
│   ├── components/
│   │   ├── WinampModal.tsx          # Real FFT visualizer
│   │   ├── MinifiedMusicPlayer.tsx  # Real-time bars
│   │   └── MusicPlayerContext.tsx   # Proper GainNode volume
│   ├── hooks/
│   │   ├── useFFTData.ts            # NEW: FFT analysis hook
│   │   ├── useVUMeter.ts            # NEW: VU meter hook
│   │   └── useWinampSkin.ts
│   ├── components/
│   │   ├── EQControls.tsx           # NEW: 3-band EQ
│   │   └── VUMeter.tsx              # NEW: Professional VU meter
│   ├── data/
│   │   └── musicMetadata.ts
│   ├── styles/
│   │   └── WinampModal.module.css   # Updated for real FFT
│   ├── assets/
│   │   ├── screenshot-full.png
│   │   ├── screenshot-visualizer.png  # Real FFT in action
│   │   ├── screenshot-volume.png      # Working volume
│   │   ├── screenshot-eq.png          # 3-band EQ
│   │   └── screenshot-vu-meter.png    # VU meter
│   └── NOTE.md                        # What improved and how
│
├── comparison/
│   ├── feature-comparison.md          # Side-by-side feature list
│   ├── visual-comparison.png          # Before/after split screen
│   └── architecture-diagram.svg       # Audio routing: before vs after
│
└── demos/
    ├── before-demo.html               # Standalone before preview
    └── after-demo.html                # Standalone after preview

artifact.json for Winamp:

{
  "id": "frontend-winamp-player-001-audio-engineering",
  "title": "Winamp Player: From Fake CSS to Professional Audio Engineering",
  "description": "Complete audio engineering upgrade of Winamp music player. Replaced fake CSS animations with real FFT visualizer, fixed broken volume control with proper GainNode, and added professional features: 3-band EQ, dynamic compression, and VU meters. Demonstrates sound-engineer skill applying Web Audio API best practices.",
  "type": "single-skill",
  "skills": [
    {
      "name": "sound-engineer",
      "role": "Designed and implemented professional audio architecture using Web Audio API: GainNode for volume, AnalyserNode for real-time FFT visualization, BiquadFilterNodes for 3-band EQ, and DynamicsCompressorNode for mastering."
    }
  ],
  "category": "development",
  "tags": [
    "web-audio-api",
    "react",
    "typescript",
    "fft-visualization",
    "audio-engineering",
    "music-player",
    "real-time-processing",
    "ui-components"
  ],
  "difficulty": "advanced",
  "phases": [
    {
      "name": "Phase 1: Core Audio Routing",
      "skills": ["sound-engineer"],
      "duration": "3 tasks",
      "outcome": "Implemented GainNode for volume control with logarithmic scaling, connected proper audio chain: Source → GainNode → AnalyserNode → Destination"
    },
    {
      "name": "Phase 2: Real-Time FFT Visualizer",
      "skills": ["sound-engineer"],
      "duration": "3 tasks",
      "outcome": "Replaced fake CSS animations with real FFT analysis. Created useFFTData hook, updated WinampModal and MinifiedPlayer with 60fps real-time frequency visualization"
    },
    {
      "name": "Phase 3: Professional Audio Features",
      "skills": ["sound-engineer"],
      "duration": "4 tasks",
      "outcome": "Added 3-band EQ (bass/mid/treble), dynamic range compression to prevent clipping, and professional VU meters with peak detection"
    }
  ],
  "outcome": {
    "summary": "Transformed Winamp player from non-functional UI mockup to professional-grade audio application. Volume control now works correctly, visualizer responds to actual music frequencies, and professional features elevate the user experience to match real audio software.",
    "metrics": [
      {
        "label": "Components Created",
        "value": "5"
      },
      {
        "label": "Custom Hooks Added",
        "value": "2"
      },
      {
        "label": "FFT Frequency Bins",
        "value": "24"
      },
      {
        "label": "Animation Frame Rate",
        "value": "60 fps"
      },
      {
        "label": "EQ Bands",
        "value": "3"
      },
      {
        "label": "Audio Nodes in Chain",
        "value": "7"
      },
      {
        "label": "Tasks Completed",
        "value": "10"
      }
    ],
    "learned": [
      "Web Audio API requires proper node chaining for volume control - destination.gain doesn't exist",
      "Logarithmic volume scaling (Math.pow) is essential for natural perception",
      "Real-time FFT visualization needs exponential moving average for smooth animation",
      "AnalyserNode.smoothingTimeConstant helps but custom smoothing gives better control",
      "BiquadFilterNode types (lowshelf, peaking, highshelf) map perfectly to 3-band EQ",
      "DynamicsCompressorNode prevents clipping and normalizes volume across tracks",
      "requestAnimationFrame cleanup is critical to prevent memory leaks",
      "Downsampling FFT bins (64 → 24) improves performance without visual loss",
      "VU meters need RMS calculation for accurate audio level measurement",
      "Professional audio features elevate perceived quality dramatically"
    ]
  },
  "files": {
    "transcript": "transcript.md",
    "before": [
      "before/components/WinampModal.tsx",
      "before/components/MinifiedMusicPlayer.tsx",
      "before/components/MusicPlayerContext.tsx",
      "before/NOTE.md"
    ],
    "after": [
      "after/components/WinampModal.tsx",
      "after/components/MinifiedMusicPlayer.tsx",
      "after/components/MusicPlayerContext.tsx",
      "after/hooks/useFFTData.ts",
      "after/hooks/useVUMeter.ts",
      "after/components/EQControls.tsx",
      "after/components/VUMeter.tsx",
      "after/NOTE.md"
    ],
    "assets": [
      "comparison/feature-comparison.md",
      "comparison/visual-comparison.png",
      "comparison/architecture-diagram.svg",
      "before/assets/screenshot-full.png",
      "before/assets/screenshot-visualizer.png",
      "after/assets/screenshot-full.png",
      "after/assets/screenshot-visualizer.png",
      "after/assets/screenshot-eq.png",
      "after/assets/screenshot-vu-meter.png"
    ]
  },
  "createdAt": "2024-11-25T00:00:00Z",
  "featured": true,
  "viewCount": 0
}

---

Best Practices

DO:

✅ Preserve exact before state (don't clean it up) ✅ Capture full conversation transcript when possible ✅ Include quantifiable metrics in outcome ✅ Write clear, actionable learnings ✅ Add visual assets (screenshots, diagrams) ✅ Test your artifact renders correctly locally ✅ Be honest about difficulty level ✅ Credit all skills used with specific roles

DON'T:

❌ Retroactively create artifacts (preserve as you go) ❌ Cherry-pick only successful attempts ❌ Omit failed iterations or dead ends ❌ Exaggerate outcomes or metrics ❌ Include massive binary files (>10MB) ❌ Submit without testing preview locally ❌ Forget to update artifact list in artifacts.tsx

---

Need Help?

• Questions: Open an issue with label artifact-contribution
• Feedback: Suggest improvements to this guide
• Examples: Browse existing artifacts in /website/src/data/artifacts

Happy artifact creating! 🎨

Artifact Preservation Quick Reference

Use this guide while actively creating an artifact. For full details, see ARTIFACT_PRESERVATION.md.

Workflow Checklist

Before Starting Work

• [ ] Create artifact folder: /website/src/data/artifacts/{type}/{skill-name}/{number-name}/
• [ ] Copy current files to before/ folder
• [ ] Components, hooks, contexts
• [ ] Data files
• [ ] Styles and assets
• [ ] Screenshots of current state
• [ ] Create before/NOTE.md explaining what's broken or needs improvement

During Work

• [ ] Save conversation transcript to transcript.md
• [ ] Document decision-making process
• [ ] Note iterations and refinements

After Completion

• [ ] Copy improved files to after/ folder
• [ ] All modified components
• [ ] New hooks, utilities, components
• [ ] Updated styles and assets
• [ ] Screenshots showing improvements
• [ ] Create after/NOTE.md explaining what improved and how
• [ ] Create artifact.json with metadata
• [ ] Write comprehensive README.md
• [ ] Add visual assets (screenshots, diagrams)
• [ ] Test locally: npm run start → navigate to /artifacts

Artifact Types

Folder Structure

/website/src/data/artifacts/{type}/{skill-name}/{number-name}/
├── artifact.json       # REQUIRED: Metadata
├── README.md           # REQUIRED: Overview
├── transcript.md       # OPTIONAL: Conversation log
├── before/             # REQUIRED: Initial state
│   ├── components/
│   ├── data/
│   ├── assets/
│   └── NOTE.md
├── after/              # REQUIRED: Final state
│   ├── components/
│   ├── data/
│   ├── assets/
│   └── NOTE.md
├── comparison/         # OPTIONAL: Side-by-sides
│   └── feature-comparison.md
└── demos/              # OPTIONAL: Standalone previews
    ├── before-demo.html
    └── after-demo.html

artifact.json Template

{
  "id": "{type}-{skill}-{number}-{slug}",
  "title": "Descriptive Title",
  "description": "2-3 sentence summary",
  "type": "single-skill | multi-skill | frontend",
  "skills": [
    {
      "name": "skill_name",
      "role": "What this skill did"
    }
  ],
  "category": "design | development | ai-ml | research | writing | meta",
  "tags": ["tag1", "tag2"],
  "difficulty": "beginner | intermediate | advanced",
  "phases": [
    {
      "name": "Phase Name",
      "skills": ["skill_name"],
      "duration": "time estimate",
      "outcome": "What was accomplished"
    }
  ],
  "outcome": {
    "summary": "Overall result",
    "metrics": [
      { "label": "Metric Name", "value": "123" }
    ],
    "learned": [
      "Key insight 1",
      "Key insight 2"
    ]
  },
  "files": {
    "transcript": "transcript.md",
    "before": ["before/file1.tsx"],
    "after": ["after/file1.tsx"],
    "assets": ["assets/screenshot.png"]
  },
  "createdAt": "2024-11-25T00:00:00Z",
  "featured": false,
  "viewCount": 0
}

Front-End Component Checklist

For UI components like Winamp player:

• [ ] Preserve full component trees (not just changed files)
• [ ] Include all data files and contexts
• [ ] Capture screenshots:
• [ ] Full UI
• [ ] Specific features
• [ ] Before/after comparisons
• [ ] Create standalone demo.html for interactive preview
• [ ] Optimize images (<500KB each)
• [ ] Document or externally host audio/video assets

File Size Guidelines

• Component code: No limit (it's source code)
• Images: < 500KB each (compress with ImageOptim)
• Audio/MIDI: < 1MB each
• Videos: Link to external (YouTube, Vimeo)
• Total artifact: Aim for < 10MB

Remember

✅ DO:

• Preserve exact before state (don't clean it up)
• Include failed attempts and dead ends
• Be honest about metrics and difficulty
• Document all skills used with specific roles
• Test artifact renders correctly before committing

❌ DON'T:

• Retroactively create artifacts (preserve as you go)
• Cherry-pick only successful attempts
• Exaggerate outcomes
• Include massive binaries (>10MB)
• Skip testing preview locally

Testing

# Start dev server
npm run start

# Navigate to artifacts page
open http://localhost:3000/artifacts

# Verify your artifact appears and renders correctly

Submitting

# Add artifact
git add website/src/data/artifacts/{type}/{name}

# Commit
git commit -m "Add artifact: {title}"

# Update artifact imports in artifacts.tsx if needed
# Push and create pull request

---

For complete documentation, see `ARTIFACT_PRESERVATION.md`

skill-documentarian Guides

This directory contains comprehensive guides for the skill-documentarian's responsibilities.

Available Guides

Artifact Preservation

1. [ARTIFACT_PRESERVATION.md](./ARTIFACT_PRESERVATION.md) - Complete artifact preservation guide

• What artifacts are and why they matter
• Three artifact types with structures
• Step-by-step creation process (10 steps)
• Special section for front-end component artifacts
• Full Winamp player example with structure and artifact.json template
• Best practices, file size limits, optimization tips
• DO/DON'T lists

2. [ARTIFACT_QUICKREF.md](./ARTIFACT_QUICKREF.md) - Quick reference for active artifact creation

• Workflow checklist (before/during/after)
• Artifact types comparison table
• Folder structure diagram
• artifact.json template
• Front-end component checklist
• File size guidelines
• Testing and submission commands

When to Use Each Guide

Use ARTIFACT_PRESERVATION.md when:

• Learning about artifacts for the first time
• Need detailed explanations of each artifact type
• Want to understand the full step-by-step process
• Creating your first artifact
• Need examples and templates

Use ARTIFACT_QUICKREF.md when:

• Actively creating an artifact (keep it open as checklist)
• Need quick lookup of structure or commands
• Want file size limits and guidelines at a glance
• Testing and submitting an artifact
• Already familiar with the process

Integration with CLAUDE.md

The artifact preservation guidelines in /Users/erichowens/.claude/CLAUDE.md (lines 15-94) reference these guides. The CLAUDE.md section provides workflow-level guidance, while these documents provide comprehensive implementation details.

Purpose

The skill-documentarian is responsible for:

• Keeping .claude/skills/ and website/docs/skills/ in sync
• Generating missing hero images
• Creating artifacts when skills collaborate
• Validating metadata consistency

These guides support the artifact creation responsibility by providing:

• Complete preservation methodology
• Templates and examples
• Best practices and anti-patterns
• Quick-reference checklists

Related Documentation

• Main Skill Definition: skill-documentarian (on website)
• Website Artifact Guide: Artifact Contribution Guide (on website)
• Artifact Data: website/src/data/artifacts/
• Artifacts Page: Artifacts Showcase (on website)

Artifact Structure Reference

Complete reference for creating and structuring artifacts.

Artifact Types

Directory Structure

website/src/data/artifacts/{type}/{skill-name}/{artifact-id}/
├── artifact.json          # REQUIRED: Metadata
├── README.md             # REQUIRED: Blog-style narrative
├── transcript.md         # OPTIONAL: Implementation log
├── before/               # REQUIRED: Initial state
│   ├── components/
│   ├── data/
│   ├── assets/
│   └── NOTE.md
├── after/                # REQUIRED: Final state
│   ├── components/
│   ├── data/
│   ├── assets/
│   └── NOTE.md
├── comparison/           # OPTIONAL: Side-by-sides
│   └── feature-comparison.md
└── demos/                # OPTIONAL: Standalone previews
    ├── before-demo.html
    └── after-demo.html

artifact.json Schema

{
  "id": "kebab-case-id",
  "title": "Human-Readable Title",
  "type": "single-skill | multi-skill",
  "skills": [
    {
      "name": "skill-name",
      "role": "Specific description of what this skill did..."
    }
  ],
  "phases": [
    {
      "name": "Phase 1: Discovery",
      "skills": ["skill-1"],
      "outcome": "What was achieved in this phase"
    },
    {
      "name": "Phase 2: Implementation",
      "skills": ["skill-1", "skill-2"],
      "outcome": "What was achieved in this phase"
    }
  ],
  "outcome": {
    "summary": "High-level outcome description",
    "metrics": [
      {"label": "Tracks Added", "value": "22"},
      {"label": "Components Created", "value": "15"}
    ],
    "learned": [
      "Real insight gained during development",
      "Technical challenge overcome",
      "Design decision and rationale"
    ]
  },
  "files": {
    "transcript": "transcript.md",
    "before": ["before/component.tsx", "before/styles.css"],
    "after": ["after/component.tsx", "after/styles.css"],
    "assets": ["assets/screenshot.png"]
  },
  "heroImage": "/some_claude_skills/img/artifacts/artifact-hero.png",
  "interactiveDemo": "component-identifier",
  "narrative": [
    "Hook: What makes this interesting?",
    "Journey: How was it built?",
    "Impact: Why does it matter?"
  ]
}

Writing Compelling Narratives

The narrative field tells the STORY. Write 3-5 paragraphs:

Paragraph 1: The Hook

• What makes this interesting?
• Why should anyone care?
• What's novel or surprising?
• Lead with the most compelling detail

Paragraph 2: The Journey

• How was it actually built?
• What challenges were overcome?
• What technical decisions mattered?
• Document what ACTUALLY happened (not formulaic)

Paragraph 3: The Impact

• What's the end result?
• What does this enable?
• For interactive demos: invite them to try it

Narrative Anti-Patterns

Avoid:

• Forcing artificial iteration counts
• Dry technical documentation tone
• Starting with implementation details
• Forgetting to mention interactive demos
• Generic phrases that apply to any project

Instead:

• Authentic story of what happened
• Capture "aha!" moments and surprises
• Make technical decisions relatable
• Invite readers to experience demos
• Include specific, memorable details

Creation Workflow

Step 1: Identify Pattern

Skills involved: [List]
Primary skill: [Which led]
Supporting skills: [Which assisted]
Duration: [How long]

Step 2: Create Structure

mkdir -p website/src/data/artifacts/multi-skill/{skill-name}/{artifact-id}
cd website/src/data/artifacts/multi-skill/{skill-name}/{artifact-id}
touch artifact.json README.md
mkdir before after assets

Step 3: Capture Before State

• Copy relevant files to before/
• Screenshot current state
• Write before/NOTE.md explaining issues

Step 4: Do the Work

• Implement the feature/fix
• Save transcript if valuable

Step 5: Capture After State

• Copy improved files to after/
• Screenshot improvements
• Write after/NOTE.md explaining changes

Step 6: Write artifact.json

• Follow schema exactly
• Include all files referenced
• Write compelling narrative

Step 7: Validate

# Check all referenced files exist
jq -r '.files | to_entries[] | .value[]' artifact.json | while read f; do
  [ -f "$f" ] || echo "Missing: $f"
done

# Verify in website
npm run start
# Navigate to /artifacts

Interactive Demos

For UI components, use interactiveDemo:

{
  "interactiveDemo": "music-player"
}

This embeds the actual working component on the artifact page, allowing visitors to experience the feature directly.

When to Create Artifacts

Create artifacts when:

• Multi-skill collaboration produces something cool
• New pattern emerges (first time X + Y work together)
• Feature demonstrates what's now possible
• User says "wow" or "this is amazing"
• Interactive feature was built

Badge and Metadata Management Reference

Badge System

Badge Types

Badge Assignment Criteria

NEW Badge:

• Skill is first published to showcase
• Persists until next batch of skills arrives
• Auto-remove after ~60 days

UPDATED Badge:

• Major content expansion (50%+ more content)
• New sections added (anti-patterns, decision trees)
• Structural improvements (references folders)
• Auto-remove after ~30 days

Badge Rules

1. One badge per skill - UPDATED takes precedence over NEW 2. Meaningful changes only - Typo fixes don't warrant badges 3. Lifecycle management - Remove stale badges periodically

Where to Update Badges

In website/src/data/skills.ts:

{ id: 'new-skill', title: '...', badge: 'NEW' }
{ id: 'updated-skill', title: '...', badge: 'UPDATED' }

Badge Lifecycle

Skill created → Add NEW badge
     ↓
60 days pass (or new batch arrives)
     ↓
Remove NEW badge
     ↓
Skill significantly improved → Add UPDATED badge
     ↓
30 days pass → Remove UPDATED badge
     ↓
Repeat as improvements are made

Validation Commands

# Count skills with badges
echo "NEW badges: $(grep "badge: 'NEW'" website/src/data/skills.ts | wc -l)"
echo "UPDATED badges: $(grep "badge: 'UPDATED'" website/src/data/skills.ts | wc -l)"

# List skills with badges
grep -E "badge: '(NEW|UPDATED)'" website/src/data/skills.ts

---

Metadata System

Metadata Fields

Stored in website/src/data/skillMetadata.json:

Automatic Generation

Pre-commit hook triggers metadata regeneration:

# When any .claude/skills/ file is staged:
npx tsx scripts/generateSkillMetadata.ts
# Updated skillMetadata.json auto-added to commit

Manual Regeneration

# From website/ directory
npx tsx scripts/generateSkillMetadata.ts

# Or as part of prebuild
npm run prebuild

Website Features Powered by Metadata

• Sortable list view (/skills page "List" mode)
• Sort options: Updated, Created, Lines, Size
• Relative dates: "2 days ago", "Last week"
• Metadata badges: refs, files indicators

Validation Commands

# Verify counts match
echo "Skills: $(ls -d .claude/skills/*/ | wc -l)"
echo "Metadata entries: $(grep '"id":' website/src/data/skillMetadata.json | wc -l)"

# Check for stale entries
for id in $(grep '"id":' website/src/data/skillMetadata.json | sed 's/.*"id": "\([^"]*\)".*/\1/'); do
  if [ ! -d ".claude/skills/$id" ]; then
    echo "Stale metadata: $id"
  fi
done

# Find skills missing metadata
for skill in .claude/skills/*/; do
  name=$(basename "$skill")
  if ! grep -q "\"id\": \"$name\"" website/src/data/skillMetadata.json; then
    echo "Missing metadata: $name"
  fi
done

Metadata JSON Example

{
  "id": "skill-name",
  "createdAt": "2025-01-15",
  "updatedAt": "2025-01-20",
  "totalLines": 450,
  "totalFiles": 5,
  "skillMdSize": 15234,
  "skillMdLines": 293,
  "hasReferences": true,
  "hasExamples": false,
  "hasChangelog": true
}

Documentation Templates Reference

Ready-to-use templates for various documentation types.

README Template

# Project Name

[One-paragraph description: what, why, for whom]

## Quick Start

\`\`\`bash
# Exact commands that work
npm install
npm start
\`\`\`

## Features

- Feature 1: [Brief description]
- Feature 2: [Brief description]

## Documentation

- [Getting Started](docs/getting-started.md)
- [API Reference](docs/api.md)
- [Architecture](docs/architecture.md)

## Contributing

[How to contribute]

## License

[License type]

Tutorial Template

# Tutorial: [Specific Outcome]

**Estimated time**: 15 minutes
**Difficulty**: Beginner/Intermediate/Advanced
**Prerequisites**:
- [Prerequisite 1]
- [Prerequisite 2]

## What You'll Build

[Description + optional screenshot]

## Step 1: [Verb + Noun]

**Why**: [Explain the purpose]

**How**:
\`\`\`bash
# Exact command
\`\`\`

**Result**: [What you should see]

## Step 2: ...

[Repeat pattern]

## Troubleshooting

**Problem**: [Common issue]
**Solution**: [How to fix]

## Next Steps

- [Related tutorial]
- [Advanced topic]

API Reference Template

# API Name

## Overview
[One paragraph: what it does, who it's for]

## Quick Start
[Minimal example that works]

## Endpoints

### GET /resource
**Purpose**: [One line]
**Parameters**:
- `param1` (string, required): [Description]
**Response**: [Example JSON]
**Errors**: [Common error codes]

API Endpoint Template

### `METHOD /endpoint`

**Purpose**: [One-line description]

**Authentication**: Required/Optional/None

**Parameters**:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | [Description] |

**Request Example**:
\`\`\`http
POST /api/endpoint HTTP/1.1
Content-Type: application/json

{
  "param1": "value"
}
\`\`\`

**Response Example**:
\`\`\`json
{
  "success": true,
  "data": {...}
}
\`\`\`

**Error Responses**:
- `400 Bad Request`: [When this happens]
- `404 Not Found`: [When this happens]

Architecture Documentation Template

# System Architecture

## Overview
[Diagram + 2-3 sentences]

## Components
### Component Name
**Responsibility**: [One sentence]
**Dependencies**: [List]
**Key Files**: [Links with line numbers]

## Data Flow
[Sequence diagram or description]

## Decision Records
### ADR-001: [Decision Title]
**Context**: [Why we needed to decide]
**Decision**: [What we chose]
**Consequences**: [Trade-offs accepted]

Skill CHANGELOG Template

# Changelog

All notable changes to this skill will be documented in this file.
Format follows [Keep a Changelog](https://keepachangelog.com/).

## [1.2.0] - 2025-01-15

### Added
- NOT clause in description for precise activation
- "When to Use" / "When NOT to Use" sections
- 3 common anti-patterns with solutions

### Changed
- Expanded from 72 lines to 293 lines
- Added decision trees for core domain logic

### Fixed
- Removed reference to non-existent script

## [1.1.0] - 2024-12-15

### Added
- Anti-pattern section with 2 examples

### Changed
- Improved description keywords

## [1.0.0] - 2024-12-01

### Added
- Initial skill creation
- Core expertise documentation

Style Guide

Voice and Tone

• Active voice: "Run the command" not "The command should be run"
• Second person: "You can configure..." not "One can configure..."
• Present tense: "The function returns..." not "The function will return..."

Formatting

• Headers: Use sentence case, not title case
• Code: Always use fenced code blocks with language
• Lists: Parallel structure (all verbs, all nouns, etc.)
• Links: Descriptive text, not "click here"

Examples

Good: Configure the API key in `.env`:
Bad: You should configure the API key

Good: Returns a list of users
Bad: Will return a list of users

Good: See the [Authentication Guide](./auth.md)
Bad: Click [here](./auth.md) for more info

Quality Checklist

Completeness

• [ ] All public APIs documented
• [ ] All configuration options explained
• [ ] Common use cases have examples
• [ ] Error messages have solutions

Clarity

• [ ] Non-expert can follow quick start
• [ ] Examples are copy-paste ready
• [ ] Technical terms are defined
• [ ] Diagrams aid understanding

Maintainability

• [ ] Docs versioned with code
• [ ] Last-updated dates present
• [ ] Broken links checked in CI
• [ ] Deprecated sections archived

Tag Taxonomy Reference

Complete reference for the skill tag system used in website/src/types/tags.ts.

Tag Types and Colors

Tags are organized into 5 types, each with its own color for visual categorization:

Complete Tag Reference

Skill Type Tags (Purple)

Domain Tags (Blue)

Output Tags (Green)

Complexity Tags (Orange)

Integration Tags (Pink)

Tag Assignment Rules

Quantity Guidelines

• Optimal: 3-5 tags per skill
• Minimum: 2 tags (skill-type + domain)
• Maximum: 6 tags (avoid tag overload)

Required Coverage

Every skill should have at least: 1. One skill-type tag (what it does) 2. One domain tag (what field)

Consider adding: 3. Complexity tag (user guidance) 4. Integration tags (if applicable)

Specificity Principle

Use specific tags over generic ones when appropriate:

• photography beats generic visual for photo skills
• ml beats generic code for ML-focused skills
• robotics beats generic automation for drone skills

User Mental Model Matching

Tags should match what users search for:

• Think: "What would someone type to find this skill?"
• Use common terminology, not internal jargon

Where Tags Are Updated

1. website/src/data/skills.ts

{
  id: 'skill-name',
  title: 'Skill Title',
  category: 'Category Name',
  path: '/docs/skills/skill_name',
  description: 'Brief description',
  tags: ['creation', 'design', 'code', 'beginner-friendly']
}

2. Skill Doc Files (SkillHeader)

<SkillHeader
  skillName="Skill Name"
  fileName="skill_name"
  description="..."
  tags={["creation", "design", "code", "beginner-friendly"]}
/>

3. Tag Type Definition

// website/src/types/tags.ts
export const SKILL_TAGS = [
  { id: 'research', label: 'Research', type: 'skill-type', description: '...' },
  // ... more tags
];

Validation Commands

# List all valid tag IDs
grep "id: '" website/src/types/tags.ts | sed "s/.*id: '\\([^']*\\)'.*/\\1/"

# Count skills using each tag
for tag in research analysis creation coaching; do
  echo "$tag: $(grep "'$tag'" website/src/data/skills.ts | wc -l)"
done

# Find skills missing tags
grep -B5 "tags: \[\]" website/src/data/skills.ts

Adding New Tags

Only add new tags when: 1. Multiple skills (3+) would benefit 2. Existing tags don't cover the concept 3. Users would search for this term

Process: 1. Edit website/src/types/tags.ts 2. Add to appropriate type category:

   { id: 'new-tag', label: 'New Tag', type: 'domain', description: 'What it means' }

3. Use in skills that need it 4. Rebuild to verify: npm run build