| name | skill-repo-planning |
|---|---|
| description | Skill for skill repo planning |
This skill enables systematic analysis of codebases to identify skill gaps—domains, technologies, patterns, and workflows present in repositories that aren't covered by existing skills. Use this to plan which new skills should be created to maximize team effectiveness.
Target: 350-400 lines for focused, actionable guidance Scope: Gap analysis, skill scoping, priority assessment, planning workflow
-
New Repository Analysis
- Discovered repo using technologies not in skills catalog
- Onboarding to unfamiliar codebase with unique patterns
- Inherited legacy system with undocumented conventions
-
Gap Discovery
- After running
skill-repo-discovery.mdreveals missing coverage - Team repeatedly asks questions about same domain
- Recurring patterns found during code review
- Internal tooling lacks documentation
- After running
-
Strategic Planning
- Planning skills expansion for organization
- Capturing specialized domain knowledge before departure
- Standardizing team practices across projects
- Building organizational knowledge base
-
Integration Points
- Custom frameworks/libraries unique to organization
- Company-specific workflows (deployment, testing, auth)
- Third-party service integration patterns
- Internal API conventions
Repository Analysis Needed?
↓
Run skill-repo-discovery.md first
↓
Found gaps in coverage? YES → Use this skill
↓
Identify patterns → Scope skills → Prioritize → Create
Definition: Comparing what exists (current skills) vs. what's needed (repo patterns)
Gap Types:
- Technology gaps: Technologies used but not documented (e.g., Redis patterns, Celery workflows)
- Pattern gaps: Repeated code patterns without guidance (e.g., error handling, retry logic)
- Workflow gaps: Team processes undocumented (e.g., deployment, testing, PR review)
- Domain gaps: Business logic patterns (e.g., payment processing, data pipelines)
Example:
Repository: E-commerce platform
Current skills: swiftui-*, modal-*, zig-*
Gap found: Stripe payment integration repeated in 8 files
→ Missing skill: "stripe-integration-patterns.md"
Philosophy: One skill = One coherent domain (250-400 lines)
Good Skill Boundaries:
- Focused: Covers single technology/pattern comprehensively
- Actionable: Contains enough detail to implement
- Discoverable: Clear naming convention (domain-topic.md)
- Composable: Works with other skills for complex workflows
Bad Skill Boundaries:
- Too broad: "backend-development.md" (thousands of topics)
- Too narrow: "how-to-import-redis.md" (trivial, not reusable)
- Too specific: "fix-bug-in-user-service.md" (one-off solution)
Scoping Example:
WRONG: "python-backend.md" (monolithic)
RIGHT: Atomic skills:
- fastapi-api-design.md
- sqlalchemy-relationships.md
- celery-task-patterns.md
- redis-caching-strategies.md
Impact Dimensions:
- Frequency: How often is this needed? (daily/weekly/monthly/rarely)
- Complexity: How hard is it to figure out each time? (trivial/moderate/complex)
- Team size: How many people need this? (1/few/many)
- Risk: What happens if done wrong? (low/medium/high)
Priority Formula:
Priority = (Frequency × Complexity × Team Size) + Risk Multiplier
High: Daily × Complex × Many people + High risk
Medium: Weekly × Moderate × Few people + Medium risk
Low: Rarely × Simple × One person + Low risk
Example Assessment:
Pattern: Custom auth middleware (15 files)
Frequency: Daily (new services need auth)
Complexity: High (JWT + refresh + RBAC)
Team Size: 8 backend devs
Risk: High (security implications)
→ Priority: HIGH
Pattern: CSV export utility (2 files)
Frequency: Monthly (reports)
Complexity: Low (standard library)
Team Size: 2 people
Risk: Low (data formatting only)
→ Priority: LOW
Five-Phase Process:
Phase 1: Discovery
→ Run skill-repo-discovery.md
→ List all technologies/patterns found
→ Compare against existing skills
Phase 2: Gap Identification
→ Mark what's missing
→ Group related gaps (e.g., all Redis patterns)
→ Filter out trivial/one-off items
Phase 3: Scoping
→ Define skill boundaries (atomic, focused)
→ Name skills clearly (domain-topic.md)
→ Estimate content size (aim 250-400 lines)
Phase 4: Prioritization
→ Score each proposed skill
→ Rank by priority formula
→ Select top N for creation
Phase 5: Creation
→ Use skill-creation.md for implementation
→ Track with beads-workflow.md if multi-session
→ Update _INDEX.md when complete
Scenario: Organization built internal frameworks/libraries
Detection Strategy:
# Find custom imports
grep -r "from internal\." --include="*.py" | cut -d: -f2 | sort | uniq -c | sort -rn
# Find internal package usage
grep -r "@company/" --include="*.ts" | cut -d: -f2 | sort | uniq -c | sort -rn
# Find custom decorators/annotations
grep -rE "@(internal|custom|company)" --include="*.py" --include="*.java"Example:
Found: "from internal.auth import require_role" (47 files)
Gap: No skill for internal auth framework
Proposed: "company-auth-patterns.md"
- Covers: require_role, check_permissions, token validation
- Sections: Setup, decorators, RBAC, testing
Scenario: Same logic duplicated across files (candidates for skills)
Detection Strategy:
# Find repeated error handling
grep -rn "try:" --include="*.py" -A 10 | grep -E "(except|finally)" | wc -l
# Find repeated API patterns
grep -rn "requests\.(get|post)" --include="*.py" | cut -d: -f1 | sort | uniq -c | sort -rn
# Find repeated database patterns
grep -rn "session\.(query|add|commit)" --include="*.py" | cut -d: -f1 | sort | uniq -c | sort -rnExample:
Found: Retry logic repeated in 23 API client files
Gap: No skill for retry/backoff patterns
Proposed: "http-retry-patterns.md"
- Covers: Exponential backoff, circuit breakers, timeout handling
- Examples: tenacity library, custom decorators, testing strategies
Scenario: Custom scripts/tools for deployment, testing, automation
Detection Strategy:
# Find custom scripts
ls scripts/*.{sh,py,js} | xargs -I {} basename {}
# Find Makefile/Justfile targets
grep "^[a-z-]*:" Makefile Justfile 2>/dev/null
# Find GitHub Actions workflows
ls .github/workflows/*.yml | xargs grep "name:"
# Find custom CLI tools
find . -name "*.py" -exec grep -l "if __name__ == .__main__." {} \;Example:
Found: scripts/deploy.sh (custom deployment)
- Uses: kubectl, helm, internal config service
- Called by: CI/CD, manual deploys
Gap: No skill for company deployment process
Proposed: "company-k8s-deployment.md"
- Covers: Environment setup, deploy script, rollback, monitoring
Scenario: Processes unique to organization (not generic best practices)
Detection Areas:
- Code review: Custom checklist, automation, conventions
- Testing: Internal test frameworks, fixtures, CI setup
- Deployment: Blue/green, canary, feature flags
- Monitoring: Internal dashboards, alerting, on-call
- Documentation: RFCs, ADRs, runbooks
Example:
Workflow: Feature flag rollout
- Uses: Internal flag service + LaunchDarkly
- Process: Create flag → Test in staging → Gradual rollout → Metrics review
Gap: No skill for feature flag workflow
Proposed: "company-feature-flags.md"
- Setup, flag creation, targeting rules, monitoring, cleanup
Scenario: Custom ways of combining third-party services
Detection Strategy:
# Find service integrations
grep -rE "(import.*stripe|import.*twilio|import.*sendgrid)" --include="*.py"
# Find Redis + Celery patterns
grep -r "celery" --include="*.py" | grep -l "redis"
# Find Kafka + Postgres patterns
grep -r "KafkaConsumer" --include="*.py" | xargs grep -l "psycopg2"Example:
Found: Kafka → Redis → Postgres pipeline (8 services)
Pattern: Events from Kafka → Cache in Redis → Batch write to Postgres
Gap: No skill for this specific integration
Proposed: "kafka-redis-postgres-pipeline.md"
- Event consumption, caching strategy, batch writes, error handling
# List existing skills
ls .*.md | xargs basename -s .md
# Check for gaps
# Example: Found "FastAPI" in repo, but no fastapi-*.md skills# Custom libraries
grep -r "from (internal|company|custom)" --include="*.py" | cut -d: -f2 | sort | uniq
# Repeated imports (high usage = candidate)
grep -rh "^import\|^from" --include="*.py" | sort | uniq -c | sort -rn | head -20
# Configuration patterns
find . -name "*.yaml" -o -name "*.toml" -o -name "*.json" | head -20
# Testing patterns
grep -r "def test_\|it(" --include="*.py" --include="*.ts" | wc -lTemplate:
## Gap Analysis Report
### Repository: [name]
### Date: [YYYY-MM-DD]
### Analyzer: [name]
### Technologies Found (from skill-repo-discovery.md)
- Python 3.11, FastAPI, SQLAlchemy, Redis, Celery, Pytest
- React, TypeScript, Vite, Tailwind CSS
- Docker, Kubernetes, GitHub Actions
### Existing Skills Coverage
- Python: ✅ (general patterns)
- Redis: ❌ (no redis-*.md skills)
- Celery: ❌ (no celery-*.md skills)
- React: ❌ (no react-*.md skills)
- Kubernetes: ❌ (no k8s-*.md skills)
### Gaps Identified
1. **redis-caching-strategies.md** (HIGH)
- Frequency: Daily
- Complexity: High
- Files: 34 files use Redis
- Patterns: Cache warming, invalidation, pub/sub
2. **celery-task-patterns.md** (HIGH)
- Frequency: Daily
- Complexity: High
- Files: 28 task definitions
- Patterns: Retries, chains, error handling
3. **fastapi-api-design.md** (MEDIUM)
- Frequency: Weekly
- Complexity: Medium
- Files: 15 router files
- Patterns: Dependency injection, auth, validation
4. **company-deployment.md** (LOW)
- Frequency: Weekly
- Complexity: Low
- Files: scripts/deploy.sh
- Patterns: Helm charts, kubectl, rollback## Proposed Skill
**Filename**: [domain-topic.md]
**Target Lines**: 250-400
**Priority**: HIGH/MEDIUM/LOW
**Sections**:
1. Overview (what/when to use)
2. Core Concepts (3-5 key ideas)
3. Common Patterns (5-8 patterns with examples)
4. Quick Reference (commands, config)
5. Anti-Patterns (what not to do)
6. Related Skills (composition)
**Content Sources**:
- Files to analyze: [list 5-10 representative files]
- Documentation: [internal docs, READMEs]
- Team members: [SMEs to consult]
**Validation**:
- [ ] Atomic (focused on one domain)
- [ ] Actionable (enough detail to implement)
- [ ] Discoverable (clear naming)
- [ ] Composable (works with other skills)## Proposed Skill
**Filename**: redis-caching-strategies.md
**Target Lines**: 350 lines
**Priority**: HIGH
**Sections**:
1. Overview - When to cache, cache types
2. Core Concepts - TTL, eviction, serialization, key design
3. Patterns:
- Cache-aside (lazy loading)
- Write-through caching
- Cache warming strategies
- Invalidation patterns
- Pub/Sub for cache busting
- Distributed locking
4. Quick Reference - Redis commands, Python client config
5. Anti-Patterns - Cache stampede, stale data, memory bloat
6. Related Skills - fastapi-api-design.md, celery-task-patterns.md
**Content Sources**:
- Files: src/cache/*.py, src/services/user_cache.py, src/middleware/cache.py
- Docs: docs/caching.md, redis-config.yaml
- SME: Backend lead (10 years Redis experience)
**Validation**:
- [x] Atomic (Redis caching only, not general Redis)
- [x] Actionable (patterns with code examples)
- [x] Discoverable (redis-caching-strategies.md)
- [x] Composable (integrates with FastAPI, Celery skills)| Dimension | Score | Criteria |
|---|---|---|
| Frequency | 3 | Daily use |
| 2 | Weekly use | |
| 1 | Monthly/rare use | |
| Complexity | 3 | High (requires expertise) |
| 2 | Medium (needs guidance) | |
| 1 | Low (self-explanatory) | |
| Team Size | 3 | Entire team (8+ people) |
| 2 | Multiple people (3-7) | |
| 1 | Individual (1-2) | |
| Risk | +3 | High (security, data loss) |
| +1 | Medium (bugs, downtime) | |
| +0 | Low (cosmetic issues) |
Total Score = (Frequency × Complexity × Team Size) + Risk
Proposed Skills:
1. redis-caching-strategies.md
- Frequency: 3 (daily), Complexity: 3 (high), Team: 3 (8 devs), Risk: +1 (medium)
- Score: (3 × 3 × 3) + 1 = 28
- Priority: HIGH
2. celery-task-patterns.md
- Frequency: 3 (daily), Complexity: 3 (high), Team: 2 (4 devs), Risk: +1 (medium)
- Score: (3 × 3 × 2) + 1 = 19
- Priority: HIGH
3. fastapi-api-design.md
- Frequency: 2 (weekly), Complexity: 2 (medium), Team: 3 (8 devs), Risk: +0 (low)
- Score: (2 × 2 × 3) + 0 = 12
- Priority: MEDIUM
4. csv-export-utility.md
- Frequency: 1 (monthly), Complexity: 1 (low), Team: 1 (1 dev), Risk: +0 (low)
- Score: (1 × 1 × 1) + 0 = 1
- Priority: LOW (skip)
[ ] Run skill-repo-discovery.md first
[ ] List all technologies/frameworks used
[ ] Compare against existing skills (ls .*.md)
[ ] Search for repeated imports/patterns (grep -rh "^import")
[ ] Find custom libraries (grep -r "from internal")
[ ] Analyze scripts/tooling (ls scripts/)
[ ] Check CI/CD workflows (.github/workflows/)
[ ] Document integration patterns (service A + B)
[ ] Review team pain points (frequent questions)
[ ] Filter out trivial/one-off items
# Step 1: Discovery
# Use skill-repo-discovery.md
# Step 2: Find patterns
grep -rh "^import\|^from" --include="*.py" | sort | uniq -c | sort -rn | head -20
# Step 3: Scope skills
# Use template above (Filename, Sections, Sources, Validation)
# Step 4: Prioritize
# Use scoring matrix (Frequency × Complexity × Team Size + Risk)
# Step 5: Create skills
# Use skill-creation.md for top priority items
# Step 6: Track progress
bd create "Create redis-caching-strategies.md skill" -t feature -p 1 --jsonProblem: "everything-about-X.md" (thousands of lines, hard to navigate)
Example:
WRONG: python-backend-development.md (covers FastAPI, SQLAlchemy, Celery, Redis, testing, deployment)
RIGHT: Separate skills:
- fastapi-api-design.md
- sqlalchemy-orm-patterns.md
- celery-task-patterns.md
- redis-caching-strategies.md
Problem: Creating skill for code that won't be reused
Example:
WRONG: "fix-user-service-bug.md" (specific to one incident)
RIGHT: "debugging-distributed-systems.md" (general debugging patterns)
Problem: Assuming gap exists without checking if skill already exists under different name
Example:
WRONG: Create "kubernetes-deployment.md" without checking existing skills
RIGHT: Search first:
ls skills/*k8s*.md
ls skills/*deploy*.md
grep -l "kubernetes" skills/*.md
Problem: Documenting technology being phased out
Example:
WRONG: "angular-js-patterns.md" (team migrating to React)
RIGHT: "react-migration-patterns.md" (covers migration process)
Problem: Creating duplicate content instead of referencing related skills
Example:
WRONG: Repeat auth setup in "fastapi-api-design.md" and "celery-task-patterns.md"
RIGHT: Create "company-auth-patterns.md", reference from both skills
- skill-repo-discovery.md: Run first to catalog repository technologies/patterns
- skill-creation.md: Use after planning to implement new skills
- beads-workflow.md: Track skill creation work across sessions
- skill-prompt-planning.md: Plan custom prompts for discovered workflows
1. skill-repo-discovery.md → Catalog repo
2. skill-repo-planning.md → Identify gaps, scope skills (THIS SKILL)
3. beads-workflow.md → Track creation work (if multi-session)
4. skill-creation.md → Implement new skills
5. Update _INDEX.md → Make skills discoverable
# Step 1: Discovery
# Output: Python 3.11, FastAPI, SQLAlchemy, Stripe, Redis, Celery, Pytest
# Step 2: Find patterns
grep -rh "^from\|^import" --include="*.py" src/ | sort | uniq -c | sort -rn | head -20
# Output:
# 47 from internal.auth import require_role
# 34 import redis
# 28 from celery import shared_task
# 23 import stripe
# 15 from fastapi import APIRouter
# Step 3: Identify gaps
ls .*.md | grep -E "(redis|celery|stripe|fastapi)" | wc -l
# Output: 0 (no matching skills)
# Step 4: Scope skills
# - company-auth-patterns.md (internal framework)
# - redis-caching-strategies.md (34 files)
# - celery-task-patterns.md (28 tasks)
# - stripe-integration-patterns.md (payment flows)
# - fastapi-api-design.md (15 routers)
# Step 5: Prioritize
# Auth: (3×3×3)+3 = 30 (HIGH, security risk)
# Redis: (3×3×3)+1 = 28 (HIGH)
# Celery: (3×3×2)+1 = 19 (HIGH)
# Stripe: (2×3×2)+3 = 15 (MEDIUM, payment risk)
# FastAPI: (2×2×3)+0 = 12 (MEDIUM)
# Step 6: Create top 3 skills
bd create "Create company-auth-patterns.md skill" -p 1 --json
bd create "Create redis-caching-strategies.md skill" -p 1 --json
bd create "Create celery-task-patterns.md skill" -p 2 --jsonRepository skill planning transforms ad-hoc knowledge into reusable guidance:
- Discover gaps: Compare repo patterns to existing skills
- Scope atomically: One skill = One focused domain (250-400 lines)
- Prioritize ruthlessly: Frequency × Complexity × Team Size + Risk
- Create systematically: Use skill-creation.md for implementation
- Track progress: Use beads-workflow.md for multi-skill projects
Key principle: Skills capture reusable knowledge, not one-off solutions. If it's repeated, complex, or high-risk, it's a skill candidate.
Follow the workflow: Discovery → Gap analysis → Scoping → Prioritization → Creation.