claude-skills-reference/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Purpose

This is a comprehensive skills library for Claude AI - reusable, production-ready skill packages that bundle domain expertise, best practices, analysis tools, and strategic frameworks across marketing, executive leadership, and product development. The repository provides modular skills that teams can download and use directly in their workflows.

Current Scope: 22 production-ready skills across 4 domains:

• Marketing (1): Content creation, SEO, brand voice, social media
• C-Level Advisory (2): CEO strategic planning, CTO technical leadership
• Product Team (5): Product management, agile delivery, UX research, UI design, strategic planning
• Engineering Team (14):
  • Core Engineering (9): Architecture, frontend, backend, fullstack, QA, DevOps, SecOps, code review, security
  • AI/ML/Data (5): Data science, data engineering, ML engineering, prompt engineering, computer vision

Key Distinction: This is NOT a traditional application. It's a library of skill packages meant to be extracted and deployed by users into their own Claude workflows.

Architecture Overview

Skill Package Structure

The repository is organized by domain, with each skill following a consistent modular architecture:

claude-skills/
├── marketing-skill/
│   └── content-creator/
│       ├── SKILL.md                # Master documentation
│       ├── scripts/                # Python CLI tools
│       ├── references/             # Knowledge bases
│       └── assets/                 # User templates
├── c-level-advisor/
│   ├── ceo-advisor/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── references/
│   └── cto-advisor/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── product-team/
    ├── product-manager-toolkit/
    │   ├── SKILL.md
    │   ├── scripts/
    │   └── references/
    ├── agile-product-owner/
    │   ├── SKILL.md
    │   └── scripts/
    ├── product-strategist/
    │   ├── SKILL.md
    │   └── scripts/
    ├── ux-researcher-designer/
    │   ├── SKILL.md
    │   └── scripts/
    └── ui-design-system/
        ├── SKILL.md
        └── scripts/
└── engineering-team/
    ├── senior-architect/
    ├── senior-frontend/
    ├── senior-backend/
    ├── senior-fullstack/
    ├── senior-qa/
    ├── senior-devops/
    ├── senior-secops/
    ├── code-reviewer/
    ├── senior-security/
    ├── senior-data-scientist/
    ├── senior-data-engineer/
    ├── senior-ml-engineer/
    ├── senior-prompt-engineer/
    ├── senior-computer-vision/
    ├── README.md                      # Engineering skills overview
    ├── START_HERE.md                  # Quick start guide
    └── TEAM_STRUCTURE_GUIDE.md        # Team composition recommendations

Each skill contains:
    ├── SKILL.md                       # Master documentation
    ├── scripts/                       # 3 Python automation tools
    └── references/                    # 3 comprehensive guides

Design Philosophy: Skills are self-contained packages. Each includes executable tools (Python scripts), knowledge bases (markdown references), and user-facing templates. Teams can extract a skill folder and use it immediately.

Component Relationships

1. SKILL.md → Entry point defining workflows, referencing scripts and knowledge bases
2. scripts/ → Algorithmic analysis tools (brand voice, SEO) that process user content
3. references/ → Static knowledge bases that inform content creation (frameworks, platform guidelines)
4. assets/ → Templates that users copy and customize (content calendars, checklists)

Key Pattern: Knowledge flows from references → into SKILL.md workflows → executed via scripts → applied using templates.

Core Components

Python Analysis Scripts

Located in scripts/, these are pure algorithmic tools (no ML/LLM calls):

brand_voice_analyzer.py (185 lines):

• Analyzes text for formality, tone, perspective, readability
• Uses Flesch Reading Ease formula for readability scoring
• Outputs JSON or human-readable format
• Usage: python scripts/brand_voice_analyzer.py content.txt [json]

seo_optimizer.py (419 lines):

• Comprehensive SEO analysis: keyword density, structure, meta tags
• Calculates SEO score (0-100) with actionable recommendations
• Usage: python scripts/seo_optimizer.py article.md "primary keyword" "secondary,keywords"

Implementation Notes:

• Scripts use standard library only (except PyYAML for future features)
• Designed for CLI invocation - no server/API needed
• Process content files directly from filesystem
• Return structured data (JSON) or formatted text

Reference Knowledge Bases

