firefrost-gaming/claude-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
claude-skills-reference/documentation/implementation/implementation-plan-november-2025.md

22 KiB
Raw Permalink Blame History

Claude Skills - Skill-Agent Integration Implementation Plan

Version: 1.0 Created: November 5, 2025 Status: In Progress Milestone: Skill-Agent Integration v1.0

Executive Summary

This plan outlines the integration of specialized agents (cs-* prefix) with the existing 42 production-ready skills in the claude-code-skills repository. The implementation creates a seamless workflow where users can invoke domain-specific agents that automatically discover and execute the appropriate Python tools and reference knowledge bases.

Key Objectives:

  • Create 5 foundational agents covering marketing, C-level advisory, and product management
  • Implement simple installation system via interactive script
  • Maintain 100% backwards compatibility with existing skill structure
  • Prepare foundation for future Anthropic plugin marketplace distribution

Timeline: Days 1-4 (Phase 1-2) Future Work: Days 5-10 (Phase 3-7, including plugin creation)

Architecture Overview

Directory Structure

claude-code-skills/
├── agents/                    # cs-* prefixed agents (NEW)
│   ├── marketing/
│   │   ├── cs-content-creator.md
│   │   └── cs-demand-gen-specialist.md
│   ├── c-level/
│   │   ├── cs-ceo-advisor.md
│   │   └── cs-cto-advisor.md
│   └── product/
│       └── cs-product-manager.md
├── commands/                  # Slash commands (NEW)
├── standards/                 # Standards library (NEW)
│   ├── communication/
│   ├── quality/
│   ├── git/
│   ├── documentation/
│   └── security/
├── templates/                 # Templates (NEW)
├── marketing-skill/          # EXISTING - unchanged
├── c-level-advisor/          # EXISTING - unchanged
├── product-team/             # EXISTING - unchanged
├── project-management/       # EXISTING - unchanged
├── engineering-team/         # EXISTING - unchanged
├── ra-qm-team/               # EXISTING - unchanged
├── install.sh                # Installation script (FUTURE)
├── uninstall.sh              # Cleanup script (FUTURE)
├── INSTALL.md                # Installation guide (FUTURE)
├── USAGE.md                  # Usage examples (FUTURE)
├── .claude/                  # Dev-only workflows
└── .github/                  # GitHub automation

Design Principles

  1. Non-invasive: Agents reference existing skills via relative paths
  2. Zero conflicts: cs-* prefix prevents collision with user's existing agents
  3. Backwards compatible: Existing skill folders remain untouched
  4. Plugin-ready: Structure designed for future marketplace distribution
  5. Simple installation: Single script with 3 Q&A questions (Phase 3)

Phase 1: Core Structure Setup (Day 1)

1.1 Create Root-Level Directories

Task: Set up foundational directory structure Owner: Implementation team Estimated Time: 30 minutes

Directories to create:

mkdir -p agents/marketing
mkdir -p agents/c-level
mkdir -p agents/product
mkdir -p commands
mkdir -p standards/communication
mkdir -p standards/quality
mkdir -p standards/git
mkdir -p standards/documentation
mkdir -p standards/security
mkdir -p templates

Success Criteria:

  • All directories created in repository root
  • Directory structure matches architecture diagram
  • No conflicts with existing folders

GitHub Issue: #[TBD] - Create root-level directory structure

1.2 Port Core Standards from Factory

Task: Copy and adapt 5 essential standards from claude-code-skills-factory Owner: Documentation team Estimated Time: 2 hours

Standards to port:

  1. communication-standards.md → standards/communication/

    • Absolute honesty, zero fluff, pragmatic focus
    • Critical analysis requirements
    • Response protocol
    • Prohibited responses

  2. quality-standards.md → standards/quality/

    • Code quality requirements
    • Testing standards
    • Review checklist

  3. git-workflow-standards.md → standards/git/

    • Conventional commits
    • Branch naming
    • PR requirements
    • Commit message templates

  4. documentation-standards.md → standards/documentation/

    • Markdown formatting
    • File naming conventions
    • Structure requirements
    • Living documentation principles

  5. security-standards.md → standards/security/

    • Secret detection
    • Dependency scanning
    • Security checklist
    • Vulnerability reporting

