A skill pack is a curated collection of related skills that together provide comprehensive coverage of a domain. Thoughtful organization transforms a pile of markdown files into a navigable, coherent knowledge system. This skill covers how to plan, structure, and maintain skill packs — from topic selection and gap analysis to directory layout and metadata consistency.

## Key Points

1. Define the domain boundary:
2. Map the knowledge space:
3. Identify essential skills (must-have):
4. Identify valuable skills (nice-to-have):
5. Identify advanced skills (specialized):
6. Prioritize based on:
1. First encounter (setup, hello world)
2. Basic usage (core features, common patterns)
3. Real project (integration, configuration, testing)
4. Production (deployment, monitoring, debugging)
5. Scaling (performance, architecture, advanced patterns)
1. Domain Focus Score (1-5):

Skill Pack Organization and Planning

Purpose

A skill pack is a curated collection of related skills that together provide comprehensive coverage of a domain. Thoughtful organization transforms a pile of markdown files into a navigable, coherent knowledge system. This skill covers how to plan, structure, and maintain skill packs — from topic selection and gap analysis to directory layout and metadata consistency.

Planning a Skill Pack

Topic Selection

Skill Pack Planning Process:

1. Define the domain boundary:
   └── "This pack covers [technology/domain]
        for [audience] doing [tasks]"
   └── Example: "This pack covers PostgreSQL
        for backend developers doing application development"

2. Map the knowledge space:
   ┌──────────────────────────────────────────┐
   │         Domain Knowledge Map             │
   │                                          │
   │  Fundamentals ←→ Implementation ←→ Ops  │
   │  ├── Concepts     ├── Patterns      ├── Deploy  │
   │  ├── Setup        ├── Integration   ├── Monitor │
   │  ├── Basics       ├── Testing       ├── Debug   │
   │  └── Mental Model └── Advanced      └── Scale   │
   └──────────────────────────────────────────┘

3. Identify essential skills (must-have):
   └── What does EVERY user of this technology need?

4. Identify valuable skills (nice-to-have):
   └── What do MOST users encounter eventually?

5. Identify advanced skills (specialized):
   └── What do SOME users need for specific use cases?