Located in references/, these are expert-curated guideline documents:

• brand_guidelines.md: Voice framework with 5 personality archetypes (Expert, Friend, Innovator, Guide, Motivator)
• content_frameworks.md: 15+ content templates (blog posts, email, social, video scripts, case studies)
• social_media_optimization.md: Platform-specific best practices for LinkedIn, Twitter/X, Instagram, Facebook, TikTok

Critical Architecture Point: References are NOT code - they're knowledge bases that inform both human users and Claude when creating content. When editing, maintain structured markdown with clear sections, checklists, and examples.

Product Team Python Scripts

Located in product-team/*/scripts/, these are specialized product development tools:

rice_prioritizer.py (Product Manager Toolkit):

• RICE framework implementation: (Reach × Impact × Confidence) / Effort
• Portfolio analysis (quick wins vs big bets)
• Quarterly roadmap generation with capacity planning
• Supports CSV input/output and JSON for integrations
• Usage: python scripts/rice_prioritizer.py features.csv --capacity 20

customer_interview_analyzer.py (Product Manager Toolkit):

• NLP-based interview transcript analysis
• Extracts pain points with severity scoring
• Identifies feature requests and priorities
• Sentiment analysis and theme extraction
• Jobs-to-be-done pattern recognition
• Usage: python scripts/customer_interview_analyzer.py interview.txt [json]

user_story_generator.py (Agile Product Owner):

• INVEST-compliant user story generation
• Sprint planning with capacity allocation
• Epic breakdown into deliverable stories
• Acceptance criteria generation
• Usage: python scripts/user_story_generator.py sprint 30

okr_cascade_generator.py (Product Strategist):

• Automated OKR hierarchy: company → product → team
• Alignment scoring (vertical and horizontal)
• Strategy templates (growth, retention, revenue, innovation)
• Usage: python scripts/okr_cascade_generator.py growth

persona_generator.py (UX Researcher Designer):

• Data-driven persona creation from user research
• Demographic and psychographic profiling
• Goals, pain points, and behavior patterns
• Usage: python scripts/persona_generator.py --output json

design_token_generator.py (UI Design System):

• Complete design token system from brand color
• Generates colors, typography, spacing, shadows
• Multiple export formats: CSS, JSON, SCSS
• Responsive breakpoint calculations
• Usage: python scripts/design_token_generator.py "#0066CC" modern css

Implementation Notes:

• All scripts use standard library (minimal dependencies)
• CLI-first design for easy automation and integration
• Support both interactive and batch modes
• JSON output for tool integration (Jira, Figma, Confluence)

Engineering Team Python Scripts

Located in engineering-team/*/scripts/, these are fullstack development automation tools:

project_scaffolder.py (Fullstack Engineer):

• Production-ready project scaffolding for Next.js + GraphQL + PostgreSQL stack
• Docker Compose configuration with all services
• CI/CD pipeline setup with GitHub Actions
• Testing infrastructure (Jest, Cypress)
• TypeScript, ESLint, Prettier configuration
• Usage: python scripts/project_scaffolder.py my-project --type nextjs-graphql

code_quality_analyzer.py (Fullstack Engineer):

• Comprehensive code quality analysis and metrics
• Security vulnerability scanning
• Performance issue detection
• Test coverage assessment
• Documentation quality evaluation
• Dependency analysis and recommendations
• Usage: python scripts/code_quality_analyzer.py /path/to/project [--json]

fullstack_scaffolder.py (Fullstack Engineer):

• Rapid fullstack application generation
• Modern stack templates with Docker support
• Automated project structure and boilerplate
• Usage: python scripts/fullstack_scaffolder.py my-app --stack nextjs-graphql

Implementation Notes:

• Scripts use standard library with minimal external dependencies
• Designed for rapid project bootstrapping and quality assurance
• Support both Docker and manual deployment workflows
• Comprehensive analysis with actionable recommendations

AI/ML/Data Team Python Scripts

Located in engineering-team/senior-{data,ml,ai}*/scripts/, these are AI/ML and data infrastructure tools:

Senior Data Scientist:

• experiment_designer.py - Design A/B tests and statistical experiments
• feature_engineering_pipeline.py - Automated feature engineering
• statistical_analyzer.py - Statistical modeling and causal inference