Adaptation Notes:

  • Replace factory-specific references with claude-skills context
  • Update file paths to match new structure
  • Reference existing skills (not rr-* agents)
  • Maintain standard library focus (no external dependencies)

Success Criteria:

  • All 5 standards files created and validated
  • No broken links or factory-specific references
  • Standards reference claude-skills architecture
  • Files pass markdown linting

GitHub Issue: #[TBD] - Port core standards from factory

Phase 2: Agent Implementation (Days 2-4)

2.1 Create Marketing Agents (Day 2)

Task: Implement 2 marketing domain agents Owner: Marketing team Estimated Time: 4 hours

Agent 1: cs-content-creator

File: agents/marketing/cs-content-creator.md

Structure:

---
name: cs-content-creator
description: Create SEO-optimized marketing content with brand voice consistency
skills: content-creator
domain: marketing
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---

# Content Creator Agent

## Purpose
Specialized agent for creating high-quality marketing content across multiple formats (blog posts, social media, email campaigns, video scripts). Integrates brand voice analysis, SEO optimization, and platform-specific best practices.

## Skill Integration

**Skill Location:** `../../marketing-skill/content-creator/`

### Python Tools

**Brand Voice Analyzer:**
```bash
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt json

SEO Optimizer:

python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "primary keyword"
python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "primary keyword" "secondary,keywords"

Knowledge Bases

  • Brand Guidelines: ../../marketing-skill/content-creator/references/brand_guidelines.md
  • Content Frameworks: ../../marketing-skill/content-creator/references/content_frameworks.md
  • Social Media Optimization: ../../marketing-skill/content-creator/references/social_media_optimization.md

Templates

  • Content Calendar: ../../marketing-skill/content-creator/assets/content-calendar-template.md
  • Brand Voice Checklist: ../../marketing-skill/content-creator/assets/brand-voice-checklist.md

Workflows

Workflow 1: Create Blog Post

  1. Read brief from user
  2. Analyze existing brand voice samples using brand_voice_analyzer.py
  3. Reference content_frameworks.md for blog post structure
  4. Draft content following brand guidelines
  5. Run SEO analysis using seo_optimizer.py
  6. Refine based on SEO recommendations
  7. Output final content + SEO report

Workflow 2: Create Social Media Campaign

  1. Identify target platforms
  2. Reference social_media_optimization.md for platform best practices
  3. Draft platform-specific content (character limits, hashtags, CTAs)
  4. Validate brand voice consistency
  5. Generate content calendar using template

Workflow 3: Analyze Brand Voice

  1. Collect content samples from user
  2. Run brand_voice_analyzer.py on each sample
  3. Aggregate results to identify patterns
  4. Map to personality archetype (Expert, Friend, Innovator, Guide, Motivator)
  5. Create brand voice profile document

Integration Examples

Example 1: Blog post with SEO

# User provides brief
# Agent drafts article as draft.md
python ../../marketing-skill/content-creator/scripts/seo_optimizer.py draft.md "content marketing"

# Review SEO score and recommendations
# Refine draft based on suggestions
# Final output: optimized article

Example 2: Brand voice audit

# User provides 3 content samples
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py sample1.txt json > voice1.json
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py sample2.txt json > voice2.json
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py sample3.txt json > voice3.json

# Agent analyzes JSON outputs
# Identifies consistency patterns
# Recommends brand voice archetype

Success Metrics

  • Content creation time reduced by 40%
  • SEO scores improved by 30%+ on average
  • Brand voice consistency across all outputs
  • Platform-specific best practices followed

Related Agents

  • cs-demand-gen-specialist (acquisition campaigns)
  • cs-product-marketing (product launches)

References

  • Skill Documentation: ../../marketing-skill/content-creator/SKILL.md
  • Standards: ../../standards/communication/communication-standards.md

#### Agent 2: cs-demand-gen-specialist

**File:** `agents/marketing/cs-demand-gen-specialist.md`

**Structure:** (Similar YAML frontmatter + content structure)
- Integrates with `../../marketing-skill/marketing-demand-acquisition/`
- Python tool: campaign_analyzer.py
- Workflows: Lead gen campaigns, conversion optimization, funnel analysis

**Success Criteria:**
- Both agents created with complete YAML frontmatter
- All relative paths validated (../../ references work)
- Python tool invocation examples tested
- Workflow sections comprehensive
- No broken links

**GitHub Issue:** #[TBD] - Create marketing agents (cs-content-creator, cs-demand-gen-specialist)

---

### 2.2 Create C-Level Advisory Agents (Day 3)

**Task:** Implement 2 C-level advisory agents
**Owner:** Strategy team
**Estimated Time:** 4 hours

#### Agent 3: cs-ceo-advisor

**File:** `agents/c-level/cs-ceo-advisor.md`

**Integration Points:**
- Skill: `../../c-level-advisor/ceo-advisor/`
- Python tools: strategic_framework_generator.py, scenario_planner.py, okr_tracker.py
- Knowledge bases: Strategic frameworks, decision templates, board reporting

**Workflows:**
- Strategic planning (3-year vision)
- Quarterly OKR setting
- Board deck preparation
- Scenario analysis (market shifts, competition)

#### Agent 4: cs-cto-advisor

**File:** `agents/c-level/cs-cto-advisor.md`

**Integration Points:**
- Skill: `../../c-level-advisor/cto-advisor/`
- Python tools: tech_stack_analyzer.py, architecture_auditor.py, team_velocity_tracker.py
- Knowledge bases: Tech stack decisions, architecture patterns, engineering metrics

**Workflows:**
- Technology roadmap planning
- Build vs buy analysis
- Technical debt assessment
- Engineering team scaling

**Success Criteria:**
- Both C-level agents created
- Strategic frameworks integrated
- Python tools documented with examples
- Workflow sections cover executive use cases
- References to CEO/CTO skill packages working

**GitHub Issue:** #[TBD] - Create C-level agents (cs-ceo-advisor, cs-cto-advisor)

---

### 2.3 Create Product Management Agent (Day 4)

**Task:** Implement product management agent
**Owner:** Product team
**Estimated Time:** 3 hours

#### Agent 5: cs-product-manager

**File:** `agents/product/cs-product-manager.md`

**Integration Points:**
- Skill: `../../product-team/product-manager-toolkit/`
- Python tools: rice_prioritizer.py, customer_interview_analyzer.py
- Knowledge bases: Product frameworks, roadmap templates, prioritization methods

**Workflows:**
- Feature prioritization (RICE framework)
- Customer interview analysis
- Product roadmap generation
- Quarterly planning

**Example Integration:**
```bash
# User uploads features.csv
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 --output json

