firefrost-gaming/claude-skills-reference

Files

Reza Rezvani c1af2fc89a fix(docs): correct marketing skill count to 6, total to 53, codex to 48

Devin review identified two count inaccuracies:
1. Marketing skills: 7 → 6 (only 6 directories exist under marketing-skill/)
2. Codex skill entries: 47 → 48 (.codex/skills/ has 48 entries)
3. Total skills: 54 → 53 (6+18+5+2+6+12+3+1)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-10 07:57:58 +01:00

31 KiB

Raw Blame History

Growth Strategy: Skills & Agents Enhancement

Last Updated: February 2026 Status: Active Framework Owner: Development Team

Executive Summary

This document outlines the systematic process for adding new skills, enhancing existing agents, and maintaining the claude-code-skills ecosystem as it scales from 53 to 60+ skills by Q3 2026.

Key Principles:

Skill-First Design: Skills are portable, self-contained expertise packages
Agent-Skill Mapping: Each agent references skills via relative paths (not embedded)
Backward Compatibility: New skills enhance but don't break existing workflows
Documentation-Driven: Every addition requires complete documentation updates
Quality Gates: All additions pass the same quality standards as initial releases

Part 1: Adding New Skills

Step 1: Skill Ideation & Validation

Decision Criteria (must meet 3 of 5):

Saves users 40%+ time on repetitive tasks
Improves output quality by 30%+ vs manual work
Addresses gap in current skill portfolio
Requested by 3+ users or organizations
Provides algorithmic tools (not just documentation)

Domain Assignment:

Marketing: Brand, content, demand gen, analytics, SEO, social media
C-Level: CEO/CTO strategic decision-making
Product: PM, PO, strategist, UX research, design systems
Project Management: PM, Scrum Master, Atlassian tools
Engineering: Core (architecture, frontend, backend, fullstack, QA, DevOps, security)
Engineering: AI/ML/Data (data science, ML, prompts, computer vision)
Engineering: Specialized (cloud platforms, enterprise tools, methodologies)
Regulatory/Quality: RA, QMS, compliance, auditing

Step 2: Skill Package Creation

Required Structure:

domain-folder/skill-name/
├── SKILL.md              # Master documentation (500-1500 lines)
├── scripts/              # Python CLI tools (optional but preferred)
│   ├── tool1.py
│   ├── tool2.py
│   └── README.md
├── references/           # Expert knowledge bases
│   ├── framework1.md
│   └── framework2.md
└── assets/               # User-facing templates
    ├── template1.md
    └── example-data/

SKILL.md Template Structure:

Header (Status, Version, Description, Time savings)
What's Included (Tools, references, templates)
Skill Capabilities (Detailed feature list)
Quick Start (3-step workflow)
Detailed Workflows (5-8 use cases with examples)
Python Tools Reference (If applicable)
References (Links to knowledge bases)
Templates & Examples
Best Practices
Related Skills (Cross-references)

Quality Checklist:

SKILL.md follows standard template structure
At least 1 Python CLI tool (unless prompt-only skill)
Python tools use standard library only (minimal dependencies)
2+ reference markdown files with expert frameworks
3+ user-facing templates in assets/
All relative paths work from skill folder
Clear time savings metrics documented
Examples use realistic data and scenarios

Step 3: Documentation Updates

Must Update (in order):

Domain CLAUDE.md ({domain}/CLAUDE.md)
- Add skill to navigation section
- Update skill count in header
- Add any domain-specific tool patterns
Main README.md (/README.md)
- Update "At a Glance" skill count (line ~33)
- Add detailed skill description in appropriate domain section
- Update roadmap "Current Status" section with new count
- Update "Projected Impact" table (lines ~1712-1716)
- Update "ROI Metrics" time savings calculation
- Recalculate financial impact and annual ROI
Project CLAUDE.md (/CLAUDE.md)
- Update "Current Scope" line with new total count
- Add note in appropriate domain section if significant addition
PYTHON_TOOLS_AUDIT.md (/documentation/PYTHON_TOOLS_AUDIT.md)
- Add all new Python tools with line counts
- Update total tool count
- Update summary statistics
Domain Roadmaps (if applicable)
- Mark skill as "✅ Complete" in appropriate roadmap file
- Update phase completion statistics