6. Prioritize based on:
   ├── Frequency of need (daily > weekly > rare)
   ├── Impact when wrong (security > performance > style)
   ├── Availability elsewhere (fill gaps, don't duplicate docs)
   └── Audience size (broad appeal > niche)

Gap Analysis

Finding Gaps in a Skill Pack:

Method 1: User Journey Mapping
Walk through a typical user's journey with the technology:
1. First encounter (setup, hello world)
2. Basic usage (core features, common patterns)
3. Real project (integration, configuration, testing)
4. Production (deployment, monitoring, debugging)
5. Scaling (performance, architecture, advanced patterns)

Each stage should have at least one skill.
Gaps = stages without coverage.

Method 2: Question Mining
Collect common questions about the technology:
├── Stack Overflow top questions
├── GitHub issues (common confusion)
├── Discord/community FAQ
├── Conference talk topics
└── Tutorial gaps (what do tutorials skip?)

Group questions → identify skill topics.

Method 3: Competitor Analysis
Review existing documentation, books, courses:
├── What topics do they all cover? (essential)
├── What topics do some cover? (valuable)
├── What topics does nobody cover well? (opportunity)
└── What's outdated in existing resources? (refresh opportunity)

Method 4: Matrix Coverage Check
Create a skills matrix and find empty cells:
┌──────────┬───────┬─────────┬──────────┐
│          │ Setup │ Usage   │ Debugging│
├──────────┼───────┼─────────┼──────────┤
│ Feature A│  ✓    │   ✓     │   ✗ ←gap │
│ Feature B│  ✓    │   ✗ ←gap│   ✓      │
│ Feature C│  ✗ ←  │   ✓     │   ✗ ←gap │
└──────────┴───────┴─────────┴──────────┘

Sizing a Pack

Pack Size Guidelines:
├── Minimum viable pack: 5 skills
│   └── Enough to be useful, small enough to ship quickly
├── Standard pack: 10-20 skills
│   └── Comprehensive coverage without overwhelm
├── Large pack: 20-40 skills
│   └── Deep domain coverage, consider splitting into sub-packs
└── Too large: 40+ skills in one pack
    └── Split into related sub-packs

Example split:
kubernetes-skills/ (too large at 35 skills)
→ Split into:
  kubernetes-core/        (10 skills: concepts, resources, kubectl)
  kubernetes-networking/  (8 skills: services, ingress, DNS, policies)
  kubernetes-operations/  (10 skills: deploy, scale, debug, monitor)
  kubernetes-ecosystem/   (7 skills: helm, istio, operators, CRDs)

Directory Structure

Standard Layout

skills/
├── pack-name/
│   ├── fundamentals.md           (or technology-fundamentals.md)
│   ├── topic-a.md
│   ├── topic-b.md
│   ├── topic-c.md
│   └── advanced-topic.md

Naming Rules:
├── Directory: kebab-case, plural or descriptive
│   ├── GOOD: react-skills/, database-patterns/, devops-workflows/
│   └── BAD: React/, db/, misc/
├── Files: kebab-case, descriptive of content
│   ├── GOOD: react-hooks-patterns.md, postgresql-indexing.md
│   └── BAD: chapter1.md, advanced.md, guide.md
└── No nested directories within a pack
    └── Flat structure is simpler and more predictable

Ordering Without Prefixes

Don't use numeric prefixes (001-xxx.md).
They break when you insert a skill in the middle.

Instead, establish reading order through:
├── A "start here" skill (fundamentals, overview, setup)
├── Cross-references: Each skill links to logical next skill
├── "When to Apply" sections guide selection
└── If pack has a reading order, document it in the pack description

Reading Order via Cross-Reference:
fundamentals.md:
  "After reading this, continue with 'Core Patterns'
   for implementation guidance."

core-patterns.md:
  "Prerequisites: 'Fundamentals'. Next: 'Advanced Patterns'
   or 'Testing' depending on your need."

This creates a navigable graph, not a rigid sequence.

Metadata Consistency

Frontmatter Standards

Consistency Rules Across a Pack:

Category:
├── Same category value for all skills in the pack
├── Must match the directory name
└── Example: all files in react-skills/ use category: "react-skills"

Tags:
├── Establish a tag vocabulary before writing
├── Share at least 1-2 common tags across all skills in pack
├── Use the technology name tag in every skill
└── Example: All react-skills skills include tag "react"

Version:
├── Independent per skill (each has its own version)
├── Start all new skills at "1.0.0"
└── Version represents the skill's content version, not the pack version

Title Format:
├── Consistent pattern across pack
├── Include technology name in title (for discovery)
├── Example pattern: "React: [Specific Topic]" or "[Specific Topic] in React"
└── Pick one pattern and use it consistently

Tag Vocabulary for a Pack

Example Tag Vocabulary (React Skills Pack):

Technology tags (use in every skill):
├── "react"

Concept tags (use where applicable):
├── "hooks"
├── "state-management"
├── "server-components"
├── "performance"
├── "testing"
├── "routing"
├── "forms"
├── "styling"

Level tags (one per skill):
├── "fundamentals"
├── "intermediate"
├── "advanced"

Ecosystem tags (use when relevant):
├── "nextjs"
├── "typescript"
├── "redux"
├── "tanstack-query"

Maintaining the vocabulary:
├── Document in a TAGS.md or pack metadata file
├── Review when adding new skills
├── Refactor existing tags if vocabulary evolves
└── Avoid tag proliferation (merge similar tags)

Pack Quality Standards

Cohesion Metrics

Assess Pack Cohesion:

1. Domain Focus Score (1-5):
   5: All skills clearly in the same domain
   3: Most skills related, a few outliers
   1: Grab bag of loosely related topics
   → Target: 4-5

2. Cross-Reference Density:
   Count: How many skills reference other skills in the pack?
   High density (>70%): Well-connected, navigable
   Low density (<30%): Skills feel isolated, may not belong together
   → Target: >50%

3. Coverage Completeness:
   Map user tasks in the domain.
   What % of common tasks have a skill?
   → Target: >80% of common tasks covered

4. Depth Consistency:
   Are all skills similar depth (200-400 lines)?
   Or is one skill 50 lines and another 600?
   → Target: No skill more than 2x the length of the shortest

5. Terminology Consistency:
   Is the same concept called the same name across all skills?
   → Target: 100% consistent terminology

Pack Review Process

Pack Review Checklist:
□ All skills have valid, consistent frontmatter
□ Category matches directory name in all skills
□ Tag vocabulary is consistent across pack
□ No duplicate coverage (two skills covering same topic)
□ No significant gaps (common tasks without coverage)
□ Cross-references between skills are valid
□ Reading order is discoverable (through references or docs)
□ Each skill stands alone (doesn't require reading entire pack)
□ Skill depth is consistent (no outliers)
□ All code examples are in the same language/framework version
□ "When to Apply" sections don't overlap confusingly
□ Pack size is manageable (5-30 skills)

Evolving a Pack

Pack Evolution Patterns:

Growth:
├── Start with 5-8 core skills (MVP pack)
├── Gather user feedback on gaps
├── Add skills based on demand
├── Review for cohesion with each addition
└── Split if pack exceeds 30 skills

Maintenance:
├── Quarterly review of all skills in pack
├── Update for new technology versions
├── Deprecate outdated skills
├── Merge skills that overlap significantly
└── Split skills that have grown too long

Versioning the Pack (not individual skills):
├── Track pack-level version in a manifest file
├── MINOR: Skills added or updated
├── MAJOR: Skills removed, restructured, or domain scope changed
└── Pack version independent of individual skill versions

When to Apply This Skill

Use this skill when:

• Planning a new skill pack from scratch
• Assessing an existing skill pack for quality and completeness
• Adding a new skill to an existing pack
• Deciding whether to split or merge skill packs
• Establishing metadata standards for a team's skill packs
• Conducting periodic review of a skill pack's health