# Agent analyzes RICE scores
# Categorizes: Quick Wins, Big Bets, Maybes, Time Sinks
# Generates quarterly roadmap

Success Criteria:

  • Product manager agent created
  • RICE prioritization workflow functional
  • Interview analysis integrated
  • Roadmap generation examples documented

GitHub Issue: #[TBD] - Create product agent (cs-product-manager)

2.4 Create Agent Structure Template & Documentation (Day 4)

Task: Standardize agent creation process Owner: Documentation team Estimated Time: 2 hours

Deliverables:

  1. Agent Template: templates/agent-template.md

    • YAML frontmatter structure
    • Required sections (Purpose, Skill Integration, Workflows, Success Metrics)
    • Python tool invocation patterns
    • Knowledge base reference format
    • Related agents linking

  2. Agent Creation Guide: documentation/AGENT_CREATION_GUIDE.md

    • Step-by-step process
    • Naming conventions (cs-* prefix)
    • Relative path resolution
    • Testing checklist
    • Integration validation

Success Criteria:

  • Template covers all required agent sections
  • Creation guide is actionable (developers can create new agents)
  • Examples from cs-content-creator referenced
  • Template passes validation

GitHub Issue: #[TBD] - Create agent structure template and documentation

Future Phases (Days 5-10)

Phase 3: Installation System (Day 5)

  • Create install.sh with 3 Q&A questions
  • Create uninstall.sh
  • Implement backwards compatibility detection

Phase 4: Documentation (Day 6)

  • Update README.md with agent catalog
  • Create INSTALL.md
  • Create USAGE.md
  • Update CLAUDE.md