Step 4: Testing & Validation

Functional Testing:

# Test Python tools
cd {domain}/{skill-name}/scripts/
python tool1.py --help
python tool1.py --test-mode  # If test mode exists

# Test relative paths
cd agents/
# Verify all skill references resolve correctly
grep -r "../../{domain}/{skill-name}" .

Documentation Testing:

All markdown links resolve (no 404s)
All code examples are syntactically correct
All relative paths work from multiple entry points
SKILL.md renders correctly in GitHub

Quality Gates:

# Check markdown formatting
markdownlint {domain}/{skill-name}/**/*.md

# Verify no hardcoded paths
grep -r "/Users/" {domain}/{skill-name}/
grep -r "C:\\" {domain}/{skill-name}/

# Check file naming conventions (lowercase with hyphens)
find {domain}/{skill-name} -name "*[A-Z]*"

Step 5: Git Workflow

Branch Strategy:

# Always start from dev
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/skill-{skill-name}

# Make changes, then commit
git add {domain}/{skill-name}/
git add README.md CLAUDE.md {domain}/CLAUDE.md documentation/
git commit -m "feat(skills): add {skill-name} skill to {domain} domain

- Complete SKILL.md with 8 workflows and 12 examples
- {N} Python CLI tools: {list tools}
- {N} reference frameworks: {list references}
- {N} ready-to-use templates in assets/

Metrics:
- Time savings: {X}% reduction in {task} time
- Quality improvement: {Y}% increase in {metric}

Updates:
- README.md: Added skill description, updated counts (48→49)
- CLAUDE.md: Updated skill count in scope
- {domain}/CLAUDE.md: Added navigation reference
- PYTHON_TOOLS_AUDIT.md: Added {N} tools ({X} lines)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

# Push and create PR
git push origin feature/skill-{skill-name}
gh pr create --base dev --title "feat(skills): Add {Skill Name} skill" \
  --body "## Summary
- New {domain} skill: {Skill Name}
- {N} Python tools, {N} references, {N} templates
- Time savings: {X}%, Quality: {Y}%

## Checklist
- [x] SKILL.md complete with all sections
- [x] Python tools tested and documented
- [x] All documentation updated
- [x] Quality gates passed

## Files Changed
- New: {domain}/{skill-name}/ (complete skill package)
- Updated: README.md, CLAUDE.md, {domain}/CLAUDE.md
- Updated: documentation/PYTHON_TOOLS_AUDIT.md

Closes #{issue_number}"

Part 2: Enhancing Agents with New Skills

Current Agent-Skill Architecture

Existing Agents (5):

cs-content-creator → marketing-skill/content-creator/
cs-demand-gen-specialist → marketing-skill/marketing-demand-acquisition/
cs-ceo-advisor → c-level-advisor/ceo-advisor/
cs-cto-advisor → c-level-advisor/cto-advisor/
cs-product-manager → product-team/product-manager-toolkit/

Agent Structure:

---
name: cs-skill-name
description: One-line description
tools: [Read, Write, Grep, Bash]
---

# Core Instructions
[Agent behavior and workflows]

## Available Skills

### Primary Skill: {Skill Name}
**Location:** ../../{domain}/{skill-name}/
**When to use:** [Specific use cases]
**Key capabilities:** [Bullet list]

[Detailed workflows...]

Creating Agent for New Skill

When to create a new agent:

New skill represents distinct professional role
Skill has 8+ workflows that benefit from orchestration
Skill includes 3+ Python tools requiring coordination
Users would invoke skill via slash command (e.g., /optimize-aso)

Agent Creation Process:

Create Agent File (agents/{category}/cs-{skill-name}.md)

---
name: cs-{skill-name}
description: {One-line description matching skill}
tools: [Read, Write, Grep, Bash]
model_preference: sonnet  # or opus for strategic/C-level
---

# cs-{skill-name}

Expert agent for {domain} using the {Skill Name} skill.

## Core Capabilities

{List 5-8 main capabilities from SKILL.md}

## Available Skills

### Primary Skill: {Skill Name}
**Location:** ../../{domain}/{skill-name}/
**Documentation:** ../../{domain}/{skill-name}/SKILL.md

{Paste key workflows from SKILL.md}

## Execution Patterns

### Pattern 1: {Common Use Case}
[Step-by-step workflow with tool invocations]

### Pattern 2: {Another Use Case}
[Step-by-step workflow]

## Python Tools

**Available Tools:**
- `{tool1.py}`: {Description}
  ```bash
  python ../../{domain}/{skill-name}/scripts/{tool1.py} {args}

[List all tools with examples]

Quality Standards

Validate all inputs before processing
Use Python tools for analysis when available
Reference templates from skill assets/
Follow domain best practices from references/

Integration Points

Works well with:

{Related agent 1}: For {use case}
{Related agent 2}: For {use case}


2. **Update Agent Catalog** (`documentation/team-and-agents/comprehensive-agent-catalog.md`)
   - Add agent to appropriate category
   - Link to skill location
   - Document agent capabilities

3. **Create Slash Command** (if appropriate)
   - Create `.claude/commands/{command-name}.md`
   - Command invokes agent with skill context
   - Example: `/optimize-aso` → loads cs-app-store-optimizer agent

4. **Update AGENTS.md** (`/.gitignore` currently ignores, but update for documentation)
   - Add agent to list
   - Reference skill location
   - Document common use cases

### Enhancing Existing Agent with New Skill

**When to enhance existing agent:**
- New skill complements existing agent's domain
- Skills have overlapping use cases (e.g., content + social media)
- Agent would benefit from additional tools/frameworks
- Skills form logical workflow sequence

**Enhancement Process:**

1. **Add Secondary Skill Reference:**
```markdown
## Available Skills

### Primary Skill: {Original Skill}
**Location:** ../../{domain}/{original-skill}/
[Keep existing content]

### Secondary Skill: {New Skill}
**Location:** ../../{domain}/{new-skill}/
**When to use:** {Specific scenarios where this skill adds value}
**Key capabilities:**
- {Capability 1}
- {Capability 2}

**Integration example:**
[Show workflow combining both skills]

Add Coordinated Workflows:

## Cross-Skill Workflows

### Workflow: {Task requiring both skills}
1. Use {Primary Skill} for {step}
2. Use {Secondary Skill} for {step}
3. Combine outputs for {result}

**Example:**
[Concrete example with data]

Update Agent Description:
- Mention both skills in frontmatter description
- Update capabilities list
- Add tools from new skill
Test Integration:
- Verify relative paths work
- Test workflows using both skills
- Ensure no conflicts in tool names

Part 3: Agent-Skill Mapping Maintenance

Mapping Matrix (Current State)

Agent	Primary Skill	Secondary Skills	Python Tools	Status
cs-content-creator	content-creator	-	5 tools	✅ Active
cs-demand-gen-specialist	marketing-demand-acquisition	-	4 tools	✅ Active
cs-ceo-advisor	ceo-advisor	-	0 (strategic)	✅ Active
cs-cto-advisor	cto-advisor	-	0 (strategic)	✅ Active
cs-product-manager	product-manager-toolkit	-	8 tools	✅ Active

Mapping Matrix (Target State - Q1 2026)