Senior Data Engineer:

• pipeline_orchestrator.py - Build data pipelines with Airflow/Spark
• data_quality_validator.py - Data quality checks and monitoring
• etl_generator.py - Generate ETL/ELT workflows

Senior ML Engineer:

• model_deployment_pipeline.py - Deploy ML models to production
• mlops_setup_tool.py - Setup MLOps infrastructure (MLflow, monitoring)
• llm_integration_builder.py - Integrate LLMs into applications

Senior Prompt Engineer:

• prompt_optimizer.py - Optimize prompts for LLMs
• rag_system_builder.py - Build RAG (Retrieval Augmented Generation) systems
• agent_orchestrator.py - Design and orchestrate AI agents

Senior Computer Vision Engineer:

• vision_model_trainer.py - Train object detection and segmentation models
• inference_optimizer.py - Optimize vision model inference
• video_processor.py - Process and analyze video streams

Implementation Notes:

• AI/ML scripts integrate with modern frameworks (PyTorch, LangChain, OpenCV)
• Data engineering tools support Spark, Airflow, dbt, Kafka
• MLOps workflows include monitoring, versioning, and drift detection
• All tools designed for production deployment at scale

Development Commands

Running Analysis Tools

# Analyze brand voice
python marketing-skill/content-creator/scripts/brand_voice_analyzer.py content.txt

# Analyze with JSON output
python marketing-skill/content-creator/scripts/brand_voice_analyzer.py content.txt json

# SEO optimization
python marketing-skill/content-creator/scripts/seo_optimizer.py article.md "main keyword"

# SEO with secondary keywords
python marketing-skill/content-creator/scripts/seo_optimizer.py article.md "main keyword" "secondary,keywords"

# Product Manager - RICE prioritization
python product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv
python product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 --output json

# Product Manager - Interview analysis
python product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt
python product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt json

# Product Owner - User stories
python product-team/agile-product-owner/scripts/user_story_generator.py
python product-team/agile-product-owner/scripts/user_story_generator.py sprint 30

# Product Strategist - OKR cascade
python product-team/product-strategist/scripts/okr_cascade_generator.py growth
python product-team/product-strategist/scripts/okr_cascade_generator.py retention

# UX Researcher - Personas
python product-team/ux-researcher-designer/scripts/persona_generator.py
python product-team/ux-researcher-designer/scripts/persona_generator.py --output json

# UI Designer - Design tokens
python product-team/ui-design-system/scripts/design_token_generator.py "#0066CC" modern css
python product-team/ui-design-system/scripts/design_token_generator.py "#0066CC" modern json

# Fullstack Engineer - Project scaffolding
python engineering-team/fullstack-engineer/scripts/project_scaffolder.py my-project --type nextjs-graphql
cd my-project && docker-compose up -d

# Fullstack Engineer - Code quality
python engineering-team/fullstack-engineer/scripts/code_quality_analyzer.py /path/to/project
python engineering-team/fullstack-engineer/scripts/code_quality_analyzer.py /path/to/project --json

# Fullstack Engineer - Rapid scaffolding
python engineering-team/fullstack-engineer/scripts/fullstack_scaffolder.py my-app --stack nextjs-graphql

Development Environment

No build system, package managers, or test frameworks currently exist. This is intentional - skills are designed to be lightweight and dependency-free.

If adding dependencies:

• Keep scripts runnable with minimal setup (pip install package at most)
• Document all dependencies in SKILL.md
• Prefer standard library implementations over external packages

Working with Skills

Creating New Skills

Follow the appropriate roadmap for your skill domain. When adding a new skill:

For Marketing Skills:

1. Create skill folder: marketing-skill/{skill-name}/
2. Copy structure from content-creator/ as template
3. Follow roadmap in marketing-skill/marketing_skills_roadmap.md

For C-Level Advisory Skills:

1. Create skill folder: c-level-advisor/{role}-advisor/
2. Copy structure from ceo-advisor/ or cto-advisor/
3. Focus on strategic decision-making tools

For Product Team Skills:

1. Create skill folder: product-team/{skill-name}/
2. Copy structure from product-manager-toolkit/ as template
3. Follow guide in product-team/product_team_implementation_guide.md