Phase 5: Testing & Quality (Day 7)

  • Validate YAML frontmatter
  • Test relative path resolution
  • Verify Python tool invocation
  • Run quality gates

Phase 6-7: Plugin Creation (Days 8-10)

  • Research Anthropic marketplace requirements
  • Design plugin.yaml manifest
  • Create plugin package structure
  • Prepare submission assets (icon, screenshots, description)
  • Submit to marketplace

Success Criteria

Phase 1-2 Completion Checklist

  • All 4 root directories created (agents/, commands/, standards/, templates/)
  • 5 core standards ported and validated
  • 5 agents implemented and tested:
    • cs-content-creator
    • cs-demand-gen-specialist
    • cs-ceo-advisor
    • cs-cto-advisor
    • cs-product-manager
  • All relative paths (../../) resolve correctly
  • Python tools execute successfully from agents
  • Agent template created
  • Documentation updated
  • All tasks tracked in GitHub issues
  • Issues linked to Milestone "Skill-Agent Integration v1.0"
  • Issues synced to Project #9 board

Quality Gates

  1. File Structure:

    • All files use kebab-case naming
    • Markdown files pass linting
    • YAML frontmatter validates

  2. Path Resolution:

    • All ../../ relative paths work
    • Python scripts execute from agent context
    • Knowledge bases load correctly

  3. Documentation:

    • No broken links
    • All examples tested
    • Workflow sections complete

  4. Integration:

    • Agents discover skills automatically
    • Python tools execute with correct paths
    • Templates load successfully

Risk Mitigation

Risk 1: Relative path resolution fails

  • Probability: Medium
  • Impact: High
  • Mitigation: Test all paths in isolation before committing
  • Fallback: Use absolute paths with environment variable

Risk 2: Agent naming conflicts with user's existing setup

  • Probability: Low (cs-* prefix chosen to avoid conflicts)
  • Impact: Medium
  • Mitigation: Clear documentation, namespace everything
  • Fallback: Allow users to customize prefix during installation

Risk 3: GitHub automation workflow issues

  • Probability: Low (workflows already implemented and tested)
  • Impact: Low
  • Mitigation: Test issues creation before full rollout
  • Fallback: Manual issue creation

Risk 4: Standards not applicable to all skills

  • Probability: Medium
  • Impact: Low
  • Mitigation: Keep standards general, allow skill-specific overrides
  • Fallback: Document exceptions in standards files

GitHub Issues Breakdown

Phase 1 Issues (Day 1)

Issue 1: Create root-level directory structure

  • Labels: type:enhancement, domain:agents, priority:high
  • Milestone: Skill-Agent Integration v1.0
  • Checklist:
    • Create agents/ with subdirectories (marketing/, c-level/, product/)
    • Create commands/
    • Create standards/ with subdirectories
    • Create templates/
    • Verify no conflicts with existing structure
    • Update .gitignore if needed

Issue 2: Port core standards from factory

  • Labels: type:enhancement, domain:documentation, priority:high
  • Milestone: Skill-Agent Integration v1.0
  • Checklist:
    • Port communication-standards.md
    • Port quality-standards.md
    • Port git-workflow-standards.md
    • Port documentation-standards.md
    • Port security-standards.md
    • Adapt all references to claude-skills context
    • Validate markdown linting passes

Phase 2 Issues (Days 2-4)

Issue 3: Create marketing agents

  • Labels: type:enhancement, domain:agents, domain:marketing, priority:high
  • Milestone: Skill-Agent Integration v1.0
  • Checklist:
    • Create cs-content-creator.md with full structure
    • Create cs-demand-gen-specialist.md
    • Test relative paths to marketing-skill/
    • Validate Python tool invocation
    • Document workflows
    • Add integration examples

Issue 4: Create C-level agents

  • Labels: type:enhancement, domain:agents, priority:high
  • Milestone: Skill-Agent Integration v1.0
  • Checklist:
    • Create cs-ceo-advisor.md
    • Create cs-cto-advisor.md
    • Test relative paths to c-level-advisor/
    • Validate Python tool invocation
    • Document strategic workflows
    • Add executive use case examples