Agent	Primary Skill	Secondary Skills	Python Tools	Status
cs-content-creator	content-creator	social-media-analyzer	8 tools	📋 Planned
cs-demand-gen-specialist	marketing-demand-acquisition	-	4 tools	✅ Active
cs-aso-specialist	app-store-optimization	-	6 tools	📋 Planned
cs-social-media-manager	social-media-analyzer	content-creator	3 tools	📋 Planned
cs-ceo-advisor	ceo-advisor	-	0 (strategic)	✅ Active
cs-cto-advisor	cto-advisor	-	0 (strategic)	✅ Active
cs-product-manager	product-manager-toolkit	-	8 tools	✅ Active
cs-aws-architect	aws-solution-architect	-	4 tools	📋 Planned
cs-ms365-admin	ms365-tenant-manager	-	5 tools	📋 Planned

Maintenance Schedule

Monthly Review:

Check for orphaned skills (skills without agents)
Review agent performance feedback
Identify skills that would benefit from combination
Update mapping matrix with new additions

Quarterly Planning:

Plan new agent creations based on user demand
Schedule agent enhancements with new skills
Review and update cross-skill workflows
Plan orchestrator pattern updates

Annual Audit:

Complete agent-skill mapping review
Deprecate unused agents (archive, don't delete)
Consolidate overlapping agents if appropriate
Update documentation architecture

Part 4: Version Control & Compatibility

Versioning Scheme

Skills:

Version format: X.Y (major.minor)
Major version (X): Breaking changes to tool APIs or workflow structure
Minor version (Y): New features, enhancements, documentation improvements
Document version in SKILL.md header

Agents:

Version format: X.Y.Z (major.minor.patch)
Major version (X): Breaking changes to agent interface
Minor version (Y): New skills added or workflows enhanced
Patch version (Z): Bug fixes, documentation updates
Document version in agent frontmatter

Backward Compatibility Rules

DO:

✅ Add new Python tools with unique names
✅ Add new workflows to SKILL.md
✅ Enhance existing workflows with more examples
✅ Add new reference frameworks
✅ Add new templates to assets/
✅ Add optional parameters to Python tools (with defaults)

DON'T:

❌ Rename existing Python tools (create new, deprecate old)
❌ Change Python tool required parameters
❌ Remove workflows from SKILL.md (mark deprecated instead)
❌ Change folder structure of existing skills
❌ Break relative path references in agents
❌ Remove or rename files that agents reference

Deprecation Process

Deprecating a Tool:

Add deprecation notice to tool docstring
Update SKILL.md with deprecation warning
Create replacement tool with new name
Maintain old tool for 2 minor versions (6 months)
Archive (don't delete) after deprecation period

Deprecating a Skill:

Add deprecation notice to SKILL.md header
Update all agent references with alternatives
Move skill to archived-skills/ folder
Keep documentation accessible but mark clearly
Update README.md to show skill as archived

Migration Path for Breaking Changes

If breaking change is necessary:

Create Migration Guide ({skill}/MIGRATION.md)

# Migration Guide: {Skill Name} v{X}.0

## Breaking Changes
- Change 1: {Description and impact}
- Change 2: {Description and impact}

## Migration Steps
1. Step 1
2. Step 2

## Before/After Examples
[Code examples showing old vs new]

Support Dual Versions Temporarily
- Keep old version in {skill-name}-v{X-1}/
- New version in {skill-name}/
- Both documented and functional for 1 major version cycle
Update All Agent References
- Update relative paths in agents
- Test all workflows with new version
- Update agent documentation
Communicate Changes
- Update README.md with migration notice
- Update CHANGELOG.md with breaking changes
- Add notice to project CLAUDE.md

Part 5: Quality Assurance Framework

Pre-Addition Checklist

Before committing new skill:

SKILL.md complete and follows template
All Python tools have --help and --version flags
All Python tools handle errors gracefully (no stack traces for user errors)
All relative paths tested and working
All markdown links resolve correctly
All code examples are syntactically correct
Time savings metrics calculated and documented
At least 3 real-world examples included
Cross-references to related skills added
All documentation files updated (README.md, CLAUDE.md, etc.)

Post-Addition Validation

Within 1 week of merge:

User feedback collected (if early adopter program)
Tool usage tracked (if telemetry enabled)
Documentation clarity verified
Integration with existing agents tested

Within 1 month:

Review skill usage patterns
Identify missing workflows based on user requests
Plan enhancements for next minor version
Update examples based on real-world usage

Success Metrics

Skill Success Indicators:

Saves users 40%+ time (validated through feedback)
Used in 10+ projects within first month
Positive feedback rating (if collecting)
Referenced by other skills (cross-pollination)
Agent created for skill (validates demand)

Agent Success Indicators:

Invoked via slash command 50+ times/month
Maintains 90%+ success rate (task completion)
Positive user feedback
Enhanced with 2+ skills over time
Documented in user workflows

Part 6: Growth Projections & Resource Planning

Current State (Q4 2025)

Skills: 53 (6 marketing, 2 C-level, 5 product, 6 PM, 18 engineering, 12 RA/QM, 3 business & growth, 1 finance)
Agents: 5 (cs-content-creator, cs-demand-gen-specialist, cs-ceo-advisor, cs-cto-advisor, cs-product-manager)
Python Tools: 87+
Active Users: Early adopters (estimated 25 organizations)

Target State (Q3 2026)

Skills: 55+ (target breakdown below)
Agents: 12-15 (one agent per 4-5 skills average)
Python Tools: 110+
Active Users: 250+ organizations

Domain Growth Roadmap

Marketing (6 → 10):

✅ Content Creator
✅ Marketing Demand & Acquisition
✅ Marketing Strategy & Product Marketing
✅ App Store Optimization
✅ Social Media Analyzer
✅ Campaign Analytics
📋 SEO Optimizer (Q1 2026)
📋 Social Media Manager (Q1 2026)

C-Level (2 → 2): Stable, mature

✅ CEO Advisor
✅ CTO Advisor

Product (5 → 6):

✅ Product Manager Toolkit
✅ Agile Product Owner
✅ Product Strategist
✅ UX Researcher Designer
✅ UI Design System
📋 Product Analytics (Q2 2026)

Project Management (6 → 8):

✅ Senior PM Expert
✅ Scrum Master Expert
✅ Atlassian Jira Expert
✅ Atlassian Confluence Expert
✅ Atlassian Administrator
✅ Atlassian Template Creator
📋 Asana Expert (Q2 2026)
📋 Monday.com Expert (Q2 2026)

Engineering - Core (13 → 16):

✅ 9 existing core engineering skills
✅ AWS Solution Architect
✅ Microsoft 365 Tenant Manager
✅ TDD Guide
✅ Tech Stack Evaluator
📋 Google Cloud Architect (Q2 2026)
📋 Azure Solution Architect (Q2 2026)
📋 Mobile Engineer (Q3 2026)

Engineering - AI/ML/Data (5 → 7):

✅ 5 existing AI/ML/Data skills
📋 MLOps Engineer (Q2 2026)
📋 NLP Engineer (Q3 2026)

RA/QM (12 → 12): Complete, mature domain

Business & Growth (3 → 4):

✅ Customer Success Manager
✅ Sales Engineer
✅ Revenue Operations
📋 Growth Marketer (Q2 2026)

Finance (1 → 1): Complete

✅ Financial Analyst

Resource Requirements

Per New Skill (average):

Development time: 12-20 hours
Documentation time: 6-10 hours
Testing time: 4-6 hours
Python tools: 2-4 scripts
Reference frameworks: 2-3 files
Templates: 3-5 files
Total: 22-36 hours per skill

Per New Agent (average):

Agent creation: 4-6 hours
Workflow integration: 3-5 hours
Testing with skill: 2-3 hours
Documentation updates: 2-3 hours
Total: 11-17 hours per agent

Quarterly Capacity Planning (Q1 2026):

3 new skills × 30 hours = 90 hours
2 new agents × 15 hours = 30 hours
Documentation maintenance = 20 hours
Total: 140 hours (3.5 weeks FTE)

Part 7: Orchestrator Integration Strategy

Phase 1: Manual Agent Invocation (Current)

Users invoke agents individually via @agents/cs-{name}
Each agent is self-contained with single skill focus
No cross-agent coordination

Phase 2: Slash Command Orchestration (Sprint 11-06-2025)

Orchestrator agent (cs-orchestrator) routes tasks to specialist agents
Task-based commands (/write-blog, /plan-campaign, /optimize-aso)
Hybrid routing: 95% rule-based, 5% AI-based
Max 5 agents per workflow
Token-optimized with prompt caching

Orchestrator Integration for New Skills:

Create Routing Rule (agents/orchestrator/routing-rules.yaml)

- command: /{skill-command}
  keywords: [kw1, kw2, kw3]
  agent: cs-{skill-name}
  confidence: high
  examples:
    - "User request example 1"
    - "User request example 2"

Update Orchestrator Context (agents/orchestrator/cs-orchestrator.md)
- Add skill to available agents list
- Document coordination patterns if skill works with others
- Update routing logic documentation

Create Slash Command (.claude/commands/{command-name}.md)

# /{command-name}

Invokes cs-{skill-name} agent via orchestrator.

**Usage:** `/{command-name} [task description]`

**Examples:**
- `/{command-name} {specific task}`
- `/{command-name} {another task}`

**What happens:**
1. Orchestrator routes to cs-{skill-name}
2. Agent loads {skill-name} skill
3. Executes workflow using skill tools and references
4. Returns results to user

Test Orchestration:

# Test command routing
/{command-name} test task

# Verify correct agent invoked
# Check skill loaded correctly
# Validate output quality

Phase 3: Multi-Agent Workflows (Future)

Orchestrator spawns 2-5 agents for complex tasks
Sequential handoffs (agent A → agent B)
Parallel execution (agents A + B → orchestrator merge)
Quality gates between agent transitions

Example Multi-Agent Workflow:

User: "Create a complete marketing campaign for our new product"

Orchestrator:
1. cs-product-manager → Analyze product positioning
2. cs-marketing-strategist → Create campaign strategy
3. cs-content-creator → Generate campaign content
4. cs-demand-gen-specialist → Plan acquisition channels
5. Orchestrator → Merge outputs into cohesive campaign plan

Part 8: Community Contribution Process

Accepting External Skills

Contribution Evaluation Criteria:

Meets quality standards (see Part 5)
Fills genuine gap in portfolio
Provides algorithmic tools (not just docs)
Clear time savings demonstrated
Maintainer commits to support

Evaluation Process:

PR submitted with new skill
Automated checks (linting, structure)
Manual review (quality, uniqueness)
User testing (if possible)
Decision: Accept / Request changes / Decline

Acceptance Workflow:

Merge to dev branch
Include in next release cycle
Add contributor to CONTRIBUTORS.md
Feature in release notes
Monitor usage and feedback

Encouraging Contributions

Contribution Incentives:

Recognition in repository README.md
Featured in release announcements
Access to early adopter community
Priority support for contributed skills

Contributor Resources:

Complete contribution guide (CONTRIBUTING.md)
Skill template repository
Automated validation tools
Community Discord/Slack for support

Part 9: Monitoring & Analytics

Skill Usage Tracking (If Implementing)

Key Metrics:

Skill invocations per month
Most-used Python tools per skill
Average time savings per skill (user-reported)
Skill combinations (which skills used together)
Agent success rates by skill

Growth Indicators

Monthly Tracking:

New skills added
New agents created
Documentation updates
Bug fixes / enhancements
Community contributions

Quarterly Review:

Skill adoption rates
Most/least used skills
User feedback themes
Roadmap adjustments based on data

Success Dashboard (Example)

┌─────────────────────────────────────────────┐
│ Claude Code Skills - Growth Dashboard      │
│ Quarter: Q1 2026                            │
├─────────────────────────────────────────────┤
│ Skills: 51 (+3 this quarter)                │
│ Agents: 8 (+3 this quarter)                 │
│ Python Tools: 85 (+17 this quarter)         │
│ Active Users: 450 orgs (+425 this quarter)  │
│ Avg Time Savings: 68% (target: 70%)        │
│ Quality Improvement: 63% (target: 65%)      │
│ Community Contributions: 2 skills           │
├─────────────────────────────────────────────┤
│ Top 5 Skills (by usage):                    │
│ 1. Content Creator (2,340 invocations)     │
│ 2. Product Manager Toolkit (1,890 inv)     │
│ 3. Senior Backend Engineer (1,560 inv)     │
│ 4. AWS Solution Architect (980 inv)        │
│ 5. Demand Gen Specialist (875 inv)         │
└─────────────────────────────────────────────┘

Part 10: Risk Management & Mitigation

Key Risks

Risk 1: Skill Sprawl

Description: Too many similar skills causing user confusion
Mitigation: Regular consolidation reviews, clear skill differentiation
Indicator: Multiple skills with <50 invocations/month

Risk 2: Agent-Skill Drift

Description: Agents referencing outdated skill versions
Mitigation: Automated link checking, version compatibility matrix
Indicator: Broken relative paths, agent errors

Risk 3: Quality Degradation

Description: Rapid growth compromising quality standards
Mitigation: Mandatory quality gates, peer review, automated testing
Indicator: User complaints, low success rates

Risk 4: Maintenance Burden

Description: Skills requiring updates faster than capacity
Mitigation: Prioritize high-usage skills, community contributions
Indicator: Backlog of enhancement requests >30 days old

Risk 5: Orchestrator Overload

Description: Too many agents overwhelming orchestrator
Mitigation: Max 15 agents enforced, consolidated routing rules
Indicator: Routing latency >2s, routing errors >5%

Mitigation Action Plans

If Skill Sprawl Detected:

Audit all skills <50 invocations/month
Identify consolidation opportunities
Deprecate redundant skills
Merge overlapping capabilities

If Agent-Skill Drift Detected:

Run automated link checker
Update agent references
Test all workflows end-to-end
Update version compatibility matrix

If Quality Degradation Detected:

Pause new skill additions
Comprehensive quality audit
Fix all quality issues
Reinforce quality gates

Appendix A: Templates

New Skill Proposal Template

# Skill Proposal: {Skill Name}

**Domain:** {marketing / c-level / product / pm / engineering / ra-qm}
**Proposed By:** {Name}
**Date:** {YYYY-MM-DD}

## Problem Statement
{What problem does this skill solve? Be specific.}

## Target Users
{Who will use this skill? Roles, industries, company sizes.}

## Value Proposition
- Time savings: {X}% reduction in {task}
- Quality improvement: {Y}% increase in {metric}
- Gap filled: {What's currently missing?}

## Proposed Components

### Python Tools ({N} tools)
1. **{tool-name}.py**: {Purpose}
2. **{tool-name}.py**: {Purpose}

### Reference Frameworks ({N} files)
1. **{framework-name}.md**: {Content}
2. **{framework-name}.md**: {Content}

### Templates ({N} files)
1. **{template-name}.md**: {Use case}

## Estimated Development
- Development: {X} hours
- Documentation: {Y} hours
- Testing: {Z} hours
- **Total: {X+Y+Z} hours**

## Success Metrics
- {Metric 1}: {Target}
- {Metric 2}: {Target}
- {Metric 3}: {Target}

## Approval Checklist
- [ ] Meets 3 of 5 decision criteria
- [ ] Unique from existing skills
- [ ] Realistic development timeline
- [ ] Clear success metrics defined

Agent Enhancement Proposal Template

# Agent Enhancement: cs-{agent-name}

**Current Skills:** {List current skills}
**Proposed Addition:** {New skill to add}
**Date:** {YYYY-MM-DD}

## Enhancement Rationale
{Why add this skill to this agent? What workflows benefit?}

## Integration Plan
- {Workflow 1}: How skills combine
- {Workflow 2}: How skills combine

## Updated Capabilities
{List all capabilities after enhancement}

## Testing Plan
1. Test skill isolation (each skill independently)
2. Test skill coordination (combined workflows)
3. Validate relative paths
4. User acceptance testing

## Documentation Updates
- [ ] Agent file updated with secondary skill
- [ ] AGENTS.md updated
- [ ] Agent catalog updated
- [ ] Cross-references added

## Rollout Plan
- Dev testing: {Date}
- User beta: {Date}
- Production: {Date}

Appendix B: Automation Scripts

Skill Validation Script

#!/bin/bash
# validate-skill.sh - Validate new skill structure

SKILL_PATH=$1

echo "Validating skill at: $SKILL_PATH"

# Check required files
if [ ! -f "$SKILL_PATH/SKILL.md" ]; then
  echo "❌ Missing SKILL.md"
  exit 1
fi

if [ ! -d "$SKILL_PATH/scripts" ]; then
  echo "⚠️  No scripts/ directory (optional but recommended)"
fi

if [ ! -d "$SKILL_PATH/references" ]; then
  echo "❌ Missing references/ directory"
  exit 1
fi

if [ ! -d "$SKILL_PATH/assets" ]; then
  echo "❌ Missing assets/ directory"
  exit 1
fi

# Check Python tools have --help
if [ -d "$SKILL_PATH/scripts" ]; then
  for tool in "$SKILL_PATH/scripts"/*.py; do
    if [ -f "$tool" ]; then
      python "$tool" --help > /dev/null 2>&1
      if [ $? -ne 0 ]; then
        echo "❌ Tool $(basename $tool) missing --help flag"
        exit 1
      fi
    fi
  done
fi

# Check for hardcoded paths
if grep -r "/Users/" "$SKILL_PATH" > /dev/null; then
  echo "❌ Hardcoded /Users/ paths found"
  exit 1
fi

if grep -r "C:\\" "$SKILL_PATH" > /dev/null; then
  echo "❌ Hardcoded C:\\ paths found"
  exit 1
fi

# Check markdown links
# (Requires markdown-link-check installed)
find "$SKILL_PATH" -name "*.md" -exec markdown-link-check {} \;

echo "✅ Skill validation passed"

Documentation Update Checker

#!/bin/bash
# check-docs-updated.sh - Verify all docs updated when adding skill

NEW_SKILL_NAME=$1

echo "Checking documentation updates for: $NEW_SKILL_NAME"

# Check README.md updated
if ! grep -q "$NEW_SKILL_NAME" README.md; then
  echo "❌ README.md not updated with skill"
  exit 1
fi

# Check PYTHON_TOOLS_AUDIT.md updated (if tools exist)
if [ -d "*/scripts" ]; then
  if ! grep -q "$NEW_SKILL_NAME" documentation/PYTHON_TOOLS_AUDIT.md; then
    echo "❌ PYTHON_TOOLS_AUDIT.md not updated"
    exit 1
  fi
fi

# Check domain CLAUDE.md updated
DOMAIN=$(dirname $(find . -type d -name "$NEW_SKILL_NAME"))
if [ -f "$DOMAIN/CLAUDE.md" ]; then
  if ! grep -q "$NEW_SKILL_NAME" "$DOMAIN/CLAUDE.md"; then
    echo "⚠️  Domain CLAUDE.md not updated (recommended)"
  fi
fi

echo "✅ Documentation check passed"

Document Control

Version: 1.0 Last Updated: November 7, 2025 Next Review: February 7, 2026 Owner: Development Team Approvers: Repository Maintainers

Change Log:

2025-11-07: Initial version created
[Future changes will be documented here]

This is a living document. Update quarterly or as needed when processes change.

31 KiB Raw Blame History Unescape Escape