For Engineering Team Skills:

1. Create skill folder: engineering-team/{skill-name}/
2. Copy structure from fullstack-engineer/ as template
3. Follow guide in engineering-team/engineering_skills_roadmap.md

Universal Process:

1. Write SKILL.md first (defines workflows before building tools)
2. Build Python scripts if algorithmic analysis is needed
3. Curate reference knowledge bases (frameworks, templates)
4. Create user-facing templates and examples
5. Package as .zip for distribution

Quality Standard: Each skill should save users 40%+ time while improving consistency/quality by 30%+.

Editing Existing Skills

SKILL.md: This is the master document users read first. Changes here impact user workflows directly.

Scripts: Pure logic implementation. No LLM calls, no external APIs (keeps skills portable and fast).

References: Expert knowledge curation. Focus on actionable checklists, specific metrics, and platform-specific details.

Critical: Maintain consistency across all markdown files. Use the same voice, formatting, and structure patterns established in content-creator.

Git Workflow

The repository follows a domain-based branching strategy. Recommended workflow:

# Feature branches by domain
git checkout -b feature/marketing/seo-optimizer
git checkout -b feature/product/ux-research-tools
git checkout -b feature/c-level/cfo-advisor

# Semantic versioning by skill
git tag v1.0-content-creator
git tag v1.0-product-manager-toolkit
git tag v1.0-ceo-advisor

# Commit message conventions
feat(content-creator): add LinkedIn content framework
feat(product-manager): add RICE prioritization script
fix(agile-product-owner): correct sprint capacity calculation
docs(ux-researcher): update persona generation guide
refactor(ui-design-system): improve token generator performance

Current State:

• 22 skills deployed across 4 domains
• 58 Python automation tools
• All skills v1.0 production-ready
• Complete engineering suite with 14 specialized roles (9 core + 5 AI/ML/Data)

.gitignore excludes: .vscode/, .DS_Store, AGENTS.md, PROMPTS.md, .env* (CLAUDE.md is tracked as living documentation)

Roadmap Context

Current Status: Phase 1 Complete - 22 production-ready skills deployed

Delivered Skills:

• Marketing (1): content-creator
• C-Level Advisory (2): ceo-advisor, cto-advisor
• Product Team (5): product-manager-toolkit, agile-product-owner, product-strategist, ux-researcher-designer, ui-design-system
• Engineering Team (14):
  • Core Engineering (9): senior-architect, senior-frontend, senior-backend, senior-fullstack, senior-qa, senior-devops, senior-secops, code-reviewer, senior-security
  • AI/ML/Data (5): senior-data-scientist, senior-data-engineer, senior-ml-engineer, senior-prompt-engineer, senior-computer-vision

Total Automation:

• 58 Python automation tools (22 skills × 2.6 avg tools per skill)
• 60+ comprehensive reference guides with patterns and best practices
• Complete development lifecycle coverage from architecture through AI/ML deployment

Next Priorities:

• Phase 2 (Q1 2026): Marketing expansion - SEO optimizer, social media manager, campaign analytics
• Phase 3 (Q2 2026): Business & growth - Sales engineer, customer success, growth marketer
• Phase 4 (Q3 2026): Specialized domains - Mobile-specific, blockchain, web3

Target: 30+ skills by Q3 2026

See detailed roadmaps:

• marketing-skill/marketing_skills_roadmap.md
• product-team/product_team_implementation_guide.md
• engineering-team/engineering_skills_roadmap.md

Key Principles

1. Skills are products: Each skill should be deployable as a standalone package
2. Documentation-driven: Success depends on clear, actionable documentation
3. Algorithm over AI: Use deterministic analysis (code) rather than LLM calls when possible
4. Template-heavy: Provide ready-to-use templates users can customize
5. Platform-specific: Generic advice is less valuable than specific platform best practices

Anti-Patterns to Avoid

• Creating dependencies between skills (keep each self-contained)
• Adding complex build systems or test frameworks (maintain simplicity)
• Generic marketing advice (focus on specific, actionable frameworks)
• LLM calls in scripts (defeats the purpose of portable, fast analysis tools)
• Over-documenting file structure (skills are simple by design)