Issue 5: Create product agent

  • Labels: type:enhancement, domain:agents, domain:product, priority:high
  • Milestone: Skill-Agent Integration v1.0
  • Checklist:
    • Create cs-product-manager.md
    • Test relative paths to product-team/
    • Validate RICE prioritizer integration
    • Validate interview analyzer integration
    • Document roadmap workflows

Issue 6: Create agent structure template

  • Labels: type:documentation, domain:templates, priority:medium
  • Milestone: Skill-Agent Integration v1.0
  • Checklist:
    • Create templates/agent-template.md
    • Create documentation/AGENT_CREATION_GUIDE.md
    • Document YAML frontmatter requirements
    • Document workflow section structure
    • Add validation checklist

Metrics & KPIs

Implementation Metrics

  • Time to complete Phase 1-2: 4 days (target)
  • Number of agents created: 5
  • Standards ported: 5
  • GitHub issues created: 6-8
  • Code review cycles: 1-2 per agent

Quality Metrics

  • Path resolution success rate: 100%
  • Python tool execution success rate: 100%
  • Documentation coverage: 100% (all agents fully documented)
  • Markdown linting pass rate: 100%

User Experience Metrics (Post Phase 3)

  • Time to install: <5 minutes
  • Agent discovery time: <1 minute
  • Skill execution time: Same as direct Python invocation
  • User satisfaction: TBD (collect feedback)

Next Steps After Phase 1-2

  1. Phase 3 Planning: Create detailed plan for installation system
  2. Community Feedback: Share Phase 1-2 implementation for early feedback
  3. Agent Expansion: Plan remaining 37 agents (project management, engineering, RA/QM)
  4. Plugin Research: Deep dive into Anthropic marketplace requirements
  5. Integration Testing: Comprehensive testing with real user workflows

Appendix A: Agent Naming Convention

Format: cs-{domain}-{role}

Examples:

  • cs-content-creator (marketing domain)
  • cs-demand-gen-specialist (marketing domain)
  • cs-ceo-advisor (c-level domain)
  • cs-product-manager (product domain)

Rules:

  • Always use cs- prefix (claude-skills)
  • Use kebab-case for multi-word roles
  • Keep names concise (<30 characters)
  • Match corresponding skill folder name when possible

Appendix B: Directory Tree (Complete)

claude-code-skills/
├── .claude/
│   └── commands/              # Development commands (git/, review.md, etc.)
├── .github/
│   ├── workflows/             # CI/CD automation
│   ├── AUTOMATION_SETUP.md
│   └── pull_request_template.md
├── agents/                    # NEW: cs-* agents
│   ├── marketing/
│   │   ├── cs-content-creator.md
│   │   └── cs-demand-gen-specialist.md
│   ├── c-level/
│   │   ├── cs-ceo-advisor.md
│   │   └── cs-cto-advisor.md
│   └── product/
│       └── cs-product-manager.md
├── commands/                  # NEW: User slash commands
├── standards/                 # NEW: Standards library
│   ├── communication/
│   │   └── communication-standards.md
│   ├── quality/
│   │   └── quality-standards.md
│   ├── git/
│   │   └── git-workflow-standards.md
│   ├── documentation/
│   │   └── documentation-standards.md
│   └── security/
│       └── security-standards.md
├── templates/                 # NEW: Templates
│   └── agent-template.md
├── documentation/
│   ├── implementation/
│   │   └── implementation-plan-november-2025.md  # THIS FILE
│   ├── GIST_CONTENT.md
│   └── PYTHON_TOOLS_AUDIT.md
├── marketing-skill/          # EXISTING
├── c-level-advisor/          # EXISTING
├── product-team/             # EXISTING
├── project-management/       # EXISTING
├── engineering-team/         # EXISTING
├── ra-qm-team/               # EXISTING
├── CLAUDE.md
├── README.md
├── LICENSE
└── .gitignore

Document History

  • v1.0 (2025-11-05): Initial implementation plan created for Phase 1-2
  • Future versions will document Phase 3-7 planning and execution

End of Implementation Plan

Reference in New Issue View Git Blame Copy Permalink