Brand Analyzer

Overview

This skill enables comprehensive brand analysis and guidelines creation. It analyzes brand requirements, identifies brand personality and positioning, and generates professional brand guidelines documents. The skill uses established brand frameworks including Jung's 12 archetypes and industry-standard brand identity principles.

When to Use This Skill

Use this skill when the user requests:

• Brand analysis or brand audit
• Creation of brand guidelines or brand standards
• Brand identity development or refinement
• Brand consistency evaluation
• Brand positioning and differentiation analysis
• Brand archetype identification
• Recommendations for brand improvements
• Documentation of existing brand elements

Core Workflow

Step 1: Determine Analysis Type

Identify what type of brand work is needed:

A. New Brand Development

• Starting from scratch or rebranding
• Requires comprehensive brand identity creation
• Output: Complete brand guidelines document

B. Existing Brand Analysis

• Analyzing current brand state
• Identifying inconsistencies and gaps
• Output: Brand analysis report with recommendations

C. Quick Brand Audit

• Fast assessment of brand health
• Checking for consistency issues
• Output: Quick audit checklist with scores

D. Brand Guidelines Creation

• Documenting existing brand elements
• Formalizing standards and rules
• Output: Professional brand guidelines

Step 2: Gather Brand Information

Collect relevant information based on analysis type. Use the questions from references/brand_analysis_framework.md as a guide.

Essential Information:

• Brand name and tagline
• Mission and vision statements
• Core values
• Target audience details
• Industry and competitive context
• Existing brand materials (if any)

Visual Identity Information:

• Logo and variations
• Color palette (with codes)
• Typography (font families)
• Imagery style preferences
• Design elements

Voice and Messaging:

• Brand personality traits
• Tone of voice
• Key messages
• Value proposition
• Language preferences

Additional Context:

• Brand history and evolution
• Customer perception
• Competitive positioning
• Business goals
• Brand touchpoints

Step 3: Analyze Brand Archetype

Identify the brand's personality using the 12 archetypes framework from references/brand_archetypes.md.

Analysis Process:

1. Review brand's core desire and goals
2. Assess personality traits and values
3. Consider target audience aspirations
4. Evaluate competitive positioning
5. Identify primary archetype (60-70% influence)
6. Identify secondary archetype (30-40% influence)

Archetypes Quick Reference:

• Innocent: Happiness, optimism, simplicity
• Sage: Knowledge, wisdom, expertise
• Explorer: Freedom, adventure, discovery
• Outlaw: Rebellion, disruption, change
• Magician: Transformation, vision, innovation
• Hero: Courage, achievement, mastery
• Lover: Passion, intimacy, beauty
• Jester: Fun, humor, enjoyment
• Everyman: Belonging, authenticity, relatability
• Caregiver: Nurturing, protection, support
• Ruler: Control, leadership, success
• Creator: Innovation, imagination, artistic expression

Load references/brand_archetypes.md for detailed characteristics, visual directions, and messaging patterns for each archetype.

Step 4: Conduct Brand Analysis

Perform comprehensive analysis using the framework from references/brand_analysis_framework.md.

Key Analysis Areas:

1. Brand Identity

• Mission/vision clarity and alignment
• Values authenticity and consistency
• Personality definition and expression
• Archetype fit and application

2. Visual Identity

• Logo effectiveness and variations
• Color palette appropriateness and accessibility
• Typography hierarchy and readability
• Imagery style consistency
• Overall visual coherence

3. Voice and Messaging

• Voice consistency across channels
• Tone adaptation for contexts
• Message clarity and relevance
• Language effectiveness
• Value proposition strength

4. Target Audience Alignment

• Audience definition completeness
• Brand-audience fit
• Messaging resonance
• Visual appeal to audience
• Problem-solution alignment

5. Market Position

• Competitive differentiation
• Unique value proposition
• Market positioning clarity
• Brand promise delivery

6. Brand Consistency

• Cross-channel consistency
• Touchpoint alignment
• Quality standards maintenance
• Experience coherence

Step 5: Generate Output Document

Create the appropriate deliverable based on analysis type using templates from assets/.

Output Options:

A. Brand Guidelines Document (assets/brand_guidelines_template.md)

• Complete, professional brand guidelines
• Includes all identity elements
• Usage rules and examples
• Application across channels
• Resource section

B. Brand Analysis Report (assets/brand_analysis_report_template.md)

• Comprehensive analysis findings
• Strengths and opportunities
• Competitive positioning
• Recommendations and roadmap
• Success metrics

C. Quick Brand Audit (assets/quick_brand_audit_template.md)

• Rapid assessment checklist
• Health scores by category
• Priority action items
• Consistency check across channels

File Naming Convention:

• Guidelines: brand-guidelines-BRANDNAME-YYYY-MM-DD.md
• Analysis: brand-analysis-BRANDNAME-YYYY-MM-DD.md
• Audit: brand-audit-BRANDNAME-YYYY-MM-DD.md

Storage Location: Create in project root or in brand-documents/ directory if multiple documents.

Step 6: Provide Recommendations

Based on analysis, provide actionable recommendations:

Prioritization Framework:

• High Impact + Low Effort: Quick wins - do immediately
• High Impact + High Effort: Strategic initiatives - plan carefully
• Low Impact + Low Effort: Nice-to-haves - do when possible
• Low Impact + High Effort: Avoid - not worth resources

Recommendation Categories:

1. Visual Identity Improvements: Logo refinements, color adjustments, typography updates
2. Voice and Messaging: Tone consistency, message clarification, language refinement
3. Documentation: Creating or updating guidelines, standards documentation
4. Consistency: Fixing inconsistencies across touchpoints
5. Strategic: Repositioning, rebranding, major initiatives

Step 7: Create Implementation Roadmap

Provide phased approach for implementing recommendations:

Phase 1: Immediate (0-30 days)

• Critical fixes
• Quick wins
• Documentation updates
• High-priority inconsistencies

Phase 2: Short-term (1-3 months)

• Medium-priority improvements
• Guideline development
• Team training
• Channel optimization

Phase 3: Long-term (3-6+ months)

• Strategic initiatives
• Major redesigns
• Comprehensive rollouts
• Measurement and refinement

Advanced Features

Competitive Brand Analysis

When comparing to competitors:

1. Identify 3-5 key competitors
2. Analyze their positioning and differentiation
3. Map brand attributes on positioning matrix
4. Identify gaps and opportunities
5. Recommend differentiation strategy

Brand Health Scoring

Provide quantitative assessments:

• Visual Identity: Logo, colors, typography coherence
• Brand Foundation: Mission, values, personality clarity
• Voice & Messaging: Consistency and effectiveness
• Consistency: Cross-channel alignment
• Audience Alignment: Target fit and appeal
• Differentiation: Competitive uniqueness
• Documentation: Guidelines completeness

Scale: 1-10 for each category, with overall average.

Multi-Channel Audit

Assess brand consistency across touchpoints:

• Website
• Social media (platform-specific)
• Email communications
• Print materials
• Packaging
• Signage and environmental
• Customer service
• Product/service delivery

Usage Examples

Example 1: New Brand Guidelines

User Request: "Create comprehensive brand guidelines for our eco-friendly packaging startup called GreenWrap."

Execution:

1. Ask discovery questions about mission, values, target audience
2. Gather visual identity details (colors, fonts, logo variations)
3. Identify brand archetype (likely Explorer or Caregiver)
4. Reference references/brand_analysis_framework.md for structure
5. Use assets/brand_guidelines_template.md as base
6. Fill in all sections with specific details
7. Save as brand-guidelines-greenwrap-2025-03-15.md
8. Provide implementation recommendations

Example 2: Brand Audit

User Request: "Audit our existing brand for consistency issues."

Execution:

1. Request access to brand materials across channels
2. Use references/brand_analysis_framework.md audit checklist
3. Assess each brand element category
4. Score consistency across touchpoints
5. Identify gaps and inconsistencies
6. Use assets/quick_brand_audit_template.md
7. Complete all checklist items with findings
8. Provide prioritized action items
9. Save as brand-audit-[name]-[date].md

Example 3: Brand Analysis with Recommendations

User Request: "Analyze our tech startup brand and suggest improvements."

Execution:

1. Gather current brand information
2. Load references/brand_archetypes.md to identify archetype
3. Use references/brand_analysis_framework.md for analysis structure
4. Evaluate all brand elements (visual, voice, positioning)
5. Assess competitive differentiation
6. Identify strengths and opportunities
7. Use assets/brand_analysis_report_template.md
8. Complete comprehensive report with scores
9. Provide implementation roadmap
10. Save as brand-analysis-[name]-[date].md

Reference Files

This skill includes detailed reference documentation:

references/brand_analysis_framework.md

Comprehensive framework covering:

• Core brand elements (identity, visual, voice, audience, position)
• Discovery and analysis questions
• Brand consistency checkpoints
• Guideline categories and structure
• Audit checklists
• Output frameworks

When to load: For any brand analysis or guidelines creation to ensure comprehensive coverage.

references/brand_archetypes.md

Complete guide to Jung's 12 brand archetypes:

• Detailed descriptions of each archetype
• Core desires, goals, and strategies
• Voice and visual characteristics
• Example brands for each type
• How to identify and apply archetypes
• Mixed archetype strategies

When to load: When identifying brand personality or determining visual/voice direction.

Asset Templates

This skill includes three professional templates in assets/:

brand_guidelines_template.md

Complete brand guidelines document template with sections for:

• Brand story and foundation
• Visual identity (logo, colors, typography, imagery)
• Voice and messaging
• Brand applications (digital, print, environmental)
• Usage examples and checklist

brand_analysis_report_template.md

Comprehensive analysis report template covering:

• Executive summary and key findings
• Detailed analysis of all brand elements
• Competitive positioning
• Touchpoint audit
• Strengths and opportunities
• Implementation roadmap with phases
• Success metrics

quick_brand_audit_template.md

Rapid assessment checklist including:

• Visual identity verification
• Brand foundation check
• Voice and messaging evaluation
• Consistency across channels
• Audience alignment assessment
• Competitive position review
• Health scores and priority actions

Best Practices

Discovery Phase

• Ask open-ended questions to understand brand deeply
• Review all existing materials before making recommendations
• Understand business goals and how brand supports them
• Consider customer perspective and perception

Analysis Phase

• Use both references files for comprehensive framework
• Be objective in assessments - identify both strengths and gaps
• Provide specific examples when noting issues
• Consider industry context and competitive landscape

Documentation Phase

• Use clear, actionable language
• Include specific measurements and standards
• Provide both good and bad examples
• Make guidelines accessible and easy to follow

Recommendation Phase

• Prioritize based on impact and effort
• Provide rationale for each recommendation
• Include estimated timelines and resources
• Connect recommendations to business goals

Follow-up

• Suggest regular brand audits (quarterly or bi-annually)
• Recommend brand guideline updates as brand evolves
• Provide guidance on implementing changes
• Offer to create supporting materials

Common Scenarios

Scenario 1: Inconsistent Brand

Symptoms: Different colors/fonts across channels, unclear messaging Approach: Quick audit → Identify inconsistencies → Prioritize fixes → Create guidelines Output: Quick audit + Brand guidelines document

Scenario 2: Undefined Brand

Symptoms: No clear values, personality, or visual standards Approach: Discovery → Define all elements → Document in guidelines Output: Complete brand guidelines document

Scenario 3: Rebranding

Symptoms: Old brand doesn't fit current direction Approach: Full analysis → Competitive positioning → New identity development Output: Brand analysis report + New brand guidelines

Scenario 4: Brand Expansion

Symptoms: Entering new market or launching new product line Approach: Review core brand → Adapt for new context → Extension guidelines Output: Brand guidelines with extension sections

Tips for Effective Brand Analysis

1. Start with Why: Understanding purpose drives better brand decisions
2. Think Long-term: Brand should be enduring, not trendy
3. Stay Authentic: Brand must reflect true organizational values
4. Be Consistent: Repetition builds recognition
5. Consider Context: Brand exists in competitive and cultural context
6. Measure Impact: Track brand health metrics over time
7. Evolve Thoughtfully: Brands should evolve, but deliberately
8. Empower Team: Guidelines should enable, not restrict creativity

Business Analytics Reporter

Overview

Generate comprehensive business performance reports that analyze sales and revenue data, identify areas where the business is lacking, interpret what the statistics indicate, and provide actionable improvement strategies. The skill uses data-driven analysis to detect weak areas and recommends specific strategies backed by business frameworks.

When to Use This Skill

Invoke this skill when users request:

• "Analyze my business data and tell me where we're lacking"
• "Generate a report on what areas need improvement"
• "What do these sales numbers tell us about our business performance?"
• "Create a business analysis report with improvement strategies"
• "Identify weak areas in our revenue data"
• "What strategies should we use to improve our business metrics?"

The skill expects CSV files containing business data (sales, revenue, transactions) with columns like dates, amounts, categories, or products.

Core Workflow

Step 1: Data Loading and Exploration

Start by understanding the data structure and what the user wants to analyze.

Ask clarifying questions if needed:

• What specific metrics or areas should the analysis focus on?
• Are there particular time periods or categories of interest?
• Should the report include visualizations or focus on written analysis?

Load and explore the data:

import pandas as pd

# Load the CSV file
df = pd.read_csv('business_data.csv')

# Display basic information
print(f"Data shape: {df.shape}")
print(f"Columns: {df.columns.tolist()}")
print(f"Date range: {df['date'].min()} to {df['date'].max()}")
print(df.head())

Step 2: Run Automated Analysis

Use the bundled analysis script to generate comprehensive insights:

python scripts/analyze_business_data.py path/to/business_data.csv output_report.json

The script will:

1. Automatically detect data structure (revenue columns, date columns, categories)
2. Calculate statistical metrics (mean, median, growth rates, volatility)
3. Identify trends and patterns
4. Detect weak areas and underperforming segments
5. Generate improvement strategies based on findings
6. Output a structured JSON report

Output structure:

{
  "metadata": {...},
  "findings": {
    "basic_statistics": {...},
    "trend_analysis": {...},
    "category_analysis": {...},
    "variability": {...}
  },
  "weak_areas": [...],
  "improvement_strategies": [...]
}

Step 3: Interpret the Analysis Results

Read the generated JSON report and interpret the findings for the user in plain language.

Focus on:

1. Current State: What the data shows about business performance
2. Weak Areas: Specific problems identified with severity levels
3. Root Causes: Why these issues exist (use business frameworks from references/)
4. Impact: What these weaknesses mean for the business

Example interpretation:

Based on the analysis of your sales data from January to December 2024:

Current State:
- Total revenue: $1.2M with average monthly revenue of $100K
- Average growth rate: -3.5% indicating declining performance
- Revenue stability: High volatility (CV: 58%) suggesting inconsistent performance

Weak Areas Identified:
1. Revenue Growth (High Severity): Negative average growth rate of -3.5%
2. Performance Consistency (Medium Severity): 45% of periods show declining performance
3. Category Performance (Medium Severity): 4 underperforming categories identified

Step 4: Generate Detailed Recommendations

Consult the business frameworks reference to provide strategic recommendations:

Load business frameworks for context: Refer to references/business_frameworks.md for:

• Revenue growth strategies (market penetration, product development, etc.)
• Operational excellence frameworks
• Customer-centric strategies
• Pricing strategy frameworks
• Common weak area solutions

Structure recommendations as:

For each identified weak area, provide:

1. Strategic Initiative Name: Clear, actionable program name
2. Objective: What this strategy aims to achieve
3. Key Actions: 3-5 specific, prioritized steps
4. Expected Impact: High/Medium/Low
5. Timeline: Realistic implementation timeframe
6. Success Metrics: How to measure improvement

Example recommendation:

Strategy: Revenue Acceleration Program
Area: Revenue Growth
Objective: Reverse negative growth trend and achieve 10%+ monthly growth

Key Actions:
1. Implement aggressive customer acquisition campaigns
2. Review and optimize pricing strategy
3. Launch upselling and cross-selling initiatives
4. Expand into new market segments or geographies
5. Accelerate product development and innovation

Expected Impact: High
Timeline: 3-6 months
Success Metrics: Monthly revenue growth rate, new customer acquisition, ARPU increase

Step 5: Create Visualizations (Optional)

If requested, create interactive visualizations using Plotly to illustrate findings:

Consult visualization guide: Refer to references/visualization_guide.md for:

• Recommended chart types for different analyses
• Code examples for creating charts
• Best practices for business dashboards

Common visualizations to create:

1. Revenue Trend Chart: Line chart showing revenue over time with growth rate overlay
2. Category Performance: Bar chart sorted by revenue contribution
3. Volatility Analysis: Box plot or standard deviation visualization
4. Weak Areas Heatmap: Visual representation of severity and impact

Example code for revenue trend:

import plotly.graph_objects as go
from plotly.subplots import make_subplots

fig = make_subplots(specs=[[{"secondary_y": True}]])

# Add revenue line
fig.add_trace(
    go.Scatter(x=df['date'], y=df['revenue'], name="Revenue",
               line=dict(color='blue', width=3)),
    secondary_y=False
)

# Add growth rate line
fig.add_trace(
    go.Scatter(x=df['date'], y=df['growth_rate'], name="Growth Rate",
               line=dict(color='green', dash='dash')),
    secondary_y=True
)

fig.update_layout(title_text="Revenue Performance & Growth Rate")
fig.show()

Step 6: Generate Final Report

Compile findings into a comprehensive report format.

Option A: Generate HTML Report

Use the report template from assets/report_template.html:

# Read the template
with open('assets/report_template.html', 'r') as f:
    template = f.read()

# Load analysis results
with open('output_report.json', 'r') as f:
    analysis = json.load(f)

# Populate the template with actual data
# Replace placeholders with real values from analysis
# Add Plotly charts as JavaScript
# Save as final HTML report

with open('business_report.html', 'w') as f:
    f.write(populated_template)

The HTML template includes:

• Executive summary with key metrics
• Interactive charts for trends and categories
• Styled weak area cards with severity indicators
• Strategic recommendations with action items
• Professional styling and print-ready format

Option B: Generate Markdown Report

Create a structured markdown document:

# Business Performance Analysis Report

**Generated:** [Date]
**Data Period:** [Period]

## Executive Summary

[Brief overview of findings]

## Key Metrics

- Total Revenue: $X
- Average Growth Rate: X%
- Revenue Stability: [Assessment]
- Weak Areas Identified: X

## Performance Trends

[Insert chart or describe trends]

## Areas of Weakness

### 1. [Weak Area Name] (Severity)
**Finding:** [Description]
**Impact:** [Business impact]

### 2. [Next weak area...]

## Strategic Recommendations

### Strategy 1: [Name]
**Objective:** [Goal]
**Actions:**
- [Action 1]
- [Action 2]
...

**Expected Impact:** High/Medium/Low
**Timeline:** X months

Key Analysis Metrics

The analysis script calculates the following metrics automatically:

Growth Analysis

• Average Growth Rate: Period-over-period revenue change percentage
• Declining Period Count: Number of periods with negative growth
• Trend Direction: Overall trajectory (growing, declining, stable)

Stability Analysis

• Coefficient of Variation (CV): Measures revenue volatility
  • CV < 25%: Stable performance
  • CV 25-50%: Moderate volatility
  • CV > 50%: High volatility (flag as weak area)

Category Performance

• Revenue Contribution: Percentage breakdown by category
• Underperforming Categories: Bottom 25% by average performance
• Top/Bottom Performers: Best and worst performing categories

Statistical Indicators

• Mean, Median, Standard Deviation for all numeric columns
• Min/Max values and ranges
• Total aggregates

Business Frameworks Reference

When generating recommendations, leverage the frameworks documented in references/business_frameworks.md:

1. Revenue Growth Strategies: Market penetration, product development, market development, diversification
2. Operational Excellence: Process optimization, resource allocation, quality management
3. Customer-Centric Strategies: Retention programs, CLV optimization, segmentation
4. Pricing Strategies: Value-based, dynamic, competitive pricing
5. Data-Driven Decision Making: Analytics maturity model, KPI frameworks

Match identified weak areas with appropriate strategic frameworks to provide contextually relevant recommendations.

Tips for Effective Reports

1. Start with the Big Picture: Lead with overall performance and key findings
2. Prioritize by Severity: Focus on high-severity issues first
3. Be Specific: Provide concrete numbers and percentages, not vague assessments
4. Action-Oriented: Every weak area should have actionable recommendations
5. Context Matters: Consider industry benchmarks and business context
6. Visual Communication: Use charts to make trends immediately clear
7. Executive-Friendly: Structure for quick scanning with clear headers and summaries

Common Weak Areas and Detection

The analysis automatically detects these common business problems:

Example Usage

User request: "Analyze my Q4 sales data and tell me where we're weak and how to improve"

Workflow:

1. Load the CSV: df = pd.read_csv('q4_sales.csv')
2. Run analysis: python scripts/analyze_business_data.py q4_sales.csv q4_report.json
3. Read results: with open('q4_report.json') as f: report = json.load(f)
4. Interpret findings for the user in natural language
5. Create visualizations using Plotly (refer to references/visualization_guide.md)
6. Generate HTML report using assets/report_template.html
7. Provide strategic recommendations using references/business_frameworks.md

Expected output:

• Clear explanation of current business performance
• 3-5 identified weak areas with severity levels
• 4-6 strategic initiatives with specific action plans
• Interactive visualizations (if requested)
• Professional HTML or markdown report

Resources

scripts/

• analyze_business_data.py: Automated analysis engine that detects data structure, calculates metrics, identifies weak areas, and generates improvement strategies

references/

• business_frameworks.md: Comprehensive guide to business strategy frameworks, common weak areas, and solution templates
• visualization_guide.md: Chart type recommendations, Plotly code examples, and dashboard design best practices

assets/

• report_template.html: Professional HTML template with interactive visualizations, styled cards for weak areas and strategies, and print-ready formatting

Business Document Generator

Overview

Generate professional business documents (Project Proposals, Business Plans, Annual Budgets) from high-quality PDF templates. Use the bundled Python script to fill templates with user-provided data and output polished PDF documents ready for distribution.

When to Use This Skill

Activate this skill when the user asks to:

• Create a business proposal or project proposal
• Generate a business plan document
• Develop an annual budget plan
• Create any professional business document based on the available templates
• Fill in business templates with specific data

Available Document Types

This skill supports three types of professional business documents:

1. Project Proposal - Professional proposals for client projects

   • Template: assets/templates/Professional Proposal Template.pdf
   • Use case: Pitching projects to clients, stakeholders

2. Business Plan - Comprehensive business planning documents

   • Template: assets/templates/Comprehensive Business Plan Template.pdf
   • Use case: Startup planning, investor presentations, strategic planning

3. Annual Budget - Detailed budget planning documents

   • Template: assets/templates/Annual Budget Plan Template.pdf
   • Use case: Financial planning, budget proposals, fiscal year planning

Quick Start Workflow

Step 1: Understand User Requirements

Gather information from the user about:

• Document type needed (proposal, business plan, or budget)
• Key data to include (company name, client info, dates, etc.)
• Any specific customization needs

Step 2: Prepare the Data

Create a JSON file with the document data. Reference the data schemas in references/document_schemas.md for field requirements.

Example for Proposal:

{
  "title": "Digital Transformation Initiative",
  "subtitle": "A Comprehensive Plan for Acme Corporation",
  "client_org": "Acme Corporation",
  "client_contact": "Jane Smith, CTO",
  "company_name": "TechSolutions Inc.",
  "contact_info": "contact@techsolutions.com",
  "date": "November 3, 2025"
}

Note: Check assets/examples/ for complete example JSON files:

• proposal_example.json
• business_plan_example.json
• budget_example.json

Step 3: Install Dependencies (First Time Only)

The generation script requires Python packages. Install them:

pip install pypdf reportlab

Step 4: Generate the Document

Run the generation script:

python3 scripts/generate_document.py <document_type> <data_file> \
  --templates-dir assets/templates \
  --output-dir <output_directory>

Parameters:

• <document_type>: One of proposal, business_plan, or budget
• <data_file>: Path to JSON file with document data
• --templates-dir: Directory containing PDF templates (default: assets/templates)
• --output-dir: Where to save generated PDFs (default: output)
• --output-filename: Optional custom filename

Example:

python3 scripts/generate_document.py proposal my_proposal_data.json \
  --templates-dir assets/templates \
  --output-dir ./generated_docs

Step 5: Deliver the Document

The script outputs a PDF file in the specified output directory. Verify the document was generated successfully and inform the user of the file location.

Detailed Usage Instructions

Creating a Project Proposal

1. Collect proposal information:

   • Project title and subtitle
   • Client organization and contact
   • Your company name and contact info
   • Project details (problem, solution, timeline, budget)

2. Create a JSON data file with proposal fields (see references/document_schemas.md)

3. Run the script:

   python3 scripts/generate_document.py proposal proposal_data.json \
     --templates-dir assets/templates
   

4. Output: Professional PDF proposal with cover page and content sections

Creating a Business Plan

1. Collect business plan information:

   • Company name and legal structure
   • Mission and vision statements
   • Target market details
   • Financial projections

2. Create a JSON data file with business plan fields

3. Run the script:

   python3 scripts/generate_document.py business_plan plan_data.json \
     --templates-dir assets/templates
   

4. Output: Comprehensive business plan PDF template

Creating an Annual Budget

1. Collect budget information:

   • Fiscal year
   • Company name
   • Budget assumptions (inflation, growth targets)
   • Revenue and expense forecasts

2. Create a JSON data file with budget fields

3. Run the script:

   python3 scripts/generate_document.py budget budget_data.json \
     --templates-dir assets/templates
   

4. Output: Annual budget plan PDF with tables and projections

Important Notes

Script Functionality

The scripts/generate_document.py script:

• Reads PDF templates from the assets directory
• Overlays user data on template pages (primarily cover pages)
• Generates a new PDF with filled information
• Preserves the original template structure and formatting

Current Limitations

The script currently fills in cover page information (titles, names, dates). The template body content serves as a professional framework that users can follow when creating their documents manually or through other PDF editing tools.

Extending the Script

To fill additional fields beyond the cover page, the script can be enhanced to:

• Parse form fields in PDFs
• Add text overlays on specific coordinates for each page
• Replace placeholder text programmatically

Modify scripts/generate_document.py to add more sophisticated PDF manipulation as needed.

Data Schema Reference

For detailed information about required and optional fields for each document type, consult:

• references/document_schemas.md - Complete data structure documentation

Example Files

Find complete working examples in assets/examples/:

• proposal_example.json - Sample project proposal data
• business_plan_example.json - Sample business plan data
• budget_example.json - Sample budget plan data

Use these as starting templates when creating new documents.

Troubleshooting

Import errors when running the script:

• Install required packages: pip install pypdf reportlab

Template not found:

• Verify --templates-dir points to assets/templates
• Check that PDF template files exist in the templates directory

Generated PDF is blank or missing data:

• Verify JSON data file is properly formatted
• Check that required fields are present (see references/document_schemas.md)

Need to customize templates:

• Original templates are in assets/templates/
• Modify templates using PDF editing software
• Keep original filenames or update TEMPLATE_MAP in the script

Resources

scripts/

Contains the Python script for document generation:

• generate_document.py - Main document generation script with CLI interface

This script can be executed directly without loading into context for token efficiency. It may be read if modifications or debugging are needed.

references/

Documentation to reference while working:

• document_schemas.md - Complete JSON data structure for all document types

assets/

Files used in the document generation output:

• templates/ - Professional PDF templates for each document type
  • Professional Proposal Template.pdf
  • Comprehensive Business Plan Template.pdf
  • Annual Budget Plan Template.pdf
• examples/ - Sample JSON data files demonstrating proper structure
  • proposal_example.json
  • business_plan_example.json
  • budget_example.json

These templates and examples are not loaded into context but referenced during generation.

CI/CD Pipeline Generator

Overview

Generate production-ready CI/CD pipeline configuration files for various platforms (GitHub Actions, GitLab CI, CircleCI, Jenkins). This skill provides templates and guidance for setting up automated workflows that handle linting, testing, building, and deployment for modern web applications, particularly Node.js/Next.js projects.

Core Capabilities

1. Platform Selection

Choose the appropriate CI/CD platform based on project requirements:

• GitHub Actions: Best for GitHub-hosted projects with native integration
• GitLab CI/CD: Ideal for GitLab repositories with complex pipeline needs
• CircleCI: Optimized for Docker workflows and fast build times
• Jenkins: Suitable for self-hosted, highly customizable environments

Refer to references/platform-comparison.md for detailed platform comparisons, pros/cons, and use case recommendations.

2. Pipeline Configuration Generation

Generate pipeline configs following these principles:

Pipeline Stages

Structure pipelines with these standard stages:

1. Install Dependencies

   • Checkout code from repository
   • Setup runtime environment (Node.js version)
   • Restore cached dependencies
   • Install dependencies with npm ci
   • Cache dependencies for future runs

2. Lint

   • Run ESLint for code quality
   • Run TypeScript type checking
   • Fail fast on linting errors

3. Test

   • Execute unit tests
   • Execute integration tests
   • Generate code coverage reports
   • Upload coverage to reporting services (Codecov, Coveralls)

4. Build

   • Create production build
   • Verify build succeeds
   • Store build artifacts

5. Deploy

   • Deploy to staging (develop branch)
   • Deploy to production (main branch)
   • Run post-deployment smoke tests

Caching Strategy

Implement effective caching to speed up builds:

# Cache node_modules based on package-lock.json
cache:
  key: ${{ hashFiles('package-lock.json') }}
  paths:
    - node_modules/
    - .npm/

Environment Variables

Configure necessary environment variables:

• NODE_ENV: Set to production for builds
• Platform-specific tokens: Store as secrets
• Build-time variables: Pass to build process

3. Template Usage

Use provided templates from assets/ directory:

GitHub Actions Template (assets/github-actions-nodejs.yml):

• Multi-job workflow with lint, test, build, deploy
• Matrix builds for multiple Node.js versions (optional)
• Vercel deployment integration
• Artifact uploading
• Code coverage reporting

GitLab CI Template (assets/gitlab-ci-nodejs.yml):

• Multi-stage pipeline
• Dependency caching
• Manual production deployment
• Automatic staging deployment
• Coverage reporting

To use a template:

1. Copy the appropriate template file
2. Place in the correct location:
   • GitHub Actions: .github/workflows/ci.yml
   • GitLab CI: .gitlab-ci.yml
3. Customize deployment targets, environment variables, and branch names
4. Add required secrets to platform settings

4. Deployment Configuration

Vercel Deployment

For GitHub Actions:

- uses: amondnet/vercel-action@v25
  with:
    vercel-token: ${{ secrets.VERCEL_TOKEN }}
    vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
    vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
    vercel-args: '--prod'

Required Secrets:

• VERCEL_TOKEN: Get from Vercel account settings
• VERCEL_ORG_ID: From Vercel project settings
• VERCEL_PROJECT_ID: From Vercel project settings

Netlify Deployment

- run: |
    npm install -g netlify-cli
    netlify deploy --prod --dir=.next
  env:
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

AWS S3 + CloudFront

- uses: aws-actions/configure-aws-credentials@v4
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-1

- run: |
    aws s3 sync .next/static s3://${{ secrets.S3_BUCKET }}/static
    aws cloudfront create-invalidation --distribution-id ${{ secrets.CF_DIST_ID }} --paths "/*"

5. Testing Integration

Configure test execution with proper reporting:

Jest Configuration:

- name: Run tests with coverage
  run: npm test -- --coverage --coverageReporters=text --coverageReporters=lcov

- name: Upload coverage
  uses: codecov/codecov-action@v4
  with:
    files: ./coverage/lcov.info
    flags: unittests

Fail Fast Strategy:

# Run quick tests first
jobs:
  lint:  # Fails in ~30 seconds
  test:  # Fails in ~2 minutes
  build: # Fails in ~5 minutes
    needs: [lint, test]
  deploy:
    needs: [build]

6. Branch-Based Workflows

Implement different behaviors per branch:

Feature Branches / PRs:

• Run lint + test only
• No deployment
• Add PR comments with test results

Develop Branch:

• Run lint + test + build
• Deploy to staging environment
• Automatic deployment

Main Branch:

• Run lint + test + build
• Deploy to production
• Manual approval (optional)
• Create release tags

Example:

deploy_staging:
  if: github.ref == 'refs/heads/develop'
  # Deploy to staging

deploy_production:
  if: github.ref == 'refs/heads/main'
  environment: production  # Requires manual approval
  # Deploy to production

Workflow Decision Tree

Follow this decision tree to generate the appropriate pipeline:

1. Which platform?

   • GitHub → Use assets/github-actions-nodejs.yml
   • GitLab → Use assets/gitlab-ci-nodejs.yml
   • CircleCI/Jenkins → Adapt GitHub Actions template
   • Unsure → Consult references/platform-comparison.md

2. What stages are needed?

   • Always include: Lint, Test, Build
   • Optional: Security scanning, E2E tests, performance tests
   • Add deployment stage if deploying from CI

3. Which deployment platform?

   • Vercel → Use Vercel deployment examples
   • Netlify → Use Netlify CLI approach
   • AWS → Use AWS Actions/CLI
   • Custom → Implement custom deployment script

4. What triggers?

   • On push to main/develop
   • On pull request
   • On tag creation
   • Manual workflow dispatch

5. What environment variables needed?

   • Platform tokens (Vercel, Netlify, AWS)
   • API keys for external services
   • Build-time environment variables
   • Feature flags

Best Practices

Security

• Store all secrets in platform secret management (never in code)
• Use least-privilege tokens (read-only when possible)
• Rotate secrets regularly
• Audit secret access permissions
• Never log secrets (use *** masking)

Performance

• Cache dependencies aggressively
• Parallelize independent jobs
• Use matrix builds for multi-version testing
• Fail fast: Run quick checks before slow ones
• Optimize Docker layer caching

Reliability

• Pin exact Node.js versions (18.x not just 18)
• Commit lockfiles (package-lock.json)
• Add retry logic for flaky external services
• Set reasonable timeouts (10-15 minutes max)
• Use continue-on-error for non-critical steps

Maintainability

• Add comments explaining complex logic
• Use reusable workflows/templates
• Keep configs DRY (Don't Repeat Yourself)
• Version control all pipeline changes
• Document required secrets in README

Common Patterns

Multi-Environment Deployment

deploy_staging:
  environment: staging
  if: github.ref == 'refs/heads/develop'

deploy_production:
  environment: production
  if: github.ref == 'refs/heads/main'
  needs: [deploy_staging]

Matrix Testing

strategy:
  matrix:
    node-version: [16.x, 18.x, 20.x]
    os: [ubuntu-latest, windows-latest]

Conditional Steps

- name: Deploy
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  run: npm run deploy

Artifact Management

- name: Upload build
  uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: .next/
    retention-days: 7

- name: Download build
  uses: actions/download-artifact@v4
  with:
    name: build-output

Troubleshooting

Pipeline Failures

1. Check action/job logs for error messages
2. Verify environment variables and secrets are set
3. Test commands locally before adding to pipeline
4. Check for platform-specific issues in documentation

Slow Builds

1. Verify cache is working (check cache hit/miss logs)
2. Parallelize independent jobs
3. Use faster runners if available
4. Optimize dependency installation

Deployment Failures

1. Verify deployment tokens are valid
2. Check platform status pages
3. Review deployment logs
4. Test deployment commands locally

Resources

Templates (assets/)

• github-actions-nodejs.yml: Complete GitHub Actions workflow
• gitlab-ci-nodejs.yml: Complete GitLab CI pipeline

Reference Documentation (references/)

• platform-comparison.md: Detailed comparison of CI/CD platforms, deployment targets, best practices, and common patterns

Example Usage

User Request: "Create a GitHub Actions workflow that runs tests and deploys to Vercel"

Steps:

1. Copy assets/github-actions-nodejs.yml template
2. Create .github/workflows/ directory if it doesn't exist
3. Save as .github/workflows/ci.yml
4. Update deployment section with Vercel credentials
5. Add secrets to GitHub repository settings:
   • VERCEL_TOKEN
   • VERCEL_ORG_ID
   • VERCEL_PROJECT_ID
6. Commit and push to trigger workflow

User Request: "Set up GitLab CI with staging and production environments"

Steps:

1. Copy assets/gitlab-ci-nodejs.yml template
2. Save as .gitlab-ci.yml in repository root
3. Configure GitLab CI/CD variables:
   • VERCEL_TOKEN
   • Other deployment credentials
4. Review manual approval settings for production
5. Commit to trigger pipeline

Advanced Configuration

Monorepo Support

paths:
  - 'apps/frontend/**'
  - 'packages/**'

Scheduled Runs

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

External Service Integration

- name: Notify Slack
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}

Security Scanning

- name: Run security audit
  run: npm audit --audit-level=moderate

- name: Check for vulnerabilities
  uses: snyk/actions/node@master
  env:
    SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

Codebase Documenter

Overview

This skill enables creating comprehensive, beginner-friendly documentation for codebases. It provides structured templates and best practices for writing READMEs, architecture guides, code comments, and API documentation that help new users quickly understand and contribute to projects.

Core Principles for Beginner-Friendly Documentation

When documenting code for new users, follow these fundamental principles:

1. Start with the "Why" - Explain the purpose before diving into implementation details
2. Use Progressive Disclosure - Present information in layers from simple to complex
3. Provide Context - Explain not just what the code does, but why it exists
4. Include Examples - Show concrete usage examples for every concept
5. Assume No Prior Knowledge - Define terms and avoid jargon when possible
6. Visual Aids - Use diagrams, flowcharts, and file tree structures
7. Quick Wins - Help users get something running within 5 minutes

Documentation Types and When to Use Them

1. README Documentation

When to create: For project root directories, major feature modules, or standalone components.

Structure to follow:

# Project Name

## What This Does
[1-2 sentence plain-English explanation]

## Quick Start
[Get users running the project in < 5 minutes]

## Project Structure
[Visual file tree with explanations]

## Key Concepts
[Core concepts users need to understand]

## Common Tasks
[Step-by-step guides for frequent operations]

## Troubleshooting
[Common issues and solutions]

Best practices:

• Lead with the project's value proposition
• Include setup instructions that actually work (test them!)
• Provide a visual overview of the project structure
• Link to deeper documentation for advanced topics
• Keep the root README focused on getting started

2. Architecture Documentation

When to create: For projects with multiple modules, complex data flows, or non-obvious design decisions.

Structure to follow:

# Architecture Overview

## System Design
[High-level diagram and explanation]

## Directory Structure
[Detailed breakdown with purpose of each directory]

## Data Flow
[How data moves through the system]

## Key Design Decisions
[Why certain architectural choices were made]

## Module Dependencies
[How different parts interact]

## Extension Points
[Where and how to add new features]

Best practices:

• Use diagrams to show system components and relationships
• Explain the "why" behind architectural decisions
• Document both the happy path and error handling
• Identify boundaries between modules
• Include visual file tree structures with annotations

3. Code Comments

When to create: For complex logic, non-obvious algorithms, or code that requires context.

Annotation patterns:

Function/Method Documentation:

/**
 * Calculates the prorated subscription cost for a partial billing period.
 *
 * Why this exists: Users can subscribe mid-month, so we need to charge
 * them only for the days remaining in the current billing cycle.
 *
 * @param {number} fullPrice - The normal monthly subscription price
 * @param {Date} startDate - When the user's subscription begins
 * @param {Date} periodEnd - End of the current billing period
 * @returns {number} The prorated amount to charge
 *
 * @example
 * // User subscribes on Jan 15, period ends Jan 31
 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
 * // Returns: 16.13 (17 days out of 31 days)
 */

Complex Logic Documentation:

# Why this check exists: The API returns null for deleted users,
# but empty string for users who never set a name. We need to
# distinguish between these cases for the audit log.
if user_name is None:
    # User was deleted - log this as a security event
    log_deletion_event(user_id)
elif user_name == "":
    # User never completed onboarding - safe to skip
    continue

Best practices:

• Explain "why" not "what" - the code shows what it does
• Document edge cases and business logic
• Add examples for complex functions
• Explain parameters that aren't self-explanatory
• Note any gotchas or counterintuitive behavior

4. API Documentation

When to create: For any HTTP endpoints, SDK methods, or public interfaces.

Structure to follow:

## Endpoint Name

### What It Does
[Plain-English explanation of the endpoint's purpose]

### Endpoint
`POST /api/v1/resource`

### Authentication
[What auth is required and how to provide it]

### Request Format
[JSON schema or example request]

### Response Format
[JSON schema or example response]

### Example Usage
[Concrete example with curl/code]

### Common Errors
[Error codes and what they mean]

### Related Endpoints
[Links to related operations]

Best practices:

• Provide working curl examples
• Show both success and error responses
• Explain authentication clearly
• Document rate limits and constraints
• Include troubleshooting for common issues

Documentation Workflow

Step 1: Analyze the Codebase

Before writing documentation:

1. Identify entry points - Main files, index files, app initialization
2. Map dependencies - How modules relate to each other
3. Find core concepts - Key abstractions users need to understand
4. Locate configuration - Environment setup, config files
5. Review existing docs - Build on what's there, don't duplicate

Step 2: Choose Documentation Type

Based on user request and codebase analysis:

• New project or missing README → Start with README documentation
• Complex architecture or multiple modules → Create architecture documentation
• Confusing code sections → Add inline code comments
• HTTP/API endpoints → Write API documentation
• Multiple types needed → Address in order: README → Architecture → API → Comments

Step 3: Generate Documentation

Use the templates from assets/templates/ as starting points:

• assets/templates/README.template.md - For project READMEs
• assets/templates/ARCHITECTURE.template.md - For architecture docs
• assets/templates/API.template.md - For API documentation

Customize templates based on the specific codebase:

1. Fill in project-specific information - Replace placeholders with actual content
2. Add concrete examples - Use real code from the project
3. Include visual aids - Create file trees, diagrams, flowcharts
4. Test instructions - Verify setup steps actually work
5. Link related docs - Connect documentation pieces together

Step 4: Review for Clarity

Before finalizing documentation:

1. Read as a beginner - Does it make sense without project context?
2. Check completeness - Are there gaps in the explanation?
3. Verify examples - Do code examples actually work?
4. Test instructions - Can someone follow the setup steps?
5. Improve structure - Is information easy to find?

Documentation Templates

This skill includes several templates in assets/templates/ that provide starting structures:

Available Templates

• README.template.md - Comprehensive README structure with sections for quick start, project structure, and common tasks
• ARCHITECTURE.template.md - Architecture documentation template with system design, data flow, and design decisions
• API.template.md - API endpoint documentation with request/response formats and examples
• CODE_COMMENTS.template.md - Examples and patterns for effective inline documentation

Using Templates

1. Read the appropriate template from assets/templates/
2. Customize for the specific project - Replace placeholders with actual information
3. Add project-specific sections - Extend the template as needed
4. Include real examples - Use actual code from the codebase
5. Remove irrelevant sections - Delete parts that don't apply

Best Practices Reference

For detailed documentation best practices, style guidelines, and advanced patterns, refer to:

• references/documentation_guidelines.md - Comprehensive style guide and best practices
• references/visual_aids_guide.md - How to create effective diagrams and file trees

Load these references when:

• Creating documentation for complex enterprise codebases
• Dealing with multiple stakeholder requirements
• Needing advanced documentation patterns
• Standardizing documentation across a large project

Common Patterns

Creating File Tree Structures

File trees help new users understand project organization:

project-root/
├── src/                    # Source code
│   ├── components/        # Reusable UI components
│   ├── pages/             # Page-level components (routing)
│   ├── services/          # Business logic and API calls
│   ├── utils/             # Helper functions
│   └── types/             # TypeScript type definitions
├── public/                # Static assets (images, fonts)
├── tests/                 # Test files mirroring src structure
└── package.json           # Dependencies and scripts

Explaining Complex Data Flows

Use numbered steps with diagrams:

User Request Flow:
1. User submits form → 2. Validation → 3. API call → 4. Database → 5. Response

[1] components/UserForm.tsx
    ↓ validates input
[2] services/validation.ts
    ↓ sends to API
[3] services/api.ts
    ↓ queries database
[4] Database (PostgreSQL)
    ↓ returns data
[5] components/UserForm.tsx (updates UI)

Documenting Design Decisions

Capture the "why" behind architectural choices:

## Why We Use Redux

**Decision:** State management with Redux instead of Context API

**Context:** Our app has 50+ components that need access to user
authentication state, shopping cart, and UI preferences.

**Reasoning:**
- Context API causes unnecessary re-renders with this many components
- Redux DevTools helps debug complex state changes
- Team has existing Redux expertise

**Trade-offs:**
- More boilerplate code
- Steeper learning curve for new developers
- Worth it for: performance, debugging, team familiarity

Output Guidelines

When generating documentation:

1. Write for the target audience - Adjust complexity based on whether documentation is for beginners, intermediate, or advanced users
2. Use consistent formatting - Follow markdown conventions, consistent heading hierarchy
3. Provide working examples - Test all code snippets and commands
4. Link between documents - Create a documentation navigation structure
5. Keep it maintainable - Documentation should be easy to update as code changes
6. Add dates and versions - Note when documentation was last updated

Quick Reference

Command to generate README: "Create a README file for this project that helps new developers get started"

Command to document architecture: "Document the architecture of this codebase, explaining how the different modules interact"

Command to add code comments: "Add explanatory comments to this file that help new developers understand the logic"

Command to document API: "Create API documentation for all the endpoints in this file"

CSV Data Visualizer

Overview

This skill enables comprehensive data visualization and analysis for CSV files. It provides three main capabilities: (1) creating individual interactive visualizations using Plotly, (2) automatic data profiling with statistical summaries, and (3) generating multi-plot dashboards. The skill is optimized for exploratory data analysis, statistical reporting, and creating presentation-ready visualizations.

When to Use This Skill

Invoke this skill when users request:

• "Visualize this CSV data"
• "Create a histogram/scatter plot/box plot from this data"
• "Show me the distribution of [column]"
• "Generate a dashboard for this dataset"
• "Profile this CSV file" or "Analyze this data"
• "Create a correlation heatmap"
• "Show trends over time"
• "Compare [variable] across [categories]"

Core Capabilities

1. Individual Visualizations

Create specific chart types for detailed analysis using the visualize_csv.py script.

Available Chart Types:

Statistical Plots:

# Histogram - distribution of numeric data
python3 scripts/visualize_csv.py data.csv --histogram column_name --bins 30

# Box plot - show quartiles and outliers
python3 scripts/visualize_csv.py data.csv --boxplot column_name

# Box plot grouped by category
python3 scripts/visualize_csv.py data.csv --boxplot salary --group-by department

# Violin plot - distribution with probability density
python3 scripts/visualize_csv.py data.csv --violin column_name --group-by category

Relationship Analysis:

# Scatter plot with automatic trend line
python3 scripts/visualize_csv.py data.csv --scatter height weight

# Scatter plot with color and size encoding
python3 scripts/visualize_csv.py data.csv --scatter x y --color category --size value

# Correlation heatmap for all numeric columns
python3 scripts/visualize_csv.py data.csv --correlation

Time Series:

# Line chart for single variable
python3 scripts/visualize_csv.py data.csv --line date sales

# Multiple variables on same chart
python3 scripts/visualize_csv.py data.csv --line date "sales,revenue,profit"

Categorical Data:

# Bar chart (counts categories automatically)
python3 scripts/visualize_csv.py data.csv --bar category

# Pie chart for composition
python3 scripts/visualize_csv.py data.csv --pie region

Output Formats: Specify output file with desired format extension:

# Interactive HTML (default)
python3 scripts/visualize_csv.py data.csv --histogram age -o output.html

# Static image formats
python3 scripts/visualize_csv.py data.csv --scatter x y -o plot.png
python3 scripts/visualize_csv.py data.csv --correlation -o heatmap.pdf
python3 scripts/visualize_csv.py data.csv --bar category -o chart.svg

2. Automatic Data Profiling

Generate comprehensive data quality and statistical reports using the data_profile.py script.

Text Report (default):

python3 scripts/data_profile.py data.csv

HTML Report:

python3 scripts/data_profile.py data.csv -f html -o report.html

JSON Report:

python3 scripts/data_profile.py data.csv -f json -o profile.json

What the Profiler Provides:

• File information (size, dimensions)
• Dataset overview (shape, memory usage, duplicates)
• Column-by-column analysis (types, missing data, unique values)
• Missing data patterns and completeness
• Statistical summary for numeric columns (mean, std, quartiles, skewness, kurtosis)
• Categorical column analysis (frequency counts, most/least common values)
• Data quality checks (high missing data, duplicate rows, constant columns, high cardinality)

When to Use Profiling: Always recommend running data profiling BEFORE creating visualizations when:

• User is unfamiliar with the dataset
• Data quality is unknown
• Need to identify appropriate visualization types
• Exploring a new dataset for the first time

3. Multi-Plot Dashboards

Create comprehensive dashboards with multiple visualizations using the create_dashboard.py script.

Automatic Dashboard: Analyzes data types and automatically creates appropriate visualizations:

python3 scripts/create_dashboard.py data.csv

Custom output location:

python3 scripts/create_dashboard.py data.csv -o my_dashboard.html

Control number of plots:

python3 scripts/create_dashboard.py data.csv --max-plots 9

Custom Dashboard from Config: Create a JSON configuration file specifying exact plots:

python3 scripts/create_dashboard.py data.csv --config config.json

Dashboard Config Format:

{
  "title": "Sales Analysis Dashboard",
  "plots": [
    {"type": "histogram", "column": "revenue"},
    {"type": "box", "column": "revenue", "group_by": "region"},
    {"type": "scatter", "column": "advertising", "group_by": "revenue"},
    {"type": "bar", "column": "product_category"},
    {"type": "correlation"}
  ]
}

Dashboard Plot Types:

• histogram: Distribution of numeric column
• box: Box plot, optionally grouped by category
• scatter: Relationship between two numeric columns
• bar: Count of categorical values
• correlation: Heatmap of numeric correlations

Workflow Decision Tree

Use this decision tree to determine the appropriate approach:

User provides CSV file
│
├─ "Profile this data" / "Analyze this data" / Unfamiliar dataset
│  └─> Run data_profile.py first
│     Then offer visualization options based on findings
│
├─ "Create dashboard" / "Overview of the data" / Multiple visualizations needed
│  ├─ User knows exact plots wanted
│  │  └─> Create JSON config → run create_dashboard.py with config
│  └─ User wants automatic dashboard
│     └─> Run create_dashboard.py (auto mode)
│
└─ Specific visualization requested ("histogram", "scatter plot", etc.)
   └─> Use visualize_csv.py with appropriate flag

Best Practices

Starting Analysis

1. Always profile first for unfamiliar datasets: python3 scripts/data_profile.py data.csv
2. Review the profiling output to understand:
   • Column data types and ranges
   • Missing data patterns
   • Data quality issues
   • Statistical distributions

Choosing Visualizations

Consult references/visualization_guide.md for detailed guidance. Quick reference:

• Distribution: Histogram, box plot, violin plot
• Relationship: Scatter plot, correlation heatmap
• Time series: Line chart
• Categories: Bar chart (preferred) or pie chart (use sparingly)
• Comparison: Box plot grouped by category

Creating Dashboards

• Automatic dashboard: Good for initial exploration
• Custom dashboard: Better for presentations or specific analysis goals
• Limit plots: Keep to 6-9 plots maximum for readability
• Logical grouping: Group related visualizations together

Output Considerations

• HTML: Best for interactive exploration (zoom, pan, hover tooltips)
• PNG/PDF: Best for reports and presentations
• SVG: Best for publications requiring vector graphics

Dependencies

The scripts require these Python packages:

pip install pandas plotly numpy

For static image export (PNG, PDF, SVG), also install:

pip install kaleido

Example Workflows

Exploratory Data Analysis

# 1. Profile the data
python3 scripts/data_profile.py sales_data.csv -f html -o profile.html

# 2. Create automatic dashboard
python3 scripts/create_dashboard.py sales_data.csv -o dashboard.html

# 3. Dive deeper with specific plots
python3 scripts/visualize_csv.py sales_data.csv --scatter price sales --color region
python3 scripts/visualize_csv.py sales_data.csv --boxplot revenue --group-by product

Report Generation

# Create specific visualizations for report
python3 scripts/visualize_csv.py data.csv --histogram age -o fig1_distribution.png
python3 scripts/visualize_csv.py data.csv --scatter income age -o fig2_correlation.png
python3 scripts/visualize_csv.py data.csv --bar category -o fig3_categories.png

# Generate data summary
python3 scripts/data_profile.py data.csv -f html -o data_summary.html

Interactive Dashboard

# Create custom dashboard for presentation
# 1. First, create config.json with desired plots
# 2. Generate dashboard
python3 scripts/create_dashboard.py data.csv --config config.json -o presentation_dashboard.html

Troubleshooting

"Column not found" errors:

• Run data profiling to see exact column names
• CSV columns are case-sensitive
• Check for leading/trailing spaces in column names

Empty or incorrect visualizations:

• Verify data types (numeric vs categorical)
• Check for missing data in plotted columns
• Ensure sufficient non-null values exist

Script execution errors:

• Verify dependencies are installed: pip list | grep plotly
• Check Python version: Python 3.6+ required
• For image export issues, install kaleido: pip install kaleido

Resources

scripts/

• visualize_csv.py: Main visualization script with all chart types
• data_profile.py: Automatic data profiling and quality analysis
• create_dashboard.py: Multi-plot dashboard generator

references/

• visualization_guide.md: Comprehensive guide for choosing appropriate chart types, best practices, and common patterns

Data Analyst

Overview

This skill provides comprehensive capabilities for data analysis workflows on CSV datasets. It automatically analyzes missing value patterns, intelligently imputes missing data using appropriate statistical methods, and creates interactive Plotly Dash dashboards for visualizing trends and patterns. The skill combines automated missing value handling with rich interactive visualizations to support end-to-end exploratory data analysis.

Core Capabilities

The data-analyst skill provides three main capabilities that can be used independently or as a complete workflow:

1. Missing Value Analysis

Automatically detect and analyze missing values in datasets, identifying patterns and suggesting optimal imputation strategies.

2. Intelligent Imputation

Apply sophisticated imputation methods tailored to each column's data type and distribution characteristics.

3. Interactive Dashboard Creation

Generate comprehensive Plotly Dash dashboards with multiple visualization types for trend analysis and exploration.

Complete Workflow

When a user requests complete data analysis with missing value handling and visualization, follow this workflow:

Step 1: Analyze Missing Values

Run the missing value analysis script to understand the data quality:

python3 scripts/analyze_missing_values.py <input_file.csv> <output_analysis.json>

What this does:

• Detects missing values in each column
• Identifies data types (numeric, categorical, temporal, etc.)
• Calculates missing value statistics
• Suggests appropriate imputation strategies per column
• Generates detailed JSON report and console output

Review the output to understand:

• Which columns have missing data
• The percentage of missing values
• The recommended imputation method for each column
• Why each method was recommended

Step 2: Impute Missing Values

Apply automatic imputation based on the analysis:

python3 scripts/impute_missing_values.py <input_file.csv> <analysis.json> <output_imputed.csv>

What this does:

• Loads the analysis results (or performs analysis if not provided)
• Applies the optimal imputation method to each column:
  • Mean: For normally distributed numeric data
  • Median: For skewed numeric data
  • Mode: For categorical variables
  • KNN: For multivariate numeric data with correlations
  • Forward fill: For time series data
  • Constant: For high-cardinality text fields
• Handles edge cases (drops rows/columns when appropriate)
• Generates imputation report with before/after statistics
• Saves cleaned dataset

The script automatically:

• Drops columns with >70% missing values
• Drops rows where critical ID columns are missing
• Performs batch KNN imputation for correlated variables
• Creates detailed imputation log

Step 3: Create Interactive Dashboard

Generate an interactive Plotly Dash dashboard:

python3 scripts/create_dashboard.py <imputed_file.csv> <output_dir> <port>

Example:

python3 scripts/create_dashboard.py data_imputed.csv ./visualizations 8050

What this does:

• Automatically detects column types (numeric, categorical, temporal)
• Creates comprehensive visualizations:
  • Summary statistics table: Descriptive stats for all numeric columns
  • Time series plots: Trend analysis if date/time columns exist
  • Distribution plots: Histograms for understanding data distributions
  • Correlation heatmap: Relationships between numeric variables
  • Categorical analysis: Bar charts for categorical variables
  • Scatter plot matrix: Pairwise relationships between variables
• Launches interactive Dash web server
• Optionally saves static HTML visualizations

Access the dashboard at http://127.0.0.1:8050 (or specified port)

Individual Use Cases

Use Case A: Quick Missing Value Assessment

When the user wants to understand data quality without imputation:

python3 scripts/analyze_missing_values.py data.csv

Review the console output to understand missing value patterns and get recommendations.

Use Case B: Imputation Only

When the user has a dataset with missing values and wants cleaned data:

python3 scripts/impute_missing_values.py data.csv

This performs analysis and imputation in one step, producing data_imputed.csv.

Use Case C: Visualization Only

When the user has a clean dataset and wants interactive visualizations:

python3 scripts/create_dashboard.py clean_data.csv ./visualizations 8050

This creates a full dashboard without any preprocessing.

Use Case D: Custom Imputation Strategy

When the user wants to review and adjust imputation strategies:

1. Run analysis first:

   python3 scripts/analyze_missing_values.py data.csv analysis.json
   

2. Review analysis.json and discuss strategies with the user

3. If needed, modify the imputation logic or parameters in the script

4. Run imputation:

   python3 scripts/impute_missing_values.py data.csv analysis.json data_imputed.csv
   

Understanding Imputation Methods

The skill uses intelligent imputation strategies based on data characteristics. Key methods include:

• Mean/Median: For numeric data (mean for normal distributions, median for skewed)
• Mode: For categorical variables (most frequent value)
• KNN (K-Nearest Neighbors): For multivariate numeric data where variables are correlated
• Forward Fill: For time series data (carry last observation forward)
• Interpolation: For smooth temporal trends
• Constant Value: For high-cardinality text fields (e.g., "Unknown")
• Drop: For columns with >70% missing or rows with missing IDs

For detailed information about when each method is appropriate, refer to references/imputation_methods.md.

Dashboard Features

The interactive dashboard includes:

Summary Statistics

• Count, mean, std, min, max, quartiles for all numeric columns
• Missing value counts and percentages
• Sortable table format

Time Series Analysis

• Line plots with markers for temporal trends
• Multiple series support (up to 4 primary metrics)
• Hover details with exact values
• Unified hover mode for easy comparison

Distribution Analysis

• Histograms for all numeric variables
• 30-bin default for granular distribution view
• Multi-panel layout for easy comparison

Correlation Analysis

• Heatmap showing correlation coefficients
• Color-coded from -1 (negative) to +1 (positive)
• Annotated with exact correlation values
• Useful for identifying relationships

Categorical Analysis

• Bar charts for categorical variables
• Top 10 categories shown (for high-cardinality variables)
• Frequency counts displayed

Scatter Plot Matrix

• Pairwise scatter plots for numeric variables
• Limited to 5 variables for readability
• Lower triangle shown (avoiding redundancy)

Setup and Dependencies

Before using the skill, ensure dependencies are installed:

pip install -r requirements.txt

Required packages:

• pandas - Data manipulation and analysis
• numpy - Numerical computing
• scikit-learn - KNN imputation
• plotly - Interactive visualizations
• dash - Web dashboard framework
• dash-bootstrap-components - Dashboard styling

Best Practices

For Analysis:

1. Always run analysis before imputation to understand data quality
2. Review suggested imputation methods - they're recommendations, not mandates
3. Pay attention to missing value percentages (>40% requires careful consideration)
4. Check data types match expectations (e.g., numeric IDs detected as numeric)

For Imputation:

1. Save the original dataset before imputation
2. Review the imputation report to ensure methods make sense
3. Check imputed values are within reasonable ranges
4. Consider creating missing indicators for important variables
5. Document which imputation methods were used for reproducibility

For Dashboards:

1. Use imputed/cleaned data for most accurate visualizations
2. Save static HTML plots if sharing with non-technical stakeholders
3. Use different ports if running multiple dashboards simultaneously
4. For large datasets (>100k rows), consider sampling for faster rendering

Handling Edge Cases

High Missing Rates (>50%)

The scripts automatically flag columns with >50% missing values. Options:

• Drop the column if not critical
• Create a missing indicator variable
• Investigate why data is missing (may be informative)

Mixed Data Types

If a column contains mixed types (e.g., numbers and text):

• The script detects the primary type
• Consider cleaning the column before analysis
• Use constant imputation for mixed-type text columns

Small Datasets

For datasets with <50 rows:

• Simple imputation (mean/median/mode) is more stable
• Avoid KNN (requires sufficient neighbors)
• Consider dropping rows instead of imputing

Time Series Gaps

For time series with irregular timestamps:

• Use forward fill for short gaps
• Use interpolation for longer gaps with smooth trends
• Consider the sampling frequency when choosing methods

Troubleshooting

Script fails with "module not found"

Install dependencies: pip install -r requirements.txt

Dashboard won't start (port in use)

Specify a different port: python3 scripts/create_dashboard.py data.csv ./viz 8051

KNN imputation is slow

KNN is computationally intensive for large datasets. For >50k rows, consider:

• Using simpler methods (mean/median)
• Sampling the data first
• Using fewer columns in KNN

Imputed values seem incorrect

• Review the analysis report - check detected data types
• Verify the column is being detected correctly (numeric vs categorical)
• Consider manual adjustment or different imputation method
• Check for outliers that may affect mean/median calculations

Resources

scripts/

• analyze_missing_values.py - Comprehensive missing value analysis with automatic strategy recommendation
• impute_missing_values.py - Intelligent imputation using multiple methods tailored to data characteristics
• create_dashboard.py - Interactive Plotly Dash dashboard generator with multiple visualization types

references/

• imputation_methods.md - Detailed guide to missing value imputation strategies, decision frameworks, and best practices

Other Files

• requirements.txt - Python dependencies for the skill

Docker Containerization Skill

Overview

Generate production-ready Docker configurations for modern web applications, particularly Next.js and Node.js projects. This skill provides Dockerfiles, docker-compose setups, bash scripts for container management, and comprehensive deployment guides for various orchestration platforms.

Core Capabilities

1. Dockerfile Generation

Create optimized Dockerfiles for different environments:

Production (assets/Dockerfile.production):

• Multi-stage build reducing image size by 85%
• Alpine Linux base (~180MB final image)
• Non-root user execution for security
• Health checks and resource limits

Development (assets/Dockerfile.development):

• Hot reload support
• All dev dependencies included
• Volume mounts for live code updates

Nginx Static (assets/Dockerfile.nginx):

• Static export optimization
• Nginx reverse proxy included
• Smallest possible footprint

2. Docker Compose Configuration

Multi-container orchestration with assets/docker-compose.yml:

• Development and production services
• Network and volume management
• Health checks and logging
• Restart policies

3. Bash Scripts for Container Management

docker-build.sh - Build images with comprehensive options:

./docker-build.sh -e prod -t v1.0.0
./docker-build.sh -n my-app --no-cache --platform linux/amd64

docker-run.sh - Run containers with full configuration:

./docker-run.sh -i my-app -t v1.0.0 -d
./docker-run.sh -p 8080:3000 --env-file .env.production

docker-push.sh - Push to registries (Docker Hub, ECR, GCR, ACR):

./docker-push.sh -n my-app -t v1.0.0 --repo username/my-app
./docker-push.sh -r gcr.io/project --repo my-app --also-tag stable

docker-cleanup.sh - Free disk space:

./docker-cleanup.sh --all --dry-run  # Preview cleanup
./docker-cleanup.sh --containers --images  # Clean specific resources

4. Configuration Files

• .dockerignore: Excludes unnecessary files (node_modules, .git, logs)
• nginx.conf: Production-ready Nginx configuration with compression, caching, security headers

5. Reference Documentation

docker-best-practices.md covers:

• Multi-stage builds explained
• Image optimization techniques (50-85% size reduction)
• Security best practices (non-root users, vulnerability scanning)
• Performance optimization
• Health checks and logging
• Troubleshooting guide

container-orchestration.md covers deployment to:

• Docker Compose (local development)
• Kubernetes (enterprise scale with auto-scaling)
• Amazon ECS (AWS-native orchestration)
• Google Cloud Run (serverless containers)
• Azure Container Instances
• Digital Ocean App Platform

Includes configuration examples, commands, auto-scaling setup, and monitoring.

Workflow Decision Tree

1. What environment?

• Development → Dockerfile.development (hot reload, all dependencies)
• Production → Dockerfile.production (minimal, secure, optimized)
• Static Export → Dockerfile.nginx (smallest footprint)

2. Single or Multi-container?

• Single → Generate Dockerfile only
• Multi → Generate docker-compose.yml (app + database, microservices)

3. Which registry?

• Docker Hub → docker.io/username/image
• AWS ECR → 123456789012.dkr.ecr.region.amazonaws.com/image
• Google GCR → gcr.io/project-id/image
• Azure ACR → registry.azurecr.io/image

4. Deployment platform?

• Kubernetes → See references/container-orchestration.md K8s section
• ECS → See ECS task definition examples
• Cloud Run → See deployment commands
• Docker Compose → Use provided compose file

5. Optimizations needed?

• Image size → Multi-stage builds, Alpine base
• Build speed → Layer caching, BuildKit
• Security → Non-root user, vulnerability scanning
• Performance → Resource limits, health checks

Usage Examples

Example 1: Containerize Next.js App for Production

User: "Containerize my Next.js app for production"

Steps:

1. Copy assets/Dockerfile.production to project root as Dockerfile
2. Copy assets/.dockerignore to project root
3. Build: ./docker-build.sh -e prod -n my-app -t v1.0.0
4. Test: ./docker-run.sh -i my-app -t v1.0.0 -p 3000:3000 -d
5. Push: ./docker-push.sh -n my-app -t v1.0.0 --repo username/my-app

Example 2: Development with Docker Compose

User: "Set up Docker Compose for local development"

Steps:

1. Copy assets/Dockerfile.development and assets/docker-compose.yml to project
2. Customize services in docker-compose.yml
3. Start: docker-compose up -d
4. Logs: docker-compose logs -f app-dev

Example 3: Deploy to Kubernetes

User: "Deploy my containerized app to Kubernetes"

Steps:

1. Build and push image to registry
2. Review references/container-orchestration.md Kubernetes section
3. Create K8s manifests (deployment, service, ingress)
4. Apply: kubectl apply -f deployment.yaml
5. Verify: kubectl get pods && kubectl logs -f deployment/app

Example 4: Deploy to AWS ECS

User: "Deploy to AWS ECS Fargate"

Steps:

1. Build and push to ECR
2. Review references/container-orchestration.md ECS section
3. Create task definition JSON
4. Register: aws ecs register-task-definition --cli-input-json file://task-def.json
5. Create service: aws ecs create-service --cluster my-cluster --service-name app --desired-count 3

Best Practices

Security

✅ Use multi-stage builds for production ✅ Run as non-root user ✅ Use specific image tags (not latest) ✅ Scan for vulnerabilities ✅ Never hardcode secrets ✅ Implement health checks

Performance

✅ Optimize layer caching order ✅ Use Alpine images (~85% smaller) ✅ Enable BuildKit for parallel builds ✅ Set resource limits ✅ Use compression

Maintainability

✅ Add comments for complex steps ✅ Use build arguments for flexibility ✅ Keep Dockerfiles DRY ✅ Version control all configs ✅ Document environment variables

Troubleshooting

Image too large (>500MB) → Use multi-stage builds, Alpine base, comprehensive .dockerignore

Build is slow → Optimize layer caching, use BuildKit, review dependencies

Container exits immediately → Check logs: docker logs container-name → Verify CMD/ENTRYPOINT, check port conflicts

Changes not reflecting → Rebuild without cache, check .dockerignore, verify volume mounts

Quick Reference

# Build
./docker-build.sh -e prod -t latest

# Run
./docker-run.sh -i app -t latest -d

# Logs
docker logs -f app

# Execute
docker exec -it app sh

# Cleanup
./docker-cleanup.sh --all --dry-run  # Preview
./docker-cleanup.sh --all            # Execute

Integration with CI/CD

GitHub Actions

- run: |
    chmod +x docker-build.sh docker-push.sh
    ./docker-build.sh -e prod -t ${{ github.sha }}
    ./docker-push.sh -n app -t ${{ github.sha }} --repo username/app

GitLab CI

build:
  script:
    - chmod +x docker-build.sh
    - ./docker-build.sh -e prod -t $CI_COMMIT_SHA

Resources

Scripts (scripts/)

Production-ready bash scripts with comprehensive features:

• docker-build.sh - Build images (400+ lines, colorized output)
• docker-run.sh - Run containers (400+ lines, auto conflict resolution)
• docker-push.sh - Push to registries (multi-registry support)
• docker-cleanup.sh - Clean resources (dry-run mode, selective cleanup)

References (references/)

Detailed documentation loaded as needed:

• docker-best-practices.md - Comprehensive Docker best practices (~500 lines)
• container-orchestration.md - Deployment guides for 6+ platforms (~600 lines)

Assets (assets/)

Ready-to-use templates:

• Dockerfile.production - Multi-stage production Dockerfile
• Dockerfile.development - Development Dockerfile
• Dockerfile.nginx - Static export with Nginx
• docker-compose.yml - Multi-container orchestration
• .dockerignore - Optimized exclusion rules
• nginx.conf - Production Nginx configuration

DOCX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Workflow Decision Tree

Reading/Analyzing Content

Use "Text extraction" or "Raw XML access" sections below

Creating New Document

Use "Creating a new Word document" workflow

Editing Existing Document

• Your own document + simple changes Use "Basic OOXML editing" workflow

• Someone else's document Use "Redlining workflow" (recommended default)

• Legal, academic, business, or government docs Use "Redlining workflow" (required)

Reading and analyzing content

Text extraction

If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

Raw XML access

You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_directory>

Key file structures

• word/document.xml - Main document contents
• word/comments.xml - Comments referenced in document.xml
• word/media/ - Embedded images and media files
• Tracked changes use <w:ins> (insertions) and <w:del> (deletions) tags

Creating a new Word document

When creating a new Word document from scratch, use docx-js, which allows you to create Word documents using JavaScript/TypeScript.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read docx-js.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
3. Export as .docx using Packer.toBuffer()

Editing an existing Word document

When editing an existing Word document, use the Document library (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for the Document library API and XML patterns for directly editing document files.
2. Unpack the document: python ooxml/scripts/unpack.py <office_file> <output_directory>
3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
4. Pack the final document: python ooxml/scripts/pack.py <input_directory> <office_file>

The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.

Redlining workflow for document review

This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. CRITICAL: For complete tracked changes, you must implement ALL changes systematically.

Batching Strategy: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.

Principle: Minimal, Precise Edits When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the <w:r> element from the original and reusing it.

Example - Changing "30 days" to "60 days" in a sentence:

# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

Tracked changes workflow

1. Get markdown representation: Convert document to markdown with tracked changes preserved:

   pandoc --track-changes=all path-to-file.docx -o current.md
   

2. Identify and group changes: Review the document and identify ALL changes needed, organizing them into logical batches:

   Location methods (for finding changes in XML):

   • Section/heading numbers (e.g., "Section 3.2", "Article IV")
   • Paragraph identifiers if numbered
   • Grep patterns with unique surrounding text
   • Document structure (e.g., "first paragraph", "signature block")
   • DO NOT use markdown line numbers - they don't map to XML structure

   Batch organization (group 3-10 related changes per batch):

   • By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
   • By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
   • By complexity: Start with simple text replacements, then tackle complex structural changes
   • Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"

3. Read documentation and unpack:

   • MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
   • Unpack the document: python ooxml/scripts/unpack.py <file.docx> <dir>
   • Note the suggested RSID: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.

4. Implement changes in batches: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:

   • Makes debugging easier (smaller batch = easier to isolate errors)
   • Allows incremental progress
   • Maintains efficiency (batch size of 3-10 changes works well)

   Suggested batch groupings:

   • By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
   • By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
   • By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")

   For each batch of related changes:

   a. Map text to XML: Grep for text in word/document.xml to verify how text is split across <w:r> elements.

   b. Create and run script: Use get_node to find nodes, implement changes, then doc.save(). See "Document Library" section in ooxml.md for patterns.

   Note: Always grep word/document.xml immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.

5. Pack the document: After all batches are complete, convert the unpacked directory back to .docx:

   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   

6. Final verification: Do a comprehensive check of the complete document:

   • Convert final document to markdown:

     pandoc --track-changes=all reviewed-document.docx -o verification.md
     

   • Verify ALL changes were applied correctly:

     grep "original phrase" verification.md  # Should NOT find it
     grep "replacement phrase" verification.md  # Should find it
     

   • Check that no unintended changes were introduced

Converting Documents to Images

To visually analyze Word documents, convert them to images using a two-step process:

1. Convert DOCX to PDF:

   soffice --headless --convert-to pdf document.docx
   

2. Convert PDF pages to JPEG images:

   pdftoppm -jpeg -r 150 document.pdf page
   

   This creates files like page-1.jpg, page-2.jpg, etc.

Options:

• -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
• -jpeg: Output JPEG format (use -png for PNG if preferred)
• -f N: First page to convert (e.g., -f 2 starts from page 2)
• -l N: Last page to convert (e.g., -l 5 stops at page 5)
• page: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for DOCX operations:

• Write concise code
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

Dependencies

Required dependencies (install if not available):

• pandoc: sudo apt-get install pandoc (for text extraction)
• docx: npm install -g docx (for creating new documents)
• LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
• Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
• defusedxml: pip install defusedxml (for secure XML parsing)

PDF Processing Guide

Overview

This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see reference.md. If you need to fill out a PDF form, read forms.md and follow its instructions.

Quick Start

from pypdf import PdfReader, PdfWriter

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Extract text
text = ""
for page in reader.pages:
    text += page.extract_text()

Python Libraries

pypdf - Basic Operations

Merge PDFs

from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)

Split PDF

reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    writer = PdfWriter()
    writer.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as output:
        writer.write(output)

Extract Metadata

reader = PdfReader("document.pdf")
meta = reader.metadata
print(f"Title: {meta.title}")
print(f"Author: {meta.author}")
print(f"Subject: {meta.subject}")
print(f"Creator: {meta.creator}")

Rotate Pages

reader = PdfReader("input.pdf")
writer = PdfWriter()

page = reader.pages[0]
page.rotate(90)  # Rotate 90 degrees clockwise
writer.add_page(page)

with open("rotated.pdf", "wb") as output:
    writer.write(output)

pdfplumber - Text and Table Extraction

Extract Text with Layout

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)

Extract Tables

with pdfplumber.open("document.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            print(f"Table {j+1} on page {i+1}:")
            for row in table:
                print(row)

Advanced Table Extraction

import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        tables = page.extract_tables()
        for table in tables:
            if table:  # Check if table is not empty
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

# Combine all tables
if all_tables:
    combined_df = pd.concat(all_tables, ignore_index=True)
    combined_df.to_excel("extracted_tables.xlsx", index=False)

reportlab - Create PDFs

Basic PDF Creation

from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas

c = canvas.Canvas("hello.pdf", pagesize=letter)
width, height = letter

# Add text
c.drawString(100, height - 100, "Hello World!")
c.drawString(100, height - 120, "This is a PDF created with reportlab")

# Add a line
c.line(100, height - 140, 400, height - 140)

# Save
c.save()

Create PDF with Multiple Pages

from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate("report.pdf", pagesize=letter)
styles = getSampleStyleSheet()
story = []

# Add content
title = Paragraph("Report Title", styles['Title'])
story.append(title)
story.append(Spacer(1, 12))

body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
story.append(body)
story.append(PageBreak())

# Page 2
story.append(Paragraph("Page 2", styles['Heading1']))
story.append(Paragraph("Content for page 2", styles['Normal']))

# Build PDF
doc.build(story)

Command-Line Tools

pdftotext (poppler-utils)

# Extract text
pdftotext input.pdf output.txt

# Extract text preserving layout
pdftotext -layout input.pdf output.txt

# Extract specific pages
pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5

qpdf

# Merge PDFs
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf

# Split pages
qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
qpdf input.pdf --pages . 6-10 -- pages6-10.pdf

# Rotate pages
qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees

# Remove password
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

pdftk (if available)

# Merge
pdftk file1.pdf file2.pdf cat output merged.pdf

# Split
pdftk input.pdf burst

# Rotate
pdftk input.pdf rotate 1east output rotated.pdf

Common Tasks

Extract Text from Scanned PDFs

# Requires: pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

# Convert PDF to images
images = convert_from_path('scanned.pdf')

# OCR each page
text = ""
for i, image in enumerate(images):
    text += f"Page {i+1}:\n"
    text += pytesseract.image_to_string(image)
    text += "\n\n"

print(text)

Add Watermark

from pypdf import PdfReader, PdfWriter

# Create watermark (or load existing)
watermark = PdfReader("watermark.pdf").pages[0]

# Apply to all pages
reader = PdfReader("document.pdf")
writer = PdfWriter()

for page in reader.pages:
    page.merge_page(watermark)
    writer.add_page(page)

with open("watermarked.pdf", "wb") as output:
    writer.write(output)

Extract Images

# Using pdfimages (poppler-utils)
pdfimages -j input.pdf output_prefix

# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.

Password Protection

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()

for page in reader.pages:
    writer.add_page(page)

# Add password
writer.encrypt("userpassword", "ownerpassword")

with open("encrypted.pdf", "wb") as output:
    writer.write(output)

Quick Reference

Next Steps

• For advanced pypdfium2 usage, see reference.md
• For JavaScript libraries (pdf-lib), see reference.md
• If you need to fill out a PDF form, follow the instructions in forms.md
• For troubleshooting guides, see reference.md

PPTX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Reading and analyzing content

Text extraction

If you just need to read the text contents of a presentation, you should convert the document to markdown:

# Convert document to markdown
python -m markitdown path-to-file.pptx

Raw XML access

You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_dir>

Note: The unpack.py script is located at skills/pptx/ooxml/scripts/unpack.py relative to the project root. If the script doesn't exist at this path, use find . -name "unpack.py" to locate it.

Key file structures

• ppt/presentation.xml - Main presentation metadata and slide references
• ppt/slides/slide{N}.xml - Individual slide contents (slide1.xml, slide2.xml, etc.)
• ppt/notesSlides/notesSlide{N}.xml - Speaker notes for each slide
• ppt/comments/modernComment_*.xml - Comments for specific slides
• ppt/slideLayouts/ - Layout templates for slides
• ppt/slideMasters/ - Master slide templates
• ppt/theme/ - Theme and styling information
• ppt/media/ - Images and other media files

Typography and color extraction

When given an example design to emulate: Always analyze the presentation's typography and colors first using the methods below:

1. Read theme file: Check ppt/theme/theme1.xml for colors (<a:clrScheme>) and fonts (<a:fontScheme>)
2. Sample slide content: Examine ppt/slides/slide1.xml for actual font usage (<a:rPr>) and colors
3. Search for patterns: Use grep to find color (<a:solidFill>, <a:srgbClr>) and font references across all XML files

Creating a new PowerPoint presentation without a template

When creating a new PowerPoint presentation from scratch, use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.

Design Principles

CRITICAL: Before creating any presentation, analyze the content and choose appropriate design elements:

1. Consider the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
2. Check for branding: If the user mentions a company/organization, consider their brand colors and identity
3. Match palette to content: Select colors that reflect the subject
4. State your approach: Explain your design choices before writing code

Requirements:

• ✅ State your content-informed design approach BEFORE writing code
• ✅ Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
• ✅ Create clear visual hierarchy through size, weight, and color
• ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
• ✅ Be consistent: repeat patterns, spacing, and visual language across slides

Color Palette Selection

Choosing colors creatively:

• Think beyond defaults: What colors genuinely match this specific topic? Avoid autopilot choices.
• Consider multiple angles: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)
• Be adventurous: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy
• Build your palette: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)
• Ensure contrast: Text must be clearly readable on backgrounds

Example color palettes (use these to spark creativity - choose one, adapt it, or create your own):

1. Classic Blue: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
2. Teal & Coral: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
3. Bold Red: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
4. Warm Blush: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
5. Burgundy Luxury: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
6. Deep Purple & Emerald: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
7. Cream & Forest Green: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
8. Pink & Purple: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
9. Lime & Plum: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
10. Black & Gold: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
11. Sage & Terracotta: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
12. Charcoal & Red: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
13. Vibrant Orange: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
14. Forest Green: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
15. Retro Rainbow: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
16. Vintage Earthy: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
17. Coastal Rose: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
18. Orange & Turquoise: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)

Visual Details Options

Geometric Patterns:

• Diagonal section dividers instead of horizontal
• Asymmetric column widths (30/70, 40/60, 25/75)
• Rotated text headers at 90° or 270°
• Circular/hexagonal frames for images
• Triangular accent shapes in corners
• Overlapping shapes for depth

Border & Frame Treatments:

• Thick single-color borders (10-20pt) on one side only
• Double-line borders with contrasting colors
• Corner brackets instead of full frames
• L-shaped borders (top+left or bottom+right)
• Underline accents beneath headers (3-5pt thick)

Typography Treatments:

• Extreme size contrast (72pt headlines vs 11pt body)
• All-caps headers with wide letter spacing
• Numbered sections in oversized display type
• Monospace (Courier New) for data/stats/technical content
• Condensed fonts (Arial Narrow) for dense information
• Outlined text for emphasis

Chart & Data Styling:

• Monochrome charts with single accent color for key data
• Horizontal bar charts instead of vertical
• Dot plots instead of bar charts
• Minimal gridlines or none at all
• Data labels directly on elements (no legends)
• Oversized numbers for key metrics

Layout Innovations:

• Full-bleed images with text overlays
• Sidebar column (20-30% width) for navigation/context
• Modular grid systems (3×3, 4×4 blocks)
• Z-pattern or F-pattern content flow
• Floating text boxes over colored shapes
• Magazine-style multi-column layouts

Background Treatments:

• Solid color blocks occupying 40-60% of slide
• Gradient fills (vertical or diagonal only)
• Split backgrounds (two colors, diagonal or vertical)
• Edge-to-edge color bands
• Negative space as a design element

Layout Tips

When creating slides with charts or tables:

• Two-column layout (PREFERRED): Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.
• Full-slide layout: Let the featured content (chart/table) take up the entire slide for maximum impact and readability
• NEVER vertically stack: Do not place charts/tables below text in a single column - this causes poor readability and layout issues

Workflow

1. MANDATORY - READ ENTIRE FILE: Read html2pptx.md completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.
2. Create an HTML file for each slide with proper dimensions (e.g., 720pt × 405pt for 16:9)
   • Use <p>, <h1>-<h6>, <ul>, <ol> for all text content
   • Use class="placeholder" for areas where charts/tables will be added (render with gray background for visibility)
   • CRITICAL: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML
   • LAYOUT: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability
3. Create and run a JavaScript file using the html2pptx.js library to convert HTML slides to PowerPoint and save the presentation
   • Use the html2pptx() function to process each HTML file
   • Add charts and tables to placeholder areas using PptxGenJS API
   • Save the presentation using pptx.writeFile()
4. Visual validation: Generate thumbnails and inspect for layout issues
   • Create thumbnail grid: python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
   • Read and carefully examine the thumbnail image for:
     • Text cutoff: Text being cut off by header bars, shapes, or slide edges
     • Text overlap: Text overlapping with other text or shapes
     • Positioning issues: Content too close to slide boundaries or other elements
     • Contrast issues: Insufficient contrast between text and backgrounds
   • If issues found, adjust HTML margins/spacing/colors and regenerate the presentation
   • Repeat until all slides are visually correct

Editing an existing PowerPoint presentation

When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.
2. Unpack the presentation: python ooxml/scripts/unpack.py <office_file> <output_dir>
3. Edit the XML files (primarily ppt/slides/slide{N}.xml and related files)
4. CRITICAL: Validate immediately after each edit and fix any validation errors before proceeding: python ooxml/scripts/validate.py <dir> --original <file>
5. Pack the final presentation: python ooxml/scripts/pack.py <input_directory> <office_file>

Creating a new PowerPoint presentation using a template

When you need to create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.

Workflow

1. Extract template text AND create visual thumbnail grid:

   • Extract text: python -m markitdown template.pptx > template-content.md
   • Read template-content.md: Read the entire file to understand the contents of the template presentation. NEVER set any range limits when reading this file.
   • Create thumbnail grids: python scripts/thumbnail.py template.pptx
   • See Creating Thumbnail Grids section for more details

2. Analyze template and save inventory to a file:

   • Visual Analysis: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure
   • Create and save a template inventory file at template-inventory.md containing:

     # Template Inventory Analysis
     **Total Slides: [count]**
     **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**
     
     ## [Category Name]
     - Slide 0: [Layout code if available] - Description/purpose
     - Slide 1: [Layout code] - Description/purpose
     - Slide 2: [Layout code] - Description/purpose
     [... EVERY slide must be listed individually with its index ...]
     

   • Using the thumbnail grid: Reference the visual thumbnails to identify:
     • Layout patterns (title slides, content layouts, section dividers)
     • Image placeholder locations and counts
     • Design consistency across slide groups
     • Visual hierarchy and structure
   • This inventory file is REQUIRED for selecting appropriate templates in the next step

3. Create presentation outline based on template inventory:

   • Review available templates from step 2.
   • Choose an intro or title template for the first slide. This should be one of the first templates.
   • Choose safe, text-based layouts for the other slides.
   • CRITICAL: Match layout structure to actual content:
     • Single-column layouts: Use for unified narrative or single topic
     • Two-column layouts: Use ONLY when you have exactly 2 distinct items/concepts
     • Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts
     • Image + text layouts: Use ONLY when you have actual images to insert
     • Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis
     • Never use layouts with more placeholders than you have content
     • If you have 2 items, don't force them into a 3-column layout
     • If you have 4+ items, consider breaking into multiple slides or using a list format
   • Count your actual content pieces BEFORE selecting the layout
   • Verify each placeholder in the chosen layout will be filled with meaningful content
   • Select one option representing the best layout for each content section.
   • Save outline.md with content AND template mapping that leverages available designs
   • Example template mapping:

     # Template slides to use (0-based indexing)
     # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
     # Mapping: slide numbers from outline -> template slide indices
     template_mapping = [
         0,   # Use slide 0 (Title/Cover)
         34,  # Use slide 34 (B1: Title and body)
         34,  # Use slide 34 again (duplicate for second B1)
         50,  # Use slide 50 (E1: Quote)
         54,  # Use slide 54 (F2: Closing + Text)
     ]
     

4. Duplicate, reorder, and delete slides using rearrange.py:

   • Use the scripts/rearrange.py script to create a new presentation with slides in the desired order:

     python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
     

   • The script handles duplicating repeated slides, deleting unused slides, and reordering automatically
   • Slide indices are 0-based (first slide is 0, second is 1, etc.)
   • The same slide index can appear multiple times to duplicate that slide

5. Extract ALL text using the inventory.py script:

   • Run inventory extraction:

     python scripts/inventory.py working.pptx text-inventory.json
     

   • Read text-inventory.json: Read the entire text-inventory.json file to understand all shapes and their properties. NEVER set any range limits when reading this file.

   • The inventory JSON structure:

       {
         "slide-0": {
           "shape-0": {
             "placeholder_type": "TITLE",  // or null for non-placeholders
             "left": 1.5,                  // position in inches
             "top": 2.0,
             "width": 7.5,
             "height": 1.2,
             "paragraphs": [
               {
                 "text": "Paragraph text",
                 // Optional properties (only included when non-default):
                 "bullet": true,           // explicit bullet detected
                 "level": 0,               // only included when bullet is true
                 "alignment": "CENTER",    // CENTER, RIGHT (not LEFT)
                 "space_before": 10.0,     // space before paragraph in points
                 "space_after": 6.0,       // space after paragraph in points
                 "line_spacing": 22.4,     // line spacing in points
                 "font_name": "Arial",     // from first run
                 "font_size": 14.0,        // in points
                 "bold": true,
                 "italic": false,
                 "underline": false,
                 "color": "FF0000"         // RGB color
               }
             ]
           }
         }
       }
     

   • Key features:

     • Slides: Named as "slide-0", "slide-1", etc.
     • Shapes: Ordered by visual position (top-to-bottom, left-to-right) as "shape-0", "shape-1", etc.
     • Placeholder types: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
     • Default font size: default_font_size in points extracted from layout placeholders (when available)
     • Slide numbers are filtered: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory
     • Bullets: When bullet: true, level is always included (even if 0)
     • Spacing: space_before, space_after, and line_spacing in points (only included when set)
     • Colors: color for RGB (e.g., "FF0000"), theme_color for theme colors (e.g., "DARK_1")
     • Properties: Only non-default values are included in the output

6. Generate replacement text and save the data to a JSON file Based on the text inventory from the previous step:

   • CRITICAL: First verify which shapes exist in the inventory - only reference shapes that are actually present
   • VALIDATION: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory
     • If you reference a non-existent shape, you'll get an error showing available shapes
     • If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist
     • All validation errors are shown at once before the script exits
   • IMPORTANT: The replace.py script uses inventory.py internally to identify ALL text shapes
   • AUTOMATIC CLEARING: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them
   • Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")
   • Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically
   • Paragraphs with bullets will be automatically left aligned. Don't set the alignment property on when "bullet": true
   • Generate appropriate replacement content for placeholder text
   • Use shape size to determine appropriate content length
   • CRITICAL: Include paragraph properties from the original inventory - don't just provide text
   • IMPORTANT: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically
   • ESSENTIAL FORMATTING RULES:
     • Headers/titles should typically have "bold": true
     • List items should have "bullet": true, "level": 0 (level is required when bullet is true)
     • Preserve any alignment properties (e.g., "alignment": "CENTER" for centered text)
     • Include font properties when different from default (e.g., "font_size": 14.0, "font_name": "Lora")
     • Colors: Use "color": "FF0000" for RGB or "theme_color": "DARK_1" for theme colors
     • The replacement script expects properly formatted paragraphs, not just text strings
     • Overlapping shapes: Prefer shapes with larger default_font_size or more appropriate placeholder_type
   • Save the updated inventory with replacements to replacement-text.json
   • WARNING: Different template layouts have different shape counts - always check the actual inventory before creating replacements

   Example paragraphs field showing proper formatting:

   "paragraphs": [
     {
       "text": "New presentation title text",
       "alignment": "CENTER",
       "bold": true
     },
     {
       "text": "Section Header",
       "bold": true
     },
     {
       "text": "First bullet point without bullet symbol",
       "bullet": true,
       "level": 0
     },
     {
       "text": "Red colored text",
       "color": "FF0000"
     },
     {
       "text": "Theme colored text",
       "theme_color": "DARK_1"
     },
     {
       "text": "Regular paragraph text without special formatting"
     }
   ]
   

   Shapes not listed in the replacement JSON are automatically cleared:

   {
     "slide-0": {
       "shape-0": {
         "paragraphs": [...] // This shape gets new text
       }
       // shape-1 and shape-2 from inventory will be cleared automatically
     }
   }
   

   Common formatting patterns for presentations:

   • Title slides: Bold text, sometimes centered
   • Section headers within slides: Bold text
   • Bullet lists: Each item needs "bullet": true, "level": 0
   • Body text: Usually no special properties needed
   • Quotes: May have special alignment or font properties

7. Apply replacements using the replace.py script

   python scripts/replace.py working.pptx replacement-text.json output.pptx
   

   The script will:

   • First extract the inventory of ALL text shapes using functions from inventory.py
   • Validate that all shapes in the replacement JSON exist in the inventory
   • Clear text from ALL shapes identified in the inventory
   • Apply new text only to shapes with "paragraphs" defined in the replacement JSON
   • Preserve formatting by applying paragraph properties from the JSON
   • Handle bullets, alignment, font properties, and colors automatically
   • Save the updated presentation

   Example validation errors:

   ERROR: Invalid shapes in replacement JSON:
     - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
     - Slide 'slide-999' not found in inventory
   

   ERROR: Replacement text made overflow worse in these shapes:
     - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
   

Creating Thumbnail Grids

To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:

python scripts/thumbnail.py template.pptx [output_prefix]

Features:

• Creates: thumbnails.jpg (or thumbnails-1.jpg, thumbnails-2.jpg, etc. for large decks)
• Default: 5 columns, max 30 slides per grid (5×6)
• Custom prefix: python scripts/thumbnail.py template.pptx my-grid
  • Note: The output prefix should include the path if you want output in a specific directory (e.g., workspace/my-grid)
• Adjust columns: --cols 4 (range: 3-6, affects slides per grid)
• Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
• Slides are zero-indexed (Slide 0, Slide 1, etc.)

Use cases:

• Template analysis: Quickly understand slide layouts and design patterns
• Content review: Visual overview of entire presentation
• Navigation reference: Find specific slides by their visual appearance
• Quality check: Verify all slides are properly formatted

Examples:

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combine options: custom name, columns
python scripts/thumbnail.py template.pptx analysis --cols 4

Converting Slides to Images

To visually analyze PowerPoint slides, convert them to images using a two-step process:

1. Convert PPTX to PDF:

   soffice --headless --convert-to pdf template.pptx
   

2. Convert PDF pages to JPEG images:

   pdftoppm -jpeg -r 150 template.pdf slide
   

   This creates files like slide-1.jpg, slide-2.jpg, etc.

Options:

• -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
• -jpeg: Output JPEG format (use -png for PNG if preferred)
• -f N: First page to convert (e.g., -f 2 starts from page 2)
• -l N: Last page to convert (e.g., -l 5 stops at page 5)
• slide: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for PPTX operations:

• Write concise code
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

Dependencies

Required dependencies (should already be installed):

• markitdown: pip install "markitdown[pptx]" (for text extraction from presentations)
• pptxgenjs: npm install -g pptxgenjs (for creating presentations via html2pptx)
• playwright: npm install -g playwright (for HTML rendering in html2pptx)
• react-icons: npm install -g react-icons react react-dom (for icons)
• sharp: npm install -g sharp (for SVG rasterization and image processing)
• LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
• Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
• defusedxml: pip install defusedxml (for secure XML parsing)

Requirements for Outputs

All Excel files

Zero Formula Errors

• Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)

Preserve Existing Templates (when updating templates)

• Study and EXACTLY match existing format, style, and conventions when modifying files
• Never impose standardized formatting on files with established patterns
• Existing template conventions ALWAYS override these guidelines

Financial models

Color Coding Standards

Unless otherwise stated by the user or existing template

Industry-Standard Color Conventions

• Blue text (RGB: 0,0,255): Hardcoded inputs, and numbers users will change for scenarios
• Black text (RGB: 0,0,0): ALL formulas and calculations
• Green text (RGB: 0,128,0): Links pulling from other worksheets within same workbook
• Red text (RGB: 255,0,0): External links to other files
• Yellow background (RGB: 255,255,0): Key assumptions needing attention or cells that need to be updated

Number Formatting Standards

Required Format Rules

• Years: Format as text strings (e.g., "2024" not "2,024")
• Currency: Use $#,##0 format; ALWAYS specify units in headers ("Revenue ($mm)")
• Zeros: Use number formatting to make all zeros "-", including percentages (e.g., "$#,##0;($#,##0);-")
• Percentages: Default to 0.0% format (one decimal)
• Multiples: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)
• Negative numbers: Use parentheses (123) not minus -123

Formula Construction Rules

Assumptions Placement

• Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells
• Use cell references instead of hardcoded values in formulas
• Example: Use =B5*(1+$B$6) instead of =B5*1.05

Formula Error Prevention

• Verify all cell references are correct
• Check for off-by-one errors in ranges
• Ensure consistent formulas across all projection periods
• Test with edge cases (zero values, negative numbers)
• Verify no unintended circular references

Documentation Requirements for Hardcodes

• Comment or in cells beside (if end of table). Format: "Source: [System/Document], [Date], [Specific Reference], [URL if applicable]"
• Examples:
  • "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"
  • "Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]"
  • "Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity"
  • "Source: FactSet, 8/20/2025, Consensus Estimates Screen"

XLSX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.

Important Requirements

LibreOffice Required for Formula Recalculation: You can assume LibreOffice is installed for recalculating formula values using the recalc.py script. The script automatically configures LibreOffice on first run

Reading and analyzing data

Data analysis with pandas

For data analysis, visualization, and basic operations, use pandas which provides powerful data manipulation capabilities:

import pandas as pd

# Read Excel
df = pd.read_excel('file.xlsx')  # Default: first sheet
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict

# Analyze
df.head()      # Preview data
df.info()      # Column info
df.describe()  # Statistics

# Write Excel
df.to_excel('output.xlsx', index=False)

Excel File Workflows

CRITICAL: Use Formulas, Not Hardcoded Values

Always use Excel formulas instead of calculating values in Python and hardcoding them. This ensures the spreadsheet remains dynamic and updateable.

❌ WRONG - Hardcoding Calculated Values

# Bad: Calculating in Python and hardcoding result
total = df['Sales'].sum()
sheet['B10'] = total  # Hardcodes 5000

# Bad: Computing growth rate in Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth  # Hardcodes 0.15

# Bad: Python calculation for average
avg = sum(values) / len(values)
sheet['D20'] = avg  # Hardcodes 42.5

✅ CORRECT - Using Excel Formulas

# Good: Let Excel calculate the sum
sheet['B10'] = '=SUM(B2:B9)'

# Good: Growth rate as Excel formula
sheet['C5'] = '=(C4-C2)/C2'

# Good: Average using Excel function
sheet['D20'] = '=AVERAGE(D2:D19)'

This applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.

Common Workflow

1. Choose tool: pandas for data, openpyxl for formulas/formatting
2. Create/Load: Create new workbook or load existing file
3. Modify: Add/edit data, formulas, and formatting
4. Save: Write to file
5. Recalculate formulas (MANDATORY IF USING FORMULAS): Use the recalc.py script

   python recalc.py output.xlsx
   

6. Verify and fix any errors:
   • The script returns JSON with error details
   • If status is errors_found, check error_summary for specific error types and locations
   • Fix the identified errors and recalculate again
   • Common errors to fix:
     • #REF!: Invalid cell references
     • #DIV/0!: Division by zero
     • #VALUE!: Wrong data type in formula
     • #NAME?: Unrecognized formula name

Creating new Excel files

# Using openpyxl for formulas and formatting
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

# Add data
sheet['A1'] = 'Hello'
sheet['B1'] = 'World'
sheet.append(['Row', 'of', 'data'])

# Add formula
sheet['B2'] = '=SUM(A1:A10)'

# Formatting
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')

# Column width
sheet.column_dimensions['A'].width = 20

wb.save('output.xlsx')

Editing existing Excel files

# Using openpyxl to preserve formulas and formatting
from openpyxl import load_workbook

# Load existing file
wb = load_workbook('existing.xlsx')
sheet = wb.active  # or wb['SheetName'] for specific sheet

# Working with multiple sheets
for sheet_name in wb.sheetnames:
    sheet = wb[sheet_name]
    print(f"Sheet: {sheet_name}")

# Modify cells
sheet['A1'] = 'New Value'
sheet.insert_rows(2)  # Insert row at position 2
sheet.delete_cols(3)  # Delete column 3

# Add new sheet
new_sheet = wb.create_sheet('NewSheet')
new_sheet['A1'] = 'Data'

wb.save('modified.xlsx')

Recalculating formulas

Excel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided recalc.py script to recalculate formulas:

python recalc.py <excel_file> [timeout_seconds]

Example:

python recalc.py output.xlsx 30

The script:

• Automatically sets up LibreOffice macro on first run
• Recalculates all formulas in all sheets
• Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)
• Returns JSON with detailed error locations and counts
• Works on both Linux and macOS

Formula Verification Checklist

Quick checks to ensure formulas work correctly:

Essential Verification

• Test 2-3 sample references: Verify they pull correct values before building full model
• Column mapping: Confirm Excel columns match (e.g., column 64 = BL, not BK)
• Row offset: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)

Common Pitfalls

• NaN handling: Check for null values with pd.notna()
• Far-right columns: FY data often in columns 50+
• Multiple matches: Search all occurrences, not just first
• Division by zero: Check denominators before using / in formulas (#DIV/0!)
• Wrong references: Verify all cell references point to intended cells (#REF!)
• Cross-sheet references: Use correct format (Sheet1!A1) for linking sheets

Formula Testing Strategy

• Start small: Test formulas on 2-3 cells before applying broadly
• Verify dependencies: Check all cells referenced in formulas exist
• Test edge cases: Include zero, negative, and very large values

Interpreting recalc.py Output

The script returns JSON with error details:

{
  "status": "success",           // or "errors_found"
  "total_errors": 0,              // Total error count
  "total_formulas": 42,           // Number of formulas in file
  "error_summary": {              // Only present if errors found
    "#REF!": {
      "count": 2,
      "locations": ["Sheet1!B5", "Sheet1!C10"]
    }
  }
}

Best Practices

Library Selection

• pandas: Best for data analysis, bulk operations, and simple data export
• openpyxl: Best for complex formatting, formulas, and Excel-specific features

Working with openpyxl

• Cell indices are 1-based (row=1, column=1 refers to cell A1)
• Use data_only=True to read calculated values: load_workbook('file.xlsx', data_only=True)
• Warning: If opened with data_only=True and saved, formulas are replaced with values and permanently lost
• For large files: Use read_only=True for reading or write_only=True for writing
• Formulas are preserved but not evaluated - use recalc.py to update values

Working with pandas

• Specify data types to avoid inference issues: pd.read_excel('file.xlsx', dtype={'id': str})
• For large files, read specific columns: pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])
• Handle dates properly: pd.read_excel('file.xlsx', parse_dates=['date_column'])

Code Style Guidelines

IMPORTANT: When generating Python code for Excel operations:

• Write minimal, concise Python code without unnecessary comments
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

For Excel files themselves:

• Add comments to cells with complex formulas or important assumptions
• Document data sources for hardcoded values
• Include notes for key calculations and model sections

Frontend Enhancer

Overview

The Frontend Enhancer skill transforms Next.js applications into visually stunning, modern web experiences. It provides production-ready components, comprehensive design guidelines, curated color palettes, smooth animations, and flexible layout templates optimized for responsiveness and accessibility.

When to Use This Skill

Invoke this skill when:

• Improving the visual appearance of an existing application
• Creating new UI components with modern styling
• Selecting color schemes and design themes
• Adding animations and transitions
• Building responsive layouts for different screen sizes
• Implementing hero sections, feature grids, or landing pages
• Enhancing user experience with better visual hierarchy
• Applying consistent design patterns across an application

Core Capabilities

1. Component Library

Use pre-built, production-ready React components with multiple variants and states:

Button Component (assets/button-variants.tsx):

• Variants: primary, secondary, outline, ghost, danger
• Sizes: sm, md, lg
• Loading states with animated spinner
• Full TypeScript support
• Accessibility features built-in

Card Component (assets/card-variants.tsx):

• Variants: default, bordered, elevated, interactive
• Subcomponents: CardHeader, CardTitle, CardDescription, CardContent, CardFooter
• Hover effects and transitions
• Flexible padding options

Input Components (assets/input-variants.tsx):

• Text inputs with validation states
• Textarea component
• Left/right icon support
• Error and helper text display
• Label integration
• Full accessibility support

Implementation workflow:

1. Copy the desired component file from assets/ to your project's components directory
2. Ensure the cn utility function exists (see assets/utils-cn.ts)
3. Customize colors, spacing, or variants to match your brand
4. Import and use the component in your pages

2. Layout Templates

Use pre-designed, responsive layout patterns for common page sections:

Hero Section (assets/layout-hero-section.tsx):

• Three variants: centered, split, minimal
• Support for CTAs (primary and secondary)
• Optional background gradients
• Image/illustration support
• Built-in animations

Feature Grid (assets/layout-feature-grid.tsx):

• Configurable columns (2, 3, or 4)
• Icon integration
• Staggered animations
• Hover effects
• Fully responsive

Implementation workflow:

1. Copy the layout component from assets/ to your components directory
2. Customize the props and content to match your needs
3. Integrate with your existing pages
4. Adjust styling as needed for your brand

3. Design System Guidelines

Reference comprehensive design principles for consistent, professional interfaces:

Design Principles (references/design_principles.md):

• Visual hierarchy best practices
• Spacing and rhythm guidelines
• Typography recommendations
• Color theory and usage
• Consistency standards
• Responsiveness strategies
• Accessibility guidelines (WCAG AA/AAA)
• Common layout patterns

When to reference:

• Starting a new design
• Making decisions about visual hierarchy
• Ensuring accessibility compliance
• Establishing consistency across the app
• Reviewing design quality

How to use: Read references/design_principles.md to understand best practices, then apply them to your specific design challenges. The document covers both theory and practical implementation.

4. Color Palettes

Access professionally curated color schemes optimized for modern web applications:

Available Palettes (references/color_palettes.md):

1. Corporate Blue - Professional, trustworthy (business apps, SaaS)
2. Vibrant Purple - Creative, modern (creative tools, portfolios)
3. Minimalist Gray - Clean, sophisticated (minimalist designs)
4. Warm Sunset - Energetic, friendly (consumer apps, e-commerce)
5. Ocean Fresh - Calm, professional (health, finance apps)
6. Dark Mode - Modern, eye-friendly (developer tools, dashboards)

Each palette includes:

• Primary and secondary colors
• Accent colors
• Background and surface colors
• Text colors (primary and secondary)
• Semantic colors (success, warning, error)
• Border colors

Implementation options:

1. Tailwind CSS: Add colors to tailwind.config.js (examples provided)
2. CSS Variables: Use custom properties in global CSS (examples provided)
3. Inline styles: Reference hex codes directly in components

Selection workflow:

1. Review references/color_palettes.md to see all available palettes
2. Consider your application's purpose and brand identity
3. Choose a palette that matches your goals
4. Implement using Tailwind config or CSS variables
5. Adjust specific colors if needed to match your brand

5. Animations and Transitions

Add smooth, professional animations using pre-built CSS classes and keyframes:

Animation Library (assets/animations.css):

• Fade animations (fadeIn, fadeOut, fadeInUp, fadeInDown)
• Slide animations (slideInLeft, slideInRight)
• Scale animations (scaleIn, scaleOut)
• Utility animations (bounce, pulse, spin)
• Skeleton loading (shimmer effect)
• Hover effects (lift, glow, scale)
• Stagger delays for list animations

Accessibility: All animations respect prefers-reduced-motion for accessibility compliance.

Implementation workflow:

1. Copy assets/animations.css to your global CSS file (or create a separate animations file)
2. Apply utility classes like animate-fade-in-up, hover-lift, etc.
3. Use stagger classes for sequential animations in lists
4. Customize duration and easing if needed

Best practices:

• Keep animations subtle (200-300ms for micro-interactions)
• Use animations to guide user attention
• Avoid excessive motion that distracts
• Always test with prefers-reduced-motion enabled

Enhancement Workflow

Follow this systematic approach when enhancing a frontend application:

Step 1: Assess Current State

• Identify areas lacking visual polish
• Note inconsistent styling patterns
• Check responsive behavior
• Review accessibility issues
• Evaluate color scheme and typography

Step 2: Select Design Direction

• Choose a color palette from references/color_palettes.md
• Review design principles in references/design_principles.md
• Decide on component variants and styles
• Plan layout improvements

Step 3: Implement Foundation

• Set up the cn utility function (assets/utils-cn.ts)
• Configure chosen color palette (Tailwind or CSS variables)
• Add animation CSS (assets/animations.css) to global styles
• Ensure consistent spacing scale

Step 4: Apply Components

• Replace basic elements with enhanced components from assets/
• Implement layout templates for key pages
• Apply consistent styling across the application
• Add animations and transitions

Step 5: Refine and Polish

• Test responsiveness across device sizes
• Verify accessibility (keyboard navigation, contrast, screen readers)
• Ensure consistent hover/focus states
• Optimize performance (check animation performance)
• Test with prefers-reduced-motion

Step 6: Final Review

• Check visual hierarchy on all pages
• Verify color consistency
• Test all interactive states
• Validate responsive breakpoints
• Review accessibility compliance

Utility Function Setup

Most components require the cn utility function for class name merging. To set it up:

1. Copy assets/utils-cn.ts to your project's lib/utils.ts
2. Install dependencies:

   npm install clsx tailwind-merge
   

3. Import in components:

   import { cn } from '@/lib/utils';
   

Responsive Design Strategy

All components and layouts follow a mobile-first approach:

1. Base styles - Optimized for mobile (320px+)
2. sm breakpoint - Small tablets (640px+)
3. md breakpoint - Tablets (768px+)
4. lg breakpoint - Desktops (1024px+)
5. xl breakpoint - Large desktops (1280px+)

Test each breakpoint to ensure proper layout and readability.

Accessibility Checklist

Ensure all enhanced interfaces meet these standards:

• Color contrast meets WCAG AA (4.5:1 for text)
• All interactive elements are keyboard accessible
• Focus indicators are visible and clear
• Semantic HTML is used (nav, main, article, etc.)
• Images have alt text
• Forms have proper labels
• Animations respect prefers-reduced-motion
• Touch targets are at least 44x44px

Customization Guide

To adapt components and templates to your brand:

1. Colors: Update color values in palette config or component files
2. Typography: Adjust font sizes, weights, and families
3. Spacing: Modify padding and margin values
4. Border Radius: Change rounded corners (e.g., rounded-lg to rounded-xl)
5. Shadows: Adjust shadow intensity (e.g., shadow-md to shadow-lg)
6. Animations: Modify duration and easing functions

Resources Summary

This skill includes:

references/

• color_palettes.md - Six professionally designed color schemes with implementation examples
• design_principles.md - Comprehensive design guidelines covering visual hierarchy, typography, accessibility, and common patterns

assets/

• button-variants.tsx - Modern button component with 5 variants and 3 sizes
• card-variants.tsx - Flexible card component with subcomponents
• input-variants.tsx - Input and textarea components with validation states
• layout-hero-section.tsx - Hero section with 3 layout variants
• layout-feature-grid.tsx - Responsive feature grid with configurable columns
• animations.css - Complete animation library with accessibility support
• utils-cn.ts - Utility function for class name merging

Tips for Success

1. Start with a plan: Review design principles before making changes
2. Choose one palette: Stick to a single color scheme for consistency
3. Test on real devices: Emulators don't always show true responsive behavior
4. Keep it simple: Modern design favors simplicity over complexity
5. Prioritize accessibility: Design for all users from the start
6. Iterate based on feedback: Show designs to users and refine
7. Maintain consistency: Use the same patterns throughout your application
8. Performance matters: Keep animations smooth (60fps) and optimize images

Common Use Cases

Enhancing an Existing App

1. Select a color palette and implement it
2. Replace basic buttons/inputs with enhanced components
3. Add subtle animations to improve feedback
4. Review and improve spacing consistency
5. Ensure responsive behavior across devices

Building a Landing Page

1. Use hero section layout as the focal point
2. Add feature grid to showcase key features
3. Implement consistent button styles for CTAs
4. Add staggered animations for visual interest
5. Test responsiveness thoroughly

Creating a Dashboard

1. Use card components for data sections
2. Implement consistent spacing and hierarchy
3. Choose a professional color palette
4. Add skeleton loaders for data fetching
5. Ensure touch-friendly controls on mobile

Redesigning Forms

1. Replace inputs with enhanced input components
2. Add clear error and validation states
3. Ensure proper label associations
4. Implement loading states for submission
5. Test keyboard navigation flow

Nutritional Specialist

Overview

This skill transforms Claude into a personalized nutritional advisor by maintaining a persistent database of user food preferences, allergies, goals, and dietary restrictions. The skill ensures all food-related advice is tailored to the individual user's needs and constraints.

When to Use This Skill

Invoke this skill for any food-related query, including:

• Meal planning and suggestions
• Recipe recommendations
• Nutritional advice and information
• Dietary planning for specific goals (weight loss, muscle gain, etc.)
• Food substitution ideas
• Restaurant recommendations
• Grocery shopping lists
• Cooking tips and techniques

Workflow

Step 1: Check for Existing Preferences

Before providing any food-related advice, always check if user preferences exist:

python3 scripts/preferences_manager.py has

If the output is "false", proceed to Step 2 (Initial Setup). If "true", proceed to Step 3 (Load Preferences).

Step 2: Initial Setup (First Run Only)

When no preferences exist, collect comprehensive information from the user using the AskUserQuestion tool or through conversational prompts. Gather the following information:

Essential Information:

1. Dietary Goals: What are the primary nutritional or health goals? (e.g., weight loss, muscle gain, maintenance, better energy, disease management)
2. Allergies: Any food allergies that must be strictly avoided?
3. Dietary Restrictions: Any dietary restrictions or philosophies? (vegetarian, vegan, halal, kosher, low-carb, keto, paleo, etc.)
4. Dislikes: Foods or ingredients strongly disliked
5. Preferences: Favorite foods, cuisines, or ingredients

Optional Information: 6. Health Conditions: Any health conditions affecting diet? (diabetes, hypertension, IBS, celiac, etc.) 7. Cuisine Preferences: Preferred or avoided cuisines 8. Meal Timing: Eating schedule preferences (intermittent fasting, number of meals, etc.) 9. Cooking Skill Level: Beginner, intermediate, or advanced 10. Budget Considerations: Any budget constraints 11. Additional Notes: Any other relevant information

Collecting Preferences:

Use a conversational, friendly approach to gather this information. Frame the questions in an engaging way:

Example approach:

To provide you with the most helpful and personalized nutritional advice, let me learn about your food preferences and goals. This will help me tailor all my recommendations specifically to you.

Let's start with the essentials:
1. What are your main dietary or health goals?
2. Do you have any food allergies I should be aware of?
3. Do you follow any dietary restrictions or philosophies?
4. Are there any foods you really dislike?
5. What are some of your favorite foods or cuisines?

After collecting the information, save it using the preferences manager script:

import json
import subprocess

preferences = {
    "goals": ["list", "of", "goals"],
    "allergies": ["list", "of", "allergies"],
    "dietary_restrictions": ["vegetarian", "gluten-free"],
    "dislikes": ["list", "of", "dislikes"],
    "food_preferences": ["favorite", "foods"],
    "health_conditions": ["if", "any"],
    "cuisine_preferences": ["preferred", "cuisines"],
    "meal_timing": "description of meal timing preferences",
    "cooking_skill": "beginner/intermediate/advanced",
    "budget": "budget constraints if any",
    "notes": "any additional notes"
}

# Save using Python's subprocess
import subprocess
result = subprocess.run(
    ["python3", "scripts/preferences_manager.py", "set"],
    input=json.dumps(preferences),
    capture_output=True,
    text=True,
    cwd="[SKILL_DIR]"
)

Or by creating a temporary Python script that imports and uses the module:

import sys
sys.path.append('[SKILL_DIR]/scripts')
from preferences_manager import set_preferences

preferences = {
    # ... preference data as shown above
}

set_preferences(preferences)

Replace [SKILL_DIR] with the actual path to the skill directory.

After saving, confirm with the user:

Great! I've saved your preferences. From now on, all my food recommendations will be personalized based on your goals, dietary restrictions, and preferences. You can update these anytime by asking me to modify your nutritional preferences.

Step 3: Load and Use Preferences

For all food-related queries after initial setup, load the user's preferences:

python3 scripts/preferences_manager.py get

Or display in a readable format:

python3 scripts/preferences_manager.py display

Apply Preferences to Responses:

Every food-related response must:

1. Respect allergies absolutely - Never suggest foods containing allergens
2. Align with dietary restrictions - Only suggest appropriate foods
3. Consider goals - Tailor advice to support the user's objectives
4. Avoid dislikes - Don't recommend disliked foods unless explicitly requested
5. Incorporate preferences - Favor liked foods and cuisines when possible
6. Reference health conditions - Adjust recommendations accordingly

Example Application:

User query: "What should I have for lunch?"

Without preferences: Generic lunch suggestions

With preferences (e.g., vegan, nut allergy, weight loss goal, loves Mediterranean food):

Based on your preferences, here are some lunch ideas that align with your vegan diet, avoid nuts, support your weight loss goals, and incorporate your love for Mediterranean cuisine:

1. Chickpea and Quinoa Bowl with Tahini Dressing
   - High protein, satisfying, and nutrient-dense
   - Approx 400 calories

2. Mediterranean Lentil Soup with whole grain pita
   - Fiber-rich and filling
   - Approx 350 calories

3. Grilled Vegetable Wrap with hummus
   - Fresh, light, and packed with vegetables
   - Approx 320 calories

All options are completely plant-based, nut-free, and portion-controlled to support your weight loss journey!

Step 4: Updating Preferences

When users want to update their preferences, use the same script:

python3 scripts/preferences_manager.py get

Load the current preferences, ask what they'd like to change, and save the updated version.

For complete reset:

python3 scripts/preferences_manager.py reset

Then proceed with the initial setup again.

Best Practices

1. Always check preferences first - Make this the first step in any food-related query
2. Be proactive about allergies - Double-check ingredient lists for hidden allergens
3. Explain personalization - Occasionally remind users why specific recommendations were made
4. Offer alternatives - Provide multiple options when possible
5. Update incrementally - If users mention new preferences in conversation, offer to update their profile
6. Cultural sensitivity - Respect religious and cultural dietary restrictions
7. Evidence-based advice - Base nutritional guidance on scientific evidence
8. Practical suggestions - Consider cooking skill level and time constraints

Example Interactions

Example 1: First-time user

User: "Can you suggest a healthy dinner recipe?"

Claude: [Checks preferences - finds none]

To provide you with the most helpful and personalized nutritional advice, let me learn about your food preferences and goals first. This will help me tailor all my recommendations specifically to you.

Let's start with the essentials:
1. What are your main dietary or health goals?
2. Do you have any food allergies I should be aware of?
3. Do you follow any dietary restrictions or philosophies?
4. Are there any foods you really dislike?
5. What are some of your favorite foods or cuisines?

[User provides answers, Claude saves preferences]

Great! I've saved your preferences. Now let me suggest some dinner recipes perfect for you...

Example 2: Returning user

User: "I need a quick breakfast idea"

Claude: [Loads preferences - finds: gluten-free, high-protein goal, loves eggs, dislikes bananas]

Here are some quick, high-protein, gluten-free breakfast ideas for you:

1. Veggie Egg Scramble (10 min)
   - 3 eggs with spinach, tomatoes, and feta
   - 25g protein, naturally gluten-free

2. Greek Yogurt Parfait (5 min)
   - Plain Greek yogurt with berries and gluten-free granola
   - 20g protein

3. Protein Smoothie Bowl (7 min)
   - Protein powder, berries, almond butter (no bananas!)
   - 30g protein

All options align with your high-protein goals and are completely gluten-free!

Example 3: Preference update

User: "I've decided to go pescatarian, can you update my profile?"

Claude: [Loads current preferences]

I'll update your dietary restrictions to include pescatarian. This means you'll eat fish and seafood but no other meat, correct?

[User confirms]

Perfect! I've updated your preferences. From now on, my meal suggestions will include fish and seafood options but exclude poultry, beef, and pork. Your other preferences remain the same.

Technical Notes

Preference Storage Location:

• Preferences are stored at ~/.claude/nutritional_preferences.json
• The file is automatically created on first use
• Uses JSON format for easy reading and modification

Script Commands:

• python3 scripts/preferences_manager.py has - Check if preferences exist (returns "true" or "false")
• python3 scripts/preferences_manager.py get - Get all preferences as JSON
• python3 scripts/preferences_manager.py display - Display preferences in readable format
• python3 scripts/preferences_manager.py reset - Clear all preferences

Data Structure:

{
  "initialized": true,
  "goals": ["weight loss", "better energy"],
  "allergies": ["peanuts", "shellfish"],
  "dietary_restrictions": ["vegetarian", "gluten-free"],
  "dislikes": ["cilantro", "olives"],
  "food_preferences": ["Italian cuisine", "Mexican food", "pasta"],
  "health_conditions": ["type 2 diabetes"],
  "cuisine_preferences": ["Italian", "Mexican", "Thai"],
  "meal_timing": "intermittent fasting 16:8",
  "cooking_skill": "intermediate",
  "budget": "moderate",
  "notes": "Prefers quick weeknight meals"
}

Resources

scripts/preferences_manager.py

Python script that manages the persistent user preferences database. Provides functions to:

• Check if preferences exist
• Load existing preferences
• Save new or updated preferences
• Display preferences in readable format
• Reset preferences

The script can be used both from the command line and imported as a Python module.

Pitch Deck Generator

Overview

Generate professional PowerPoint pitch decks following industry best practices. This skill creates structured presentations for fundraising, sales, and business development using a proven 10-slide format.

When to Use This Skill

Activate this skill when users request:

• Investor pitch decks for fundraising
• Sales or business development presentations
• Product launch presentations
• Startup pitch competition decks
• Any structured business presentation following standard pitch deck format

Workflow

Step 1: Gather Information

Collect necessary information from the user to populate the pitch deck. Use a conversational approach to gather details across the following categories:

Required information:

1. Company basics: Company name, tagline (one-liner describing what you do)
2. Problem: What problem are you solving? Include data or statistics if available
3. Solution: How does your product/service solve the problem? Key features and benefits
4. Business model: How do you make money? Pricing, revenue streams

Recommended information (include if available): 5. Market opportunity: Market size (TAM/SAM/SOM), growth rate, market trends 6. Product details: Product features, screenshots, technology highlights 7. Traction: Key metrics, revenue, users, growth rate, milestones, customer testimonials 8. Competition: Competitors, competitive advantages, differentiation 9. Team: Founders and key team members with relevant background 10. Financials & Ask: Funding amount, use of funds, financial projections, milestones

Approach:

• Ask open-ended questions to understand the business
• Probe for specific metrics and data points when possible
• For missing information, offer to create placeholder slides that can be updated later
• Adapt the standard 10-slide structure based on available information

Step 2: Structure the Content

Organize the gathered information into the standard pitch deck structure:

1. Title Slide: Company name + tagline
2. Problem: Pain point being addressed
3. Solution: Product/service overview
4. Market Opportunity: Market size and growth
5. Product: Features and capabilities
6. Traction: Metrics and achievements
7. Business Model: Revenue and pricing
8. Competition: Competitive landscape
9. Team: Key people
10. Financials & Ask: Funding request and projections

Reference best practices: For detailed guidance on each slide's content and structure, consult references/pitch_deck_best_practices.md. Search for specific sections using grep:

grep -A 10 "### [Slide Number]. [Slide Name]" references/pitch_deck_best_practices.md

Step 3: Create the JSON Data File

Format the collected information as a JSON file that will be consumed by the pitch deck generation script. Create a file called pitch_data.json with the following structure:

{
  "company_name": "Company Name",
  "tagline": "One-line description of what you do",
  "problem": [
    "Problem statement 1 with data/statistics",
    "Problem statement 2 showing impact",
    "Problem statement 3 demonstrating urgency"
  ],
  "solution": [
    "How your product solves the problem",
    "Key feature 1 and its benefit",
    "Key feature 2 and its benefit",
    "Unique value proposition"
  ],
  "market": [
    "TAM: Total addressable market with $ figure",
    "SAM: Serviceable available market",
    "SOM: Serviceable obtainable market",
    "Market growth rate and trends"
  ],
  "product": [
    "Product feature 1",
    "Product feature 2",
    "Technology highlights",
    "User experience benefits"
  ],
  "traction": [
    "Revenue: $X (YY% growth)",
    "Users: X,XXX active users",
    "Key milestone 1",
    "Customer testimonial or social proof"
  ],
  "business_model": [
    "Revenue model (e.g., SaaS subscription)",
    "Pricing: $XX/month per user",
    "Unit economics: CAC, LTV, margins",
    "Sales channels"
  ],
  "competition": {
    "our_advantages": [
      "Advantage 1",
      "Advantage 2",
      "Unfair advantage/defensibility"
    ],
    "competitors": [
      "Competitor 1",
      "Competitor 2",
      "Alternative solutions"
    ]
  },
  "team": [
    "Founder 1: Name - Background and relevant experience",
    "Founder 2: Name - Background and relevant experience",
    "Key hire: Name - Background and why they matter",
    "Notable advisors"
  ],
  "financials": [
    "Raising: $X seed/Series A round",
    "Use of funds: XX% engineering, XX% sales, XX% ops",
    "Milestones with this funding",
    "Runway: X-X months to next milestone"
  ]
}

Notes:

• All fields are optional except company_name
• Use arrays for bullet points (will be rendered as bullet lists)
• Competition can be either an object with our_advantages and competitors keys (for two-column layout) or a simple array
• Keep bullet points concise (1-2 lines each)
• Include specific numbers and metrics where possible

Step 4: Generate the PowerPoint

Execute the Python script to create the PowerPoint presentation:

python3 scripts/create_pitch_deck.py pitch_data.json output_filename.pptx

The script will:

• Generate a professional PowerPoint file with proper formatting
• Apply consistent color scheme and typography
• Create slides based on available data (skipping sections if data not provided)
• Output a .pptx file ready for presentation or further customization

Step 5: Review and Iterate

Present the generated pitch deck location to the user and offer to:

• Add missing sections if information becomes available
• Refine bullet points for clarity and impact
• Adjust structure based on specific audience (investor vs. sales pitch)
• Provide guidance on presenting the deck

Iteration approach:

• User can update the JSON file with new information
• Re-run the script to regenerate the updated presentation
• For design customizations beyond the script's capabilities, advise manual editing in PowerPoint

Design Guidelines

The generated pitch deck follows these design principles:

Color Scheme:

• Primary: Blue (#2962FF) for titles and emphasis
• Secondary: Gray (#646464) for body text
• Clean white background for readability

Typography:

• Title slides: 54pt bold
• Section titles: 40pt bold
• Body text: 18-20pt with appropriate line spacing

Layout:

• Consistent margins and spacing
• One key message per slide
• Bullet points limited to 3-5 items per slide
• Two-column layouts for comparison slides

Visual Hierarchy:

• Clear title at top of each slide
• Content organized with proper spacing
• Emphasis on readability and professional appearance

Best Practices Reference

For detailed guidance on pitch deck content, structure, and presentation tips, reference:

• references/pitch_deck_best_practices.md - Comprehensive guide covering:
  • Standard 10-slide structure with examples
  • Content guidelines for each slide type
  • Design best practices
  • Common mistakes to avoid
  • Tailoring for different audiences (investor, sales, product launch)
  • Pre-pitch checklist

Load this reference when providing detailed advice on pitch content or structure.

Example Usage Scenarios

Scenario 1: Early-stage startup seeking seed funding

• Focus on problem, solution, market opportunity, and team
• Emphasize founder expertise and early traction
• Include clear funding ask and use of funds

Scenario 2: Growth-stage company creating sales deck

• Emphasize product features and customer ROI
• Include customer testimonials and case studies
• De-emphasize fundraising, focus on value proposition

Scenario 3: Product launch presentation

• Focus on product features and market need
• Include demo or product screenshots
• Emphasize innovation and competitive positioning

Customization and Extensions

After generating the base deck:

• Users can manually add images, charts, and custom graphics in PowerPoint
• Suggest creating appendix slides for detailed backup information
• Recommend PDF export for sharing (File → Save As → PDF in PowerPoint)
• Advise on presentation timing (typically 10-15 minutes for 10 slides)

Troubleshooting

Script errors:

• Ensure python-pptx library is installed: pip3 install python-pptx
• Verify JSON file is properly formatted (use JSON validator if needed)
• Check file paths are correct and user has write permissions

Content issues:

• If slides appear crowded, reduce bullet points to 3-5 per slide
• For complex competition analysis, consider manually creating comparison tables in PowerPoint
• For financial projections, consider creating charts in Excel and importing as images

Resources

scripts/

• create_pitch_deck.py: Python script that generates PowerPoint presentations from structured JSON data

references/

• pitch_deck_best_practices.md: Comprehensive guide on pitch deck content, structure, and design principles

Research Paper Writer

Overview

This skill guides the creation of formal academic research papers that meet publication standards for IEEE and ACM conferences/journals. It ensures proper structure, formatting, academic writing style, and comprehensive coverage of research topics.

Workflow

1. Understanding the Research Topic

When asked to write a research paper:

1. Clarify the topic and scope with the user:

   • What is the main research question or contribution?
   • What is the target audience (conference, journal, general academic)?
   • What is the desired length (page count or word count)?
   • Are there specific sections required?
   • What formatting standard to use (IEEE or ACM)?

2. Gather context if needed:

   • Review any provided research materials, data, or references
   • Understand the domain and technical background
   • Identify key related work or existing research to reference

2. Paper Structure

Follow this standard academic paper structure:

1. Title and Abstract
   - Concise title reflecting the main contribution
   - Abstract: 150-250 words summarizing purpose, methods, results, conclusions

2. Introduction
   - Motivation and problem statement
   - Research gap and significance
   - Main contributions (typically 3-5 bullet points)
   - Paper organization paragraph

3. Related Work / Background
   - Literature review of relevant research
   - Comparison with existing approaches
   - Positioning of current work

4. Methodology / Approach / System Design
   - Detailed description of proposed method/system
   - Architecture diagrams if applicable
   - Algorithms or procedures
   - Design decisions and rationale

5. Implementation (if applicable)
   - Technical details
   - Tools and technologies used
   - Challenges and solutions

6. Evaluation / Experiments / Results
   - Experimental setup
   - Datasets or test scenarios
   - Performance metrics
   - Results presentation (tables, graphs)
   - Analysis and interpretation

7. Discussion
   - Implications of results
   - Limitations and threats to validity
   - Lessons learned

8. Conclusion and Future Work
   - Summary of contributions
   - Impact and significance
   - Future research directions

9. References
   - Comprehensive bibliography in proper citation format

3. Academic Writing Style

Apply these writing conventions from scholarly research:

Tone and Voice:

• Formal, objective, and precise language
• Third-person perspective (avoid "I" or "we" unless describing specific contributions)
• Present tense for established facts, past tense for specific studies
• Clear, direct statements without unnecessary complexity

Technical Precision:

• Define all acronyms on first use: "Context-Aware Systems (C-AS)"
• Use domain-specific terminology correctly and consistently
• Quantify claims with specific metrics or evidence
• Avoid vague terms like "very", "many", "significant" without data

Argumentation:

• State claims clearly, then support with evidence
• Use logical progression: motivation → problem → solution → validation
• Compare and contrast with related work explicitly
• Address limitations and counterarguments

Section-Specific Guidelines:

Abstract:

• First sentence: broad context and motivation
• Second/third: specific problem and gap
• Middle: approach and methodology
• End: key results and contributions
• Self-contained (readable without the full paper)

Introduction:

• Start with real-world motivation or compelling problem
• Build from general to specific (inverted pyramid)
• End with clear contribution list and paper roadmap
• Use examples to illustrate the problem

Related Work:

• Group related work by theme or approach
• Compare explicitly: "Unlike [X] which focuses on Y, our approach..."
• Identify gaps: "However, these approaches do not address..."
• Position your work clearly

Results:

• Present data clearly in tables/figures
• Describe trends and patterns objectively
• Compare with baselines quantitatively
• Acknowledge unexpected or negative results

4. Formatting Guidelines

IEEE Format (default):

• Page size: A4 (210mm × 297mm)
• Margins: Top 19mm, Bottom 43mm, Left/Right 14.32mm
• Two-column layout with 4.22mm column separation
• Font: Times New Roman throughout
  • Title: 24pt bold
  • Author names: 11pt
  • Section headings: 10pt bold, numbered (1., 1.1, 1.1.1)
  • Body text: 10pt
  • Figure/Table captions: 8pt
• Line spacing: Single
• Paragraph: No indentation, 3pt spacing between paragraphs
• Figures: Centered, with captions below
• Tables: Centered, with captions above

ACM Format (alternative):

• Standard ACM conference proceedings format
• Single-column abstract, two-column body
• Include CCS Concepts and Keywords sections after abstract
• Use ACM reference format for citations

5. Citations and References

In-text citations:

• Use numbered citations: "Recent work [1, 2] has shown..."
• Multiple citations in chronological order: [3, 7, 12]
• Reference specific sections: "As demonstrated in [5, Section 3]..."

Reference formatting (IEEE style):

[1] A. Author, B. Author, and C. Author, "Title of paper," in Proc. Conference Name, Year, pp. 123-456.
[2] D. Author, "Title of journal article," Journal Name, vol. X, no. Y, pp. 123-456, Month Year.
[3] E. Author, Book Title, Edition. City: Publisher, Year.

Reference list requirements:

• Alphabetically ordered by first author's last name (or numbered by citation order)
• Include DOI or URL when available
• Minimum 15-20 references for a full paper
• Mix of recent (last 5 years) and foundational works

6. Content Generation Process

Step-by-step approach:

1. Create outline

   • Develop detailed section-by-section outline
   • Define key points for each section
   • Identify where figures/tables are needed

2. Draft sections iteratively

   • Start with methodology (core contribution)
   • Then introduction (now that contribution is clear)
   • Related work (to position the contribution)
   • Results and evaluation
   • Discussion and conclusion
   • Abstract last (summary of complete paper)

3. Add citations

   • Reference related work throughout
   • Support claims with evidence from literature
   • Create comprehensive reference list

4. Review and refine

   • Check logical flow between sections
   • Ensure consistency in terminology
   • Verify all figures/tables are referenced in text
   • Confirm abstract matches content
   • Validate citation completeness

Examples

Example 1: User asks for a survey paper

User: "Write a research paper surveying recent advances in context-aware systems"

Response:
1. Clarify scope: "I'll create a survey paper on context-aware systems. A few questions:
   - Should I focus on specific aspects (e.g., requirements engineering, implementation techniques)?
   - What time period for 'recent' (last 5 years, 10 years)?
   - Target length: 10-15 pages, or 20-30 pages comprehensive survey?
   - IEEE or ACM format?"

2. After clarification, create outline showing:
   - Taxonomy of context-aware systems
   - Survey methodology
   - Classification scheme
   - Section-by-section coverage of different aspects
   - Trends and future directions

3. Draft paper following survey structure with extensive related work coverage

Example 2: User asks for an experimental paper

User: "Write a paper about my new algorithm for detecting hallucinations in vision-language models"

Response:
1. Gather details about:
   - Algorithm approach and novelty
   - Experimental setup and datasets used
   - Results and metrics
   - Comparison baselines

2. Structure as experimental paper:
   - Introduction: motivation for hallucination detection
   - Related work: existing detection methods
   - Proposed method: detailed algorithm description
   - Experiments: datasets, metrics, setup
   - Results: quantitative comparison with baselines
   - Analysis: ablation studies, error analysis
   - Conclusion: contributions and future work

3. Emphasize reproducibility and empirical validation

Resources

references/

• writing_style_guide.md: Detailed academic writing conventions extracted from example papers
• ieee_formatting_specs.md: Complete IEEE formatting specifications
• acm_formatting_specs.md: Complete ACM formatting specifications

assets/

• full_paper_template.pdf: IEEE paper template with formatting examples
• interim-layout.pdf: ACM paper template
• Reference these templates when discussing formatting requirements with users

Important Notes

• Always ask for clarification on topic scope before starting
• Quality over speed: Take time to structure properly and write clearly
• Cite appropriately: Academic integrity requires proper attribution
• Be honest about limitations: Acknowledge gaps or constraints in the research
• Maintain consistency: Terminology, notation, and style throughout
• User provides the research content: This skill structures and writes; the user provides the technical contributions and findings

Script Writer

Overview

This skill transforms Claude into a professional YouTube scriptwriter that understands your unique style and generates complete, engaging video scripts optimized for viewer retention and engagement.

When to Use This Skill

Invoke this skill for YouTube scriptwriting tasks:

• Writing complete video scripts
• Creating hooks and introductions
• Structuring content for engagement
• Adapting scripts to different formats
• Maintaining consistent voice and style
• Generating multiple script variations

Workflow

Step 1: Check for Existing Preferences

python3 scripts/script_db.py is_initialized

If "false", proceed to Step 2. If "true", proceed to Step 3.

Step 2: Initial Preference Collection

Collect comprehensive scriptwriting preferences:

Script Types (can select multiple):

• Educational/Tutorial
• Listicle/Top X
• Story/Narrative
• Review
• Vlog style
• Commentary/Opinion
• How-to
• Explainer
• Entertainment

Tone:

• Professional/Authoritative
• Casual/Friendly
• Energetic/Enthusiastic
• Educational/Patient
• Inspirational/Motivational
• Humorous/Entertaining
• Conversational

Target Audience:

• Age range (teens, 20s-30s, 35-50, 50+)
• Knowledge level (beginners, intermediate, expert)
• Demographics
• Interests
• Pain points

Style Preferences:

• Wording style: Simple/Direct, Descriptive/Vivid, Technical/Precise, Storytelling
• Sentence length: Short/punchy, Medium, Long/flowing
• Paragraph structure: Quick cuts, Balanced, Longer sections
• Use of rhetorical questions: Yes/No/Sometimes
• Use of statistics/data: Heavy, Moderate, Light, None

Video Length Preference:

• Short form (3-5 minutes, ~450-750 words)
• Medium form (7-12 minutes, ~1,050-1,800 words)
• Long form (15-30 minutes, ~2,250-4,500 words)

Hook Style:

• Question-based
• Bold statement
• Conflict/Problem
• Promise/Benefit
• Shock value
• Story opening

Personality:

• Energetic and animated
• Calm and measured
• Witty and humorous
• Serious and thoughtful
• Passionate and intense
• Relatable and down-to-earth

Additional Preferences:

• Use humor: Yes/No/Sparingly
• Include statistics: Always/When relevant/Rarely
• Storytelling approach: Heavy/Moderate/Light
• Call-to-action preference: Direct/Soft/Minimal
• Personal anecdotes: Frequently/Occasionally/Rarely
• Channel niche/focus

Saving Preferences:

import sys
sys.path.append('[SKILL_DIR]/scripts')
from script_db import save_preferences

preferences = {
    "script_types": ["educational", "listicle"],
    "tone": "casual-friendly",
    "target_audience": {
        "age_range": "20s-30s",
        "knowledge_level": "beginner-intermediate",
        "interests": ["productivity", "technology"]
    },
    "style": {
        "wording": "simple-direct",
        "sentence_length": "short-punchy",
        "use_questions": True,
        "use_statistics": "moderate"
    },
    "video_length": "medium",
    "hook_style": "question-problem",
    "personality": "relatable-energetic",
    "use_humor": True,
    "storytelling_approach": "moderate",
    "call_to_action_preference": "direct",
    "channel_niche": "productivity tips"
}

save_preferences(preferences)

Step 3: Generate Script for Topic

When user requests a script, gather:

Essential Information:

1. Topic/Title: What the video is about
2. Key Points: Main things to cover (3-5 points)
3. Video Length: Specific duration or use preference
4. Special Requirements: Anything specific to include/avoid
5. Target Keywords: For SEO (optional)

Example Request:

User: "Write a script about '5 Productivity Apps That Changed My Life'"

Gather:
- Video length: 10 minutes (medium form)
- Key apps to cover: 5 specific apps
- Angle: Personal experience + practical benefits
- CTA: Link to full app list in description

Step 4: Structure the Script

Based on preferences and references/script_formats.md, create structure:

Standard YouTube Script Structure:

[HOOK - 0:00-0:10]
Opening line that stops the scroll

[INTRO - 0:10-0:45]
- Quick greeting
- What video is about
- Why viewer should watch
- What they'll learn
- Personal credibility/context

[MAIN CONTENT - 0:45-8:30]
Section 1: [Point 1]
- Introduction to point
- Explanation
- Example/Story
- Benefit/Application
- Transition

Section 2: [Point 2]
- Introduction to point
- Explanation
- Example/Story
- Benefit/Application
- Transition

[Continue for each main point]

[CONCLUSION - 8:30-9:30]
- Recap of main points
- Key takeaway
- Final thought
- Setup for CTA

[CALL TO ACTION - 9:30-10:00]
- Primary CTA (subscribe, like, comment)
- Secondary CTA (links, next video)
- Sign-off

Step 5: Write Complete Script

Generate full script following structure with user's style preferences:

Example Script Output:

===================================
YOUTUBE SCRIPT
===================================

Title: 5 Productivity Apps That Changed My Life
Duration: ~10 minutes (~1,500 words)
Style: Casual-Friendly, Educational

===================================

[HOOK - 0:00-0:10]

"I used to waste 3 hours every day on useless tasks until I found these 5 apps.
And no, I'm not talking about the ones everyone already knows about."

[INTRO - 0:10-0:45]

"Hey everyone! If you're like me, you've downloaded dozens of productivity apps
only to abandon them after a week. But these 5? They've actually stuck. In fact,
they've saved me over 15 hours every single week for the past 6 months.

Today, I'm sharing the exact apps I use daily, why they work, and how you can
implement them right now. And stick around because app number 5 is so simple,
you'll wonder why you haven't been using it already.

Let's dive in."

[MAIN CONTENT - 0:45-8:30]

[Section 1: App #1 - 1:00-2:30]

"App number one is Notion – but not how you think.

I know, I know – everyone talks about Notion. But here's the thing: most people
overcomplicate it. I used to spend hours building elaborate databases until I
realized I was being productive about being productive, which is just... not
productive.

[Visual cue: Show simple Notion setup]

Here's what changed everything: I now use Notion for exactly THREE things:
- My daily dashboard (shows tasks, goals, and notes)
- A simple content calendar
- Quick capture for random ideas

That's it. No complex databases. No elaborate systems. Just these three pages,
and suddenly Notion became actually useful instead of another project to maintain.

The key? Start simple. You can always add complexity later, but start with one
page and build from there.

Moving on to something completely different..."

[Section 2: App #2 - 2:30-4:00]

"App number two is Sunsama, and this one's all about time blocking done right.

If you've ever written a to-do list and then just... stared at it, paralyzed
about where to start – Sunsama solves that. It's like a calendar and task
manager had a baby.

[Visual cue: Show Sunsama interface]

Every morning, I spend 10 minutes in Sunsama planning my day. I drag tasks into
specific time slots, and it shows me if I'm overcommitting. Game changer.

Before Sunsama, I'd have 20 tasks and no idea how to fit them in. Now? I can see
I only have time for 7 tasks today, so I prioritize accordingly. It's honestly
changed how I approach my entire day.

The best part? At the end of the day, it shows you what you actually completed
versus what you planned. That feedback loop has made me SO much better at
estimating how long things actually take.

Fair warning: it's a paid app. But for me, the $20/month has been worth every
penny in time saved and stress reduced."

[Continue for Apps 3, 4, and 5...]

[CONCLUSION - 8:30-9:30]

"So there you have it – the 5 apps that transformed my productivity:
1. Notion for simple organization
2. Sunsama for time blocking
3. [App 3] for [benefit]
4. [App 4] for [benefit]
5. [App 5] for [benefit]

The most important thing? Don't try to implement all 5 at once. Pick ONE, master
it for a week, then add another. That's how these actually stick.

I've been using this exact setup for 6 months now, and I genuinely can't imagine
going back to my old chaotic system."

[CALL TO ACTION - 9:30-10:00]

"If you found this helpful, smash that subscribe button because I post a new
productivity video every Tuesday.

Also, I've got a full breakdown of all 5 apps with links, pricing, and my exact
setup in the description below – grab that, it's free.

Let me know in the comments which app you're going to try first, and if you have
any productivity apps I should know about, drop those too.

Thanks for watching, and I'll see you in the next one!"

===================================
[END OF SCRIPT]

Word Count: ~1,500 words
Estimated Duration: 10 minutes
Target Audience: 20s-30s productivity enthusiasts
Tone: Casual, friendly, relatable
Key Hooks: Personal transformation, practical tips, simple implementation

Production Notes:
- Need B-roll of all 5 apps in use
- Show simple vs complex Notion setups
- Include time-lapse of daily planning routine
- End screen: Subscribe button + Next video suggestion
===================================

Step 6: Refine Based on Feedback

After presenting script:

Offer Adjustments:

• Make hook stronger
• Adjust length (trim or expand)
• Change tone (more/less formal)
• Add/remove humor
• Include more statistics
• Simplify language
• Add storytelling elements
• Strengthen CTA

Save Final Version:

from script_db import add_script

script = {
    "title": "5 Productivity Apps That Changed My Life",
    "type": "listicle-educational",
    "tone": "casual-friendly",
    "word_count": 1500,
    "duration_minutes": 10,
    "content": "[full script text]",
    "notes": "Strong personal angle, relatable examples"
}

add_script(script)

Best Practices

1. Hook Creation

• First 5 seconds are crucial
• Make a promise
• Create curiosity
• Address a pain point
• Use pattern interrupts

2. Pacing

• Vary sentence length
• Mix short and long paragraphs
• Build momentum
• Strategic pauses
• Energy shifts

3. Engagement Techniques

• Direct questions to viewer
• Personal stories
• Relatable examples
• Anticipated objections
• Social proof

4. Retention Optimization

• Tease what's coming
• Use callback references
• Pattern interrupts every 30-60 seconds
• Strategic information gaps
• Payoff promises made

5. Call to Action

• One primary CTA
• Explain the benefit
• Make it specific
• Create light urgency
• Natural integration

Script Templates

Educational Tutorial Template

[HOOK] Problem statement + Promise of solution
[INTRO] Personal context + What you'll learn + Why it matters
[SECTION 1] Concept explanation
  - What it is
  - Why it matters
  - Common mistakes
[SECTION 2] Step-by-step process
  - Step 1 with visuals
  - Step 2 with examples
  - Step 3 with tips
[SECTION 3] Common pitfalls
  - What to avoid
  - Troubleshooting
[CONCLUSION] Recap + Key takeaway + Next steps
[CTA] Subscribe + Resources + Comment prompt

Listicle Template

[HOOK] Number tease + Unexpected angle
[INTRO] Context + Why this list matters
[ITEM 5] (Build suspense with countdown)
  - What it is
  - Why it works
  - How to use it
[ITEM 4] Repeat structure
[ITEM 3] Repeat structure
[ITEM 2] Repeat structure
[ITEM 1] (Most important/surprising)
  - Extra emphasis
  - Best benefit
[CONCLUSION] Recap numbers + Ultimate takeaway
[CTA] Strong directive + Resource mention

Story/Narrative Template

[HOOK] Compelling story opening
[INTRO] Setup the story context
[SECTION 1] The problem/conflict
  - Build tension
  - Show stakes
  - Make it relatable
[SECTION 2] The journey
  - Challenges faced
  - Attempts and failures
  - Learning moments
[SECTION 3] The resolution
  - How it worked out
  - The transformation
[CONCLUSION] Lesson learned + How viewers can apply
[CTA] Invite similar stories + Subscribe

Tone Examples

Casual-Friendly

"Hey everyone! So, funny story – I completely messed this up last week.
Like, embarrassingly bad. But here's what I learned..."

Professional-Authoritative

"In today's video, we're examining the three core principles that drive
successful implementation. Based on 5 years of data and research..."

Energetic-Enthusiastic

"Okay, THIS is insane! I just discovered something that's going to blow
your mind. Are you ready? Because once you see this..."

Educational-Patient

"Let's break this down step by step. Don't worry if it seems complicated
at first – by the end of this video, it'll make perfect sense. First..."

Common Mistakes to Avoid

1. Weak hooks - Get to the point in 5 seconds
2. Long intros - Don't ramble before value
3. No structure - Viewers need signposts
4. Monotone delivery - Vary energy and pace
5. Information overload - Focus on key points
6. Forgetting the audience - Speak to them directly
7. Buried CTA - Make it clear and actionable
8. No personality - Let your unique voice show
9. Too formal - YouTube is conversational
10. No visual cues - Include filming notes

Example Interaction

User: "Write me a script about passive income ideas"

Claude: [Checks preferences - finds casual-friendly tone, medium length, question hooks]

Perfect! Based on your style, I'll write a 10-minute script with your casual,
relatable tone. A few quick questions:

1. How many passive income ideas should I cover? (3-5 works well for 10 minutes)
2. Any specific angle? (beginner-friendly, high-earning, low startup cost?)
3. Personal experience or research-based approach?

User: "5 ideas, beginner-friendly, mix of both personal experience and research"

Claude: [Generates complete script]

Here's your complete script for "5 Passive Income Ideas for Beginners":

[Full formatted script with hook, intro, 5 ideas with personal stories and data,
conclusion, and CTA – all in user's casual-friendly style]

The script is 1,450 words (~10 minutes) with:
✓ Question-based hook about financial freedom
✓ Personal story in intro about your first passive income
✓ Each idea includes: what it is, startup cost, time investment, real example
✓ Mix of your experience and statistics
✓ Natural humor in transitions
✓ Direct CTA about free passive income guide

Want me to adjust anything? I can make it more personal, add more data, or
change the energy level.

Technical Notes

Data Storage:

• Location: ~/.claude/script_writer.json
• Preferences saved persistently
• Script history maintained

CLI Commands:

python3 scripts/script_db.py is_initialized
python3 scripts/script_db.py get_preferences
python3 scripts/script_db.py get_scripts
python3 scripts/script_db.py stats

Word Count Guidelines:

• Speaking pace: ~150 words per minute
• Short form (3-5 min): 450-750 words
• Medium form (7-12 min): 1,050-1,800 words
• Long form (15-30 min): 2,250-4,500 words

Resources

scripts/script_db.py

Database management for preferences, scripts, and templates.

references/script_formats.md

Comprehensive guide covering:

• Common YouTube video types and structures
• Script component breakdowns (hook, intro, content, conclusion, CTA)
• Tone guidelines for different styles
• Timing guidelines by video length
• Engagement techniques
• Common mistakes to avoid
• Visual cues for scripts
• Audience-specific adjustments
• Platform-specific considerations

SEO Optimizer

Overview

This skill provides comprehensive SEO optimization capabilities for HTML/CSS websites. It analyzes websites for SEO issues, implements best practices, and generates optimization reports covering all critical SEO aspects including meta tags, heading structure, image optimization, schema markup, mobile optimization, and technical SEO.

When to Use This Skill

Use this skill when the user requests:

• "Analyze my website for SEO issues"
• "Optimize this page for SEO"
• "Generate an SEO audit report"
• "Fix SEO problems on my website"
• "Add proper meta tags to my pages"
• "Implement schema markup"
• "Generate a sitemap"
• "Improve my site's search engine rankings"
• Any task related to search engine optimization for HTML/CSS websites

Workflow

1. Initial SEO Analysis

Start with comprehensive analysis using the SEO analyzer script:

python scripts/seo_analyzer.py <directory_or_file>

This script analyzes HTML files and generates a detailed report covering:

• Title tags (length, presence, uniqueness)
• Meta descriptions (length, presence)
• Heading structure (H1-H6 hierarchy)
• Image alt attributes
• Open Graph tags
• Twitter Card tags
• Schema.org markup
• HTML lang attribute
• Viewport and charset meta tags
• Canonical URLs
• Content length

Output Options:

• Default: Human-readable text report with issues, warnings, and good practices
• --json: Machine-readable JSON format for programmatic processing

Example Usage:

# Analyze single file
python scripts/seo_analyzer.py index.html

# Analyze entire directory
python scripts/seo_analyzer.py ./public

# Get JSON output
python scripts/seo_analyzer.py ./public --json

2. Review Analysis Results

The analyzer categorizes findings into three levels:

Critical Issues (🔴) - Fix immediately:

• Missing title tags
• Missing meta descriptions
• Missing H1 headings
• Images without alt attributes
• Missing HTML lang attribute

Warnings (⚠️) - Fix soon for optimal SEO:

• Suboptimal title/description lengths
• Multiple H1 tags
• Missing Open Graph or Twitter Card tags
• Missing viewport meta tag
• Missing schema markup
• Heading hierarchy issues

Good Practices (✅) - Already optimized:

• Properly formatted elements
• Correct lengths
• Present required tags

3. Prioritize and Fix Issues

Address issues in priority order:

Priority 1: Critical Issues

Missing or Poor Title Tags:

<!-- Add unique, descriptive title to <head> -->
<title>Primary Keyword - Secondary Keyword | Brand Name</title>

• Keep 50-60 characters
• Include target keywords at the beginning
• Make unique for each page

Missing Meta Descriptions:

<!-- Add compelling description to <head> -->
<meta name="description" content="Clear, concise description that includes target keywords and encourages clicks. 150-160 characters.">

Missing H1 or Multiple H1s:

• Ensure exactly ONE H1 per page
• H1 should describe the main topic
• Should match or relate to title tag

Images Without Alt Text:

<!-- Add descriptive alt text to all images -->
<img src="image.jpg" alt="Descriptive text explaining image content">

Missing HTML Lang Attribute:

<!-- Add to opening <html> tag -->
<html lang="en">

Priority 2: Important Optimizations

Viewport Meta Tag (critical for mobile SEO):

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Charset Declaration:

<meta charset="UTF-8">

Open Graph Tags (for social media sharing):

<meta property="og:title" content="Your Page Title">
<meta property="og:description" content="Your page description">
<meta property="og:image" content="https://example.com/image.jpg">
<meta property="og:url" content="https://example.com/page-url">
<meta property="og:type" content="website">

Twitter Card Tags:

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Your Page Title">
<meta name="twitter:description" content="Your page description">
<meta name="twitter:image" content="https://example.com/image.jpg">

Canonical URL:

<link rel="canonical" href="https://example.com/preferred-url">

Priority 3: Advanced Optimization

Schema Markup - Refer to references/schema_markup_guide.md for detailed implementation. Common types:

• Organization (homepage)
• Article/BlogPosting (blog posts)
• LocalBusiness (local businesses)
• Breadcrumb (navigation)
• FAQ (FAQ pages)
• Product (e-commerce)

Example implementation:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Article Title",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "datePublished": "2024-01-15",
  "image": "https://example.com/image.jpg"
}
</script>

4. Generate or Update Sitemap

After fixing issues, generate an XML sitemap:

python scripts/generate_sitemap.py <directory> <base_url> [output_file]

Example:

# Generate sitemap for website
python scripts/generate_sitemap.py ./public https://example.com

# Specify output location
python scripts/generate_sitemap.py ./public https://example.com ./public/sitemap.xml

The script:

• Automatically finds all HTML files
• Generates proper URLs
• Includes lastmod dates
• Estimates priority and changefreq values
• Creates properly formatted XML sitemap

After generation:

1. Upload sitemap.xml to website root
2. Add reference to robots.txt
3. Submit to Google Search Console and Bing Webmaster Tools

5. Update robots.txt

Use the template from assets/robots.txt and customize:

User-agent: *
Allow: /

# Block sensitive directories
Disallow: /admin/
Disallow: /private/

# Reference your sitemap
Sitemap: https://yourdomain.com/sitemap.xml

Place robots.txt in website root directory.

6. Verify and Test

After implementing fixes:

Local Testing:

1. Run the SEO analyzer again to verify fixes
2. Check that all critical issues are resolved
3. Ensure no new issues were introduced

Online Testing:

1. Deploy changes to production
2. Test with Google Rich Results Test: https://search.google.com/test/rich-results
3. Validate schema markup: https://validator.schema.org/
4. Check mobile-friendliness: https://search.google.com/test/mobile-friendly
5. Monitor in Google Search Console

7. Ongoing Optimization

Regular maintenance:

• Update sitemap when adding new pages
• Keep meta descriptions fresh and compelling
• Ensure new images have alt text
• Add schema markup to new content types
• Monitor Search Console for issues
• Update content regularly

Common Optimization Patterns

Pattern 1: New Website Setup

For a brand new HTML/CSS website:

1. Run initial analysis: python scripts/seo_analyzer.py ./public
2. Add essential meta tags to all pages (title, description, viewport)
3. Ensure proper heading structure (one H1 per page)
4. Add alt text to all images
5. Implement organization schema on homepage
6. Generate sitemap: python scripts/generate_sitemap.py ./public https://yourdomain.com
7. Create robots.txt from template
8. Deploy and submit sitemap to search engines

Pattern 2: Existing Website Audit

For an existing website needing optimization:

1. Run comprehensive analysis: python scripts/seo_analyzer.py ./public
2. Identify and prioritize issues (critical first)
3. Fix critical issues across all pages
4. Add missing Open Graph and Twitter Card tags
5. Implement schema markup for appropriate pages
6. Regenerate sitemap with updates
7. Verify fixes with analyzer
8. Deploy and monitor

Pattern 3: Single Page Optimization

For optimizing a specific page:

1. Analyze specific file: python scripts/seo_analyzer.py page.html
2. Fix identified issues
3. Optimize title and meta description for target keywords
4. Ensure proper heading hierarchy
5. Add appropriate schema markup for page type
6. Verify with analyzer
7. Update sitemap if new page

Pattern 4: Blog Post Optimization

For blog posts and articles:

1. Ensure unique title (50-60 chars) with target keyword
2. Write compelling meta description (150-160 chars)
3. Use single H1 for article title
4. Implement proper H2/H3 hierarchy for sections
5. Add alt text to all images
6. Implement Article or BlogPosting schema (see references/schema_markup_guide.md)
7. Add Open Graph and Twitter Card tags for social sharing
8. Include author information
9. Add breadcrumb schema for navigation

Reference Materials

Detailed Guides

references/seo_checklist.md: Comprehensive checklist covering all SEO aspects:

• Title tags and meta descriptions guidelines
• Heading structure best practices
• Image optimization techniques
• URL structure recommendations
• Internal linking strategies
• Page speed optimization
• Mobile optimization requirements
• Semantic HTML usage
• Complete technical SEO checklist

Reference this for detailed specifications on any SEO element.

references/schema_markup_guide.md: Complete guide for implementing schema.org structured data:

• JSON-LD implementation (recommended format)
• 10+ common schema types with examples
• Organization, LocalBusiness, Article, BlogPosting, FAQ, Product, etc.
• Required properties for each type
• Best practices and common mistakes
• Validation tools and resources

Reference this when implementing schema markup for any content type.

Scripts

scripts/seo_analyzer.py: Python script for automated SEO analysis. Analyzes HTML files for common issues and generates detailed reports. Can output text or JSON format. Deterministic and reliable for repeated analysis.

scripts/generate_sitemap.py: Python script for generating XML sitemaps. Automatically crawls directories, estimates priorities and change frequencies, and generates properly formatted sitemaps ready for submission to search engines.

Assets

assets/robots.txt: Template robots.txt file with common configurations and comments. Customize for specific needs and place in website root directory.

Key Principles

1. User-First: Optimize for users first, search engines second. Good user experience leads to better SEO.

2. Unique Content: Every page should have unique title, description, and H1. Duplicate content hurts SEO.

3. Mobile-First: Google uses mobile-first indexing. Always include viewport meta tag and ensure mobile responsiveness.

4. Accessibility = SEO: Accessible websites (alt text, semantic HTML, proper headings) rank better.

5. Quality Over Quantity: Substantial, valuable content ranks better than thin content. Aim for comprehensive pages.

6. Technical Foundation: Fix critical technical issues (missing tags, broken structure) before advanced optimization.

7. Structured Data: Schema markup helps search engines understand content and can lead to rich results.

8. Regular Updates: SEO is ongoing. Keep content fresh, monitor analytics, and adapt to algorithm changes.

9. Natural Language: Write for humans using natural language. Avoid keyword stuffing.

10. Validation: Always validate changes with testing tools before deploying to production.

Tips for Maximum Impact

• Start with critical issues: Fix missing title tags and meta descriptions first - these have the biggest impact
• Be consistent: Apply optimizations across all pages, not just homepage
• Use semantic HTML: Use proper HTML5 semantic tags (<header>, <nav>, <main>, <article>, <aside>, <footer>)
• Optimize images: Compress images, use descriptive filenames, always include alt text
• Internal linking: Link to related pages with descriptive anchor text
• Page speed matters: Fast-loading pages rank better
• Test on mobile: Majority of searches are mobile - ensure excellent mobile experience
• Monitor Search Console: Use Google Search Console to track performance and identify issues
• Update regularly: Fresh content signals active, valuable websites

Quick Reference Commands

# Analyze single file
python scripts/seo_analyzer.py index.html

# Analyze entire website
python scripts/seo_analyzer.py ./public

# Generate sitemap
python scripts/generate_sitemap.py ./public https://example.com

# Get JSON analysis output
python scripts/seo_analyzer.py ./public --json

Social Media Generator

Overview

This skill enables creation of platform-optimized social media content for Twitter, Instagram, LinkedIn, and Facebook. It automatically generates posts tailored to each platform's best practices and saves them in an organized directory structure.

When to Use This Skill

Use this skill when the user requests:

• Creation of social media posts for multiple platforms
• Content generation for specific events, announcements, or campaigns
• Platform-specific content optimization
• Organized storage of social media content

Core Workflow

Step 1: Gather Information

Collect the following details from the user (ask if not provided):

• Event/content name
• Date and time (format: DD-MM-YYYY-HHMM)
• Main message or announcement
• Target audience
• Key details to include
• Call-to-action
• Any specific hashtags or mentions
• Brand voice/tone preferences

Step 2: Generate Platform-Specific Content

Create content for each platform using the templates in assets/:

Twitter (assets/twitter_template.md)

• Keep under 280 characters
• Concise and punchy
• 1-3 relevant hashtags
• Clear call-to-action
• Consider emojis for engagement

Instagram (assets/instagram_template.md)

• Engaging caption with hook in first line
• More detailed description
• 5-15 relevant hashtags
• Visual-focused messaging
• Line breaks for readability
• Encourage engagement

LinkedIn (assets/linkedin_template.md)

• Professional and informative tone
• Value-driven content
• Industry insights or takeaways
• 3-5 professional hashtags
• Bullet points for key information
• Discussion-prompting questions

Facebook (assets/facebook_template.md)

• Conversational and engaging
• Keep concise (under 250 chars for best engagement)
• 2-3 relevant hashtags
• Visual-focused
• Encourage comments and shares
• Include event details if applicable

Step 3: Create Organized File Structure

Create the following directory structure in the project:

social-media/
├── twitter/
│   └── event-name-DD-MM-YYYY-HHMM.md
├── instagram/
│   └── event-name-DD-MM-YYYY-HHMM.md
├── linkedin/
│   └── event-name-DD-MM-YYYY-HHMM.md
└── facebook/
    └── event-name-DD-MM-YYYY-HHMM.md

Filename Format: event-name-DD-MM-YYYY-HHMM.md

• Use lowercase with hyphens for spaces
• Include date in format: day-month-year-time
• Example: product-launch-15-03-2025-1400.md

Step 4: Write Content to Files

For each platform:

1. Generate platform-optimized content based on the templates
2. Create the platform-specific subdirectory if it doesn't exist
3. Write the content to the appropriately named markdown file
4. Include metadata at the bottom (platform, date, character count)

Step 5: Review and Confirm

After generating all posts:

1. Provide a summary of created files
2. Highlight key points for each platform
3. Note any character count warnings
4. Offer to make revisions if needed

Content Optimization Guidelines

Character Limits

• Twitter: 280 characters
• Instagram: 2,200 characters (but concise is better)
• LinkedIn: 3,000 characters
• Facebook: Unlimited (but under 250 for best engagement)

Hashtag Strategy

• Twitter: 1-3 focused hashtags
• Instagram: 5-15 relevant hashtags
• LinkedIn: 3-5 professional hashtags
• Facebook: 2-3 hashtags

Tone Adaptation

• Twitter: Casual, conversational, timely
• Instagram: Visual-first, engaging, lifestyle-focused
• LinkedIn: Professional, insightful, value-driven
• Facebook: Friendly, community-focused, conversational

Call-to-Action Best Practices

• Make it clear and specific
• Use action verbs
• Create urgency when appropriate
• Match platform conventions

Example Usage

User Request: "Create social media posts for our product launch event on March 15, 2025 at 2 PM. The product is an AI-powered productivity tool called TaskFlow."

Execution:

1. Gather additional details (key features, target audience, website link)
2. Generate four platform-specific posts
3. Create directory structure: social-media/twitter/, social-media/instagram/, etc.
4. Write files: taskflow-launch-15-03-2025-1400.md in each platform folder
5. Provide summary with file locations and key points

Assets

This skill includes template files in the assets/ directory:

• twitter_template.md - Twitter post structure and best practices
• instagram_template.md - Instagram caption format and guidelines
• linkedin_template.md - LinkedIn post structure and professional tone guide
• facebook_template.md - Facebook post format and engagement tips

These templates serve as reference for platform-specific requirements and best practices when generating content.

Storyboard Manager

Overview

The Storyboard Manager skill equips Claude with specialized knowledge and tools for creative writing workflows. It provides frameworks for character development, story structure patterns, automated timeline tracking, and consistency checking across narrative projects. This skill automatically adapts to various storyboard folder structures while maintaining best practices for novel, screenplay, and serialized fiction writing.

Core Capabilities

The skill provides four main capabilities:

1. Character Development & Management

Support creating deep, consistent character profiles with backstories, arcs, and relationships.

2. Story Planning & Structure

Guide plot development using established frameworks (Three-Act, Hero's Journey, Save the Cat, etc.) and help organize narrative elements.

3. Chapter & Scene Writing

Generate chapter content, scene breakdowns, and dialogue that maintains consistency with established characters and plot.

4. Timeline Tracking & Consistency Checking

Use automated tools to verify chronological consistency, character continuity, and world-building coherence.

Detecting Project Structure

The Storyboard Manager automatically detects and adapts to various folder organizations. Look for these common directory patterns:

Character folders: characters/, Characters/, cast/, Cast/ Chapter folders: chapters/, Chapters/, scenes/, Scenes/, story/ Planning folders: story-planning/, planning/, outline/, notes/ Summary files: summary.md, README.md, overview.md

When triggered, scan the project root to identify the structure and adjust workflows accordingly. If no standard structure exists, recommend organizing files using the pattern: characters/, chapters/, story-planning/, and summary.md.

Workflow Decision Tree

Use this decision tree to determine the appropriate workflow:

User Request
├─ Character-related? ("develop character," "create backstory," "character arc")
│  └─ → Character Development Workflow
│
├─ Planning/Plot? ("outline story," "plan act 2," "plot structure")
│  └─ → Story Planning Workflow
│
├─ Writing content? ("write chapter," "generate scene," "continue story")
│  └─ → Chapter/Scene Writing Workflow
│
└─ Checking/Analysis? ("check consistency," "track timeline," "find contradictions")
   ├─ Timeline? → Use timeline_tracker.py script
   └─ Consistency? → Use consistency_checker.py script

Character Development Workflow

Step 1: Gather Context

Before developing a character, read existing character files to understand:

• Established naming conventions and profile format
• Existing characters and relationships
• Story genre and tone
• Character archetypes already in use

Use the Read tool to examine existing character files in the characters directory.

Step 2: Access Character Development Framework

When detailed character guidance is needed, read references/character_development.md which contains:

• Core character elements (personality, motivation, goals)
• Backstory framework (ghost/wound, formative relationships)
• Character arc types (positive change, flat, negative)
• Relationship dynamics
• Voice development techniques
• Consistency guidelines

To efficiently find specific guidance, use Grep to search for relevant sections:

# Example: Find guidance on character arcs
grep -i "character arc" references/character_development.md

Step 3: Develop Character Profile

Create or enhance character profiles with these essential elements:

Basic Information

• Name, age, role, physical appearance
• Key personality traits (both positive and negative)

Background

• Origin and formative experiences
• Ghost/wound that shapes their behavior
• Key relationships and family dynamics

Character Arc

• Starting belief or flaw
• Want vs. Need (external goal vs. internal growth)
• Transformation journey
• End state

Relationships

• Connections to other characters
• Dynamic types (ally, rival, mentor, etc.)
• How relationships evolve

Unique Elements

• Abilities, skills, or special knowledge
• Secrets or hidden aspects
• Voice/speech patterns
• Character-specific quirks

Step 4: Ensure Consistency

Cross-reference with:

• Existing character profiles (avoid redundancy in roles/traits)
• Story planning documents (ensure alignment with plot needs)
• Summary/overview (match genre and tone)

Step 5: Create or Update File

Write the character profile to characters/[character-name].md using markdown format. Match the existing style and structure found in other character files.

Story Planning Workflow

Step 1: Assess Current Planning State

Read existing planning documents to understand:

• Story concept and premise
• Established plot points or outline
• Target audience and genre
• Themes and central questions
• Planned structure (if any)

Look in folders like story-planning/, outline/, or files like summary.md.

Step 2: Access Story Structure Reference

For detailed structural guidance, read references/story_structures.md which includes:

• Three-Act Structure
• Hero's Journey (Campbell's Monomyth)
• Save the Cat Beat Sheet
• Character arc templates
• Scene structure components
• Pacing guidelines by genre
• Subplot integration techniques
• Genre-specific structures

Use Grep to find specific frameworks:

# Example: Find Three-Act Structure details
grep -A 20 "Three-Act Structure" references/story_structures.md

Step 3: Determine Structure Needs

Based on the user's request and story genre, recommend appropriate frameworks:

• Thriller/Mystery: Three-Act with strong midpoint reversal
• Fantasy/Adventure: Hero's Journey for quest narratives
• YA/Contemporary: Save the Cat for tight emotional beats
• Literary Fiction: Focus on character arc structure
• Romance: Genre-specific structure with relationship beats

Step 4: Develop Planning Document

Create or enhance planning documents with:

Story Overview

• Premise in 2-3 sentences
• Genre, target audience, tone
• Central themes and questions

Plot Structure

• Act/chapter breakdown with key events
• Inciting incident and plot points
• Midpoint twist or revelation
• Climax and resolution

Character Arcs

• How each main character transforms
• Arc integration with plot beats

World-Building Elements (if applicable)

• Setting and locations
• Magic systems or technology
• Social structures or rules
• Historical context

Timeline

• Story duration
• Key event sequence
• Pacing considerations

Step 5: Create Planning File

Write planning documents to story-planning/[document-name].md. Use clear hierarchical structure with markdown headers for easy navigation.

Chapter & Scene Writing Workflow

Step 1: Gather Story Context

Before writing any content, comprehensively read:

Character Files: All relevant character profiles to understand voices, motivations, arcs Planning Documents: Story structure, plot points, current story position Previous Chapters: Recent chapters to maintain continuity (read at least 1-2 prior chapters) Summary: Overall story premise and themes

This ensures the new content aligns with established elements.

Step 2: Identify Chapter Requirements

Determine:

• Story Position: Where does this fit in the overall structure?
• POV Character: Whose perspective?
• Scene Goal: What does the POV character want in this scene?
• Conflict: What opposes their goal?
• Outcome: How does the scene end? (typically with a complication)
• Character Development: What arc beats occur here?
• Plot Advancement: What story questions are raised or answered?

Step 3: Structure the Chapter

Apply scene structure components:

Scene (Action)

1. Goal - What the POV character pursues
2. Conflict - Opposition encountered
3. Disaster - Negative outcome that propels forward

Sequel (Reaction)

1. Reaction - Emotional response to disaster
2. Dilemma - Processing options
3. Decision - Choice leading to next goal

Alternate between high-tension (action, conflict) and low-tension (reflection, world-building) beats for pacing.

Step 4: Write with Character Consistency

Maintain character voice by referencing:

• Established personality traits
• Speech patterns and vocabulary
• Behavioral patterns (under stress, when happy, decision-making style)
• Current position in character arc
• Relationships with other characters present

Step 5: Integrate Timeline Markers

Include timeline references to maintain chronological clarity:

• Explicit markers: "Day 3," "Two weeks later"
• Implicit markers: Time of day, seasonal cues, event references
• Format: **Timeline:** Day 5, Evening in chapter header or as section break

Step 6: Create Chapter File

Write chapter content to chapters/chapter-[number].md or chapters/[chapter-name].md. Include:

Chapter Header

# Chapter [Number]: [Optional Title]

**Timeline:** [When this occurs]
**POV:** [Character name]
**Location:** [Where this takes place]

Chapter Content

• Scene-by-scene breakdown
• Dialogue and action
• Character thoughts (for POV character)
• Descriptive elements

Step 7: Note Continuity Elements

After writing, document any new information introduced:

• Character revelations or development
• Plot points or clues
• World-building details
• Timeline events

This helps maintain consistency in future chapters.

Timeline Tracking

When to Use Timeline Tracking

Invoke the timeline tracker when:

• User requests timeline analysis or event sequencing
• Checking chronological consistency
• Planning event order across chapters
• Identifying unmarked time periods

Running the Timeline Tracker

Execute the script from the project root:

python3 .claude/skills/storyboard-manager/scripts/timeline_tracker.py . --output markdown

Output format options:

• markdown - Human-readable report (default)
• json - Structured data for further processing

Understanding Timeline Output

The script provides:

Statistics

• Total events tracked
• Total characters appearing
• Events per character

Timeline View

• Chronological sequence of events
• Chapter/scene locations
• Characters present in each event
• Preview of event content

Warnings

• Events without timeline markers
• Characters mentioned but not defined in character files

Acting on Timeline Results

After running the tracker:

1. Review warnings - Address missing timeline markers by adding them to chapters
2. Check sequence - Verify events occur in logical order
3. Identify gaps - Look for time periods without events
4. Character tracking - Ensure characters appear consistently with their arc

Add timeline markers to chapters where missing:

**Timeline:** Day 7, Morning

Or use inline markers:

Three days had passed since the incident...

Consistency Checking

When to Use Consistency Checking

Invoke the consistency checker when:

• User requests consistency analysis
• Before finalizing chapters or acts
• After making significant character or plot changes
• When tracking contradictions or errors

Running the Consistency Checker

Execute the script from the project root:

python3 .claude/skills/storyboard-manager/scripts/consistency_checker.py . --output markdown

Output format options:

• markdown - Human-readable report with issue details (default)
• json - Structured data for programmatic analysis

Understanding Consistency Output

The script identifies issues in three severity levels:

Critical (🔴)

• Major contradictions requiring immediate attention
• Character appearing after death
• Fundamental plot contradictions

Warning (⚠️)

• Potential inconsistencies to review
• Age discrepancies
• Physical description contradictions
• Relationship conflicts

Info (ℹ️)

• Minor issues or variations
• Name capitalization inconsistencies
• Stylistic variations

Acting on Consistency Results

For each issue reported:

1. Read flagged locations - Review the specific files mentioned
2. Determine truth - Decide which version is correct (usually character profile is authoritative)
3. Update files - Fix contradictions using the Edit tool
4. Re-run checker - Verify fixes resolved the issues

Example workflow for character age inconsistency:

Issue: Age inconsistency for Maya
- Profile: 18 years old
- Chapter 3: mentions "21-year-old Maya"

Fix: Edit chapter-3.md to change "21-year-old" to "18-year-old"

Consistency Checking Limitations

The automated checker catches:

• Physical attribute contradictions
• Age discrepancies
• Name variations
• Basic world-building facts

The checker cannot catch:

• Subtle personality inconsistencies
• Complex plot logic errors
• Thematic contradictions
• Nuanced relationship changes

Manual review is still essential for deep consistency.

Best Practices

Progressive Context Loading

Don't load all reference files at once. Instead:

1. Scan project structure first
2. Read only relevant character files for the current task
3. Access reference documentation only when specific guidance is needed
4. Use Grep to find specific sections in large reference files

Maintaining Genre Voice

Match the story's established tone:

• YA: Present tense, immediate emotional connection, contemporary language
• Fantasy: Rich descriptive language, world-building integration
• Thriller: Short sentences, high tension, sensory details
• Literary: Complex prose, internal reflection, symbolic elements

Reference the summary.md to identify target audience and adjust accordingly.

Character Arc Integration

Every chapter should serve character arcs:

• Track where each character is in their arc
• Show incremental change, not sudden transformation
• Use plot events to test character beliefs
• Demonstrate growth through choices and behavior

Balancing Show vs. Tell

For narrative writing:

• Show emotions through actions, dialogue, physical reactions
• Tell to compress time, provide necessary information efficiently
• Use character-filtered description (what would this POV character notice?)

Handling Multiple POV

When stories have multiple perspectives:

• Create distinct voices for each POV character
• Ensure each POV section advances both that character's arc and the plot
• Vary sentence structure and vocabulary by character
• Track what each character knows vs. doesn't know

Common User Requests & Responses

"Help me develop a character backstory"

1. Read existing character files for context
2. Read the character profile (if exists) to enhance
3. Access character_development.md reference for backstory framework
4. Create detailed backstory covering: ghost/wound, formative relationships, key history
5. Integrate with their character arc and story role

"Write the next chapter"

1. Read summary.md and story planning documents
2. Read all character profiles for characters appearing in chapter
3. Read previous 2 chapters for continuity
4. Identify chapter position in story structure
5. Write chapter with scene/sequel structure
6. Include timeline markers and POV/location headers

"Outline Act 2"

1. Read summary and any existing planning documents
2. Access story_structures.md for structural guidance
3. Identify act 2 requirements (complications, midpoint, rising tension)
4. Create beat-by-beat outline aligned with character arcs
5. Note how plot and character arcs intersect

"Check my story for consistency"

1. Run consistency_checker.py script
2. Review output identifying issues
3. Read flagged files to understand contradictions
4. Recommend specific fixes for each issue
5. Offer to make edits if user confirms

"Track the timeline of my story"

1. Run timeline_tracker.py script
2. Review output showing event sequence
3. Identify gaps or inconsistencies in chronology
4. Recommend adding timeline markers where missing
5. Provide timeline summary organized by character or chapter

"What structure should I use for my thriller?"

1. Access story_structures.md reference
2. Recommend Three-Act Structure or Save the Cat
3. Explain thriller-specific requirements (escalating tension, ticking clock)
4. Provide beat sheet adapted to their story concept
5. Offer to create detailed planning document

Resources

scripts/timeline_tracker.py

Python script that analyzes markdown files to extract and organize timeline events. Tracks character appearances, identifies time markers, groups events chronologically, and flags consistency issues.

Usage: Run from project root with python3 .claude/skills/storyboard-manager/scripts/timeline_tracker.py .

scripts/consistency_checker.py

Python script that detects inconsistencies in character details, physical descriptions, ages, names, and world-building facts across all story files. Outputs severity-ranked issues with file locations.

Usage: Run from project root with python3 .claude/skills/storyboard-manager/scripts/consistency_checker.py .

references/character_development.md

Comprehensive framework for creating multi-dimensional characters including core elements, backstory structure, arc types, relationship dynamics, voice development, and consistency guidelines.

Load when: Developing new characters, enhancing existing profiles, resolving character consistency issues, or planning character arcs.

references/story_structures.md

Detailed reference covering major story structures (Three-Act, Hero's Journey, Save the Cat), character arc templates, scene structure, pacing guidelines, plot development techniques, and genre-specific structures.

Load when: Planning story outline, structuring acts, organizing plot beats, determining pacing, or applying specific narrative frameworks.

Technical Debt Analyzer

Overview

Systematically identify, analyze, document, and track technical debt in JavaScript/TypeScript codebases. This skill provides automated analysis tools, comprehensive debt categorization frameworks, and documentation templates to maintain a technical debt register.

Core Workflow

1. Automated Analysis

Run automated scripts to detect technical debt indicators across the codebase.

Code Smell Detection

Identify code quality issues using the automated detector:

python3 scripts/detect_code_smells.py src --output markdown

The script analyzes:

• Large Files: Files exceeding 500 lines
• Complex Functions: High cyclomatic complexity (>10) or long functions (>50 lines)
• Debt Markers: TODO, FIXME, HACK, XXX, BUG comments
• Console Statements: Debug statements left in code
• Weak Typing: Use of any type in TypeScript
• Long Parameters: Functions with >5 parameters
• Deep Nesting: Code nested >4 levels deep
• Magic Numbers: Hardcoded numeric values

Output Example:

# Technical Debt Analysis Report

**Files Analyzed:** 127
**Total Lines:** 15,432
**Total Issues:** 89

### Issues by Severity
- HIGH: 23
- MEDIUM: 41
- LOW: 25

## Large Files (12 issues)
### High Priority
- src/components/Dashboard.tsx (847 lines): File too large
- src/services/DataProcessor.ts (623 lines): File too large
...

Dependency Analysis

Examine dependencies for debt indicators:

python3 scripts/analyze_dependencies.py package.json

The script identifies:

• Deprecated Packages: Known deprecated libraries (request, tslint, etc.)
• Duplicate Functionality: Multiple packages serving same purpose
• Version Issues: Overly loose or strict version constraints
• Security Concerns: Known vulnerable packages (requires audit data)

Output Example:

# Dependency Analysis Report

**Package:** expense-tracker
**Dependencies:** 24
**Dev Dependencies:** 18
**Total Issues:** 7

## Deprecated/Outdated Packages (3)
### request [HIGH]
Using deprecated package - use axios, node-fetch, or got instead
- Current version: ^2.88.0

## Duplicate Functionality (2)
### HTTP client [MEDIUM]
Multiple packages for HTTP client: axios, node-fetch

2. Manual Code Review

Complement automated analysis with manual review for issues that require human judgment.

Review Focus Areas

Architectural Debt:

• Tight coupling between components
• Missing abstractions
• Poor separation of concerns
• Circular dependencies

Test Debt:

• Missing test coverage for critical paths
• Fragile tests coupled to implementation
• No integration or E2E tests
• Slow test execution

Documentation Debt:

• Missing README or setup instructions
• No architecture documentation
• Outdated API docs
• Missing ADRs for major decisions

Performance Debt:

• N+1 query problems
• Inefficient algorithms
• Memory leaks
• Large bundle sizes

Security Debt:

• Missing input validation
• No authentication/authorization
• SQL injection vulnerabilities
• XSS vulnerabilities
• Exposed secrets

3. Categorize and Assess

Organize findings using the standardized debt categories.

Debt Categories

Refer to references/debt_categories.md for comprehensive details on:

1. Code Quality Debt: Code smells, complexity, duplication
2. Architectural Debt: Structure, coupling, abstractions
3. Test Debt: Coverage gaps, fragile tests
4. Documentation Debt: Missing or outdated docs
5. Dependency Debt: Outdated or problematic dependencies
6. Performance Debt: Inefficiencies and bottlenecks
7. Security Debt: Vulnerabilities and weaknesses
8. Infrastructure Debt: DevOps and deployment issues
9. Design Debt: UI/UX inconsistencies

Severity Assessment

Assign severity based on impact and urgency:

Critical:

• Security vulnerabilities
• Production-breaking issues
• Data loss risks
• Action: Immediate fix required

High:

• Significant performance problems
• Architectural issues blocking features
• High-risk untested code
• Action: Fix within current/next sprint

Medium:

• Code quality issues in frequently changed files
• Missing documentation
• Outdated dependencies (non-security)
• Action: Address within quarter

Low:

• Minor code smells
• Optimization opportunities
• Nice-to-have improvements
• Action: Address when convenient

Priority Matrix

4. Document Findings

Create comprehensive documentation of technical debt.

Technical Debt Register

Use the provided template to maintain a debt register:

Template Location: assets/DEBT_REGISTER_TEMPLATE.md

Structure:

## DEBT-001: Complex UserService with 847 lines

**Category:** Code Quality
**Severity:** High
**Location:** src/services/UserService.ts

**Description:**
UserService has grown to 847 lines with multiple responsibilities
including authentication, profile management, and notification handling.

**Impact:**
- Business: Slows down feature development by 30%
- Technical: Difficult to test, high bug rate
- Risk: Changes frequently break unrelated functionality

**Proposed Solution:**
Split into separate services:
- AuthenticationService
- UserProfileService
- NotificationService

**Effort Estimate:** 3 days
**Priority Justification:** High churn area blocking new features
**Target Resolution:** Sprint 24

Register Sections:

1. Active Debt Items: Current technical debt needing attention
2. Resolved Items: Historical record of fixed debt
3. Won't Fix Items: Debt accepted as acceptable trade-off
4. Trends: Analysis by category, severity, and age
5. Review Schedule: Regular maintenance plan

Architecture Decision Records (ADRs)

Document major technical decisions using ADRs to prevent future debt.

Template Location: assets/ADR_TEMPLATE.md

When to Create ADRs:

• Choosing frameworks or libraries
• Architectural changes
• Major refactoring decisions
• Technology migrations
• Performance optimization strategies

Example:

# ADR-003: Migrate from Moment.js to date-fns

**Status:** Accepted
**Date:** 2024-01-15

## Context
Moment.js is deprecated and increases bundle size by 67KB.
Team needs a modern date library with tree-shaking support.

## Decision
Migrate to date-fns for date manipulation.

## Consequences
- Positive: Reduce bundle by 60KB, modern API, active maintenance
- Negative: Migration effort, learning curve for team
- Technical Debt: None - this resolves existing dependency debt

5. Prioritize and Plan

Create actionable plans to address technical debt.

Prioritization Approach

1. Critical Items: Add to current sprint immediately
2. High Items: Include in sprint planning
3. Medium Items: Add to quarterly roadmap
4. Low Items: Opportunistic fixes during related work

Time Allocation

Recommended Allocation:

• 20% of sprint capacity for technical debt
• Alternating sprints: feature sprint / debt sprint
• Dedicated quarterly "tech health" sprint

Tracking Progress

Monitor debt reduction over time:

Metrics to Track:

• Total debt items (trend down)
• Debt by severity (critical should be 0)
• Debt age (old debt is concerning)
• Resolution rate (items fixed per sprint)
• New debt rate (items added per sprint)

6. Prevention Strategies

Implement practices to minimize new technical debt.

Code Review Checklist

Before approving PRs, verify:

• No code smells introduced (complexity, size, nesting)
• Tests added/updated with adequate coverage
• Documentation updated (README, comments, ADRs)
• No security vulnerabilities
• Performance impact considered
• No new dependencies without justification
• Follows team conventions and patterns

Automated Prevention

Linting and Formatting:

{
  "rules": {
    "complexity": ["error", 10],
    "max-lines-per-function": ["error", 50],
    "max-params": ["error", 5],
    "max-depth": ["error", 4],
    "no-console": "warn"
  }
}

Required Checks:

• TypeScript strict mode enabled
• Minimum test coverage threshold (80%)
• No high-severity security vulnerabilities
• Bundle size limits enforced

Regular Maintenance

Weekly:

• Review and triage TODO/FIXME comments
• Update debt register with new findings

Monthly:

• Dependency updates (security patches)
• Debt register review
• Plan fixes for high-priority items

Quarterly:

• Full codebase debt analysis
• Architecture review
• Major dependency updates
• Trend analysis and strategy adjustment

Decision Tree

Follow this workflow based on the situation:

Starting a new analysis? → Run automated scripts (detect_code_smells.py, analyze_dependencies.py) → Review output for high-severity issues → Conduct manual review for areas scripts can't detect → Go to documentation step

Documenting findings? → Copy DEBT_REGISTER_TEMPLATE.md to project root → Add each debt item with full details → Categorize by type and assign severity → Estimate effort and prioritize → Go to planning step

Planning debt reduction? → Sort by priority matrix (impact/effort) → Allocate sprint capacity (20% recommended) → Create tickets for top priority items → Schedule regular reviews

Making architectural decisions? → Copy ADR_TEMPLATE.md → Document context, options, and decision → Identify any debt being incurred → Add to debt register if applicable

Preventing new debt? → Implement code review checklist → Configure automated linting/testing → Set up regular maintenance schedule → Monitor metrics over time

Tools and Scripts

detect_code_smells.py

Purpose: Automated code quality analysis

Usage:

python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]

Detects:

• Large files (>500 lines)
• Complex functions (complexity >10)
• Technical debt markers (TODO, FIXME, HACK)
• Console statements
• Weak TypeScript typing
• Long parameter lists (>5 params)
• Deep nesting (>4 levels)
• Magic numbers

Output: Markdown report or JSON for programmatic processing

analyze_dependencies.py

Purpose: Dependency health analysis

Usage:

python3 scripts/analyze_dependencies.py [package.json-path]

Detects:

• Deprecated packages (request, tslint, node-sass, etc.)
• Duplicate functionality (multiple date libs, http clients, etc.)
• Unsafe version constraints (*, latest)
• Overly strict versions (exact versions without ^ or ~)

Output: Markdown report with recommendations

Reference Documentation

debt_categories.md

Comprehensive guide to technical debt types with:

• 9 major debt categories
• Indicators and examples for each
• Impact assessment criteria
• Severity level definitions
• Measurement metrics
• Prevention strategies

Load this reference when:

• Need detailed examples of specific debt types
• Assessing severity and impact
• Understanding root causes
• Planning prevention strategies

Documentation Templates

DEBT_REGISTER_TEMPLATE.md

Complete technical debt register template including:

• Debt item structure
• Status tracking
• Impact assessment format
• Trend analysis sections
• Review schedule

Use this template to:

• Start a new debt register
• Standardize debt documentation
• Track debt across team/project

ADR_TEMPLATE.md

Architecture Decision Record template including:

• Context and problem statement
• Options considered
• Decision rationale
• Consequences (positive and negative)
• Implementation plan

Use this template to:

• Document major technical decisions
• Prevent future "why did we do this?" questions
• Track technical debt incurred by decisions

Best Practices

Analysis Best Practices

1. Run analysis regularly (weekly or bi-weekly)
2. Combine automated + manual review for comprehensive coverage
3. Focus on high-churn areas first for maximum impact
4. Involve the team in debt identification
5. Be objective - all codebases have debt

Documentation Best Practices

1. Be specific - include file names, line numbers, examples
2. Explain impact - why does this matter?
3. Propose solutions - don't just complain, suggest fixes
4. Estimate effort - helps with prioritization
5. Track trends - is debt increasing or decreasing?

Remediation Best Practices

1. Fix critical items immediately - especially security
2. Allocate consistent time - 20% of sprint capacity
3. Celebrate wins - track and recognize debt reduction
4. Don't let perfect be the enemy of good - incremental improvement
5. Prevent new debt - easier than fixing old debt

Communication Best Practices

1. Make debt visible - share metrics with stakeholders
2. Educate on impact - connect debt to business outcomes
3. Get buy-in - explain ROI of debt reduction
4. Regular updates - include in sprint reviews
5. Avoid blame - focus on improvement, not fault

Example Workflow

Complete workflow from analysis to resolution:

Week 1: Analysis

# Run automated analysis
python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md
python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md

# Manual review of critical areas
# - Authentication logic
# - Payment processing
# - Data models

Week 1-2: Documentation

# Create debt register from template
cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md

# Add findings to register with:
# - Category and severity
# - Impact assessment
# - Effort estimation
# - Priority assignment

Week 2: Prioritization

# Team review session
# - Review all high/critical items
# - Discuss quick wins (high impact, low effort)
# - Allocate sprint capacity
# - Create tickets for top 5 items

Weeks 3-6: Remediation

# Sprint work
# - Fix 2-3 debt items per sprint
# - Update debt register as items resolved
# - Create ADRs for major refactoring decisions
# - Monitor metrics

Monthly: Review

# Trend analysis
# - Total debt (should decrease)
# - New debt rate (should be low)
# - Age of oldest items (should decrease)
# - Categories most affected

# Adjust strategy based on trends

Success Metrics

Track these metrics to measure debt reduction effectiveness:

Quantity Metrics:

• Total debt items (trending down)
• Debt by severity (zero critical)
• Debt items per 1000 LOC

Quality Metrics:

• Test coverage (trending up)
• Cyclomatic complexity (trending down)
• Average file/function size (stable or decreasing)

Velocity Metrics:

• Debt items resolved per sprint
• New debt items per sprint (should be low)
• Time to resolve (should decrease)

Business Metrics:

• Bug rate (should decrease)
• Feature delivery speed (should increase)
• Developer satisfaction (should increase)

Test Specialist

Overview

Apply systematic testing methodologies and debugging techniques to JavaScript/TypeScript applications. This skill provides comprehensive testing strategies, bug analysis frameworks, and automated tools for identifying coverage gaps and untested code.

Core Capabilities

1. Writing Test Cases

Write comprehensive tests covering unit, integration, and end-to-end scenarios.

Unit Testing Approach

Structure tests using the AAA pattern (Arrange-Act-Assert):

describe('ExpenseCalculator', () => {
  describe('calculateTotal', () => {
    test('sums expense amounts correctly', () => {
      // Arrange
      const expenses = [
        { amount: 100, category: 'food' },
        { amount: 50, category: 'transport' },
        { amount: 25, category: 'entertainment' }
      ];

      // Act
      const total = calculateTotal(expenses);

      // Assert
      expect(total).toBe(175);
    });

    test('handles empty expense list', () => {
      expect(calculateTotal([])).toBe(0);
    });

    test('handles negative amounts', () => {
      const expenses = [
        { amount: 100, category: 'food' },
        { amount: -50, category: 'refund' }
      ];
      expect(calculateTotal(expenses)).toBe(50);
    });
  });
});

Key principles:

• Test one behavior per test
• Cover happy path, edge cases, and error conditions
• Use descriptive test names that explain the scenario
• Keep tests independent and isolated

Integration Testing Approach

Test how components work together, including database, API, and service interactions:

describe('ExpenseAPI Integration', () => {
  beforeAll(async () => {
    await database.connect(TEST_DB_URL);
  });

  afterAll(async () => {
    await database.disconnect();
  });

  beforeEach(async () => {
    await database.clear();
    await seedTestData();
  });

  test('POST /expenses creates expense and updates total', async () => {
    const response = await request(app)
      .post('/api/expenses')
      .send({
        amount: 50,
        category: 'food',
        description: 'Lunch'
      })
      .expect(201);

    expect(response.body).toMatchObject({
      id: expect.any(Number),
      amount: 50,
      category: 'food'
    });

    // Verify database state
    const total = await getTotalExpenses();
    expect(total).toBe(50);
  });
});

End-to-End Testing Approach

Test complete user workflows using tools like Playwright or Cypress:

test('user can track expense from start to finish', async ({ page }) => {
  // Navigate to app
  await page.goto('/');

  // Add new expense
  await page.click('[data-testid="add-expense-btn"]');
  await page.fill('[data-testid="amount"]', '50.00');
  await page.selectOption('[data-testid="category"]', 'food');
  await page.fill('[data-testid="description"]', 'Lunch');
  await page.click('[data-testid="submit"]');

  // Verify expense appears in list
  await expect(page.locator('[data-testid="expense-item"]')).toContainText('Lunch');
  await expect(page.locator('[data-testid="total"]')).toContainText('$50.00');
});

2. Systematic Bug Analysis

Apply structured debugging methodology to identify and fix issues.

Five-Step Analysis Process

1. Reproduction: Reliably reproduce the bug

   • Document exact steps to trigger
   • Identify required environment/state
   • Note expected vs actual behavior

2. Isolation: Narrow down the problem

   • Binary search through code path
   • Create minimal reproduction case
   • Remove unrelated dependencies

3. Root Cause Analysis: Determine underlying cause

   • Trace execution flow
   • Check assumptions and preconditions
   • Review recent changes (git blame)

4. Fix Implementation: Implement solution

   • Write failing test first (TDD)
   • Implement the fix
   • Verify test passes

5. Validation: Ensure completeness

   • Run full test suite
   • Test edge cases
   • Verify no regressions

Common Bug Patterns

Race Conditions:

// Test concurrent operations
test('handles concurrent updates correctly', async () => {
  const promises = Array.from({ length: 100 }, () =>
    incrementExpenseCount()
  );

  await Promise.all(promises);
  expect(getExpenseCount()).toBe(100);
});

Null/Undefined Errors:

// Test null safety
test.each([null, undefined, '', 0, false])
  ('handles invalid input: %p', (input) => {
    expect(() => processExpense(input)).toThrow('Invalid expense');
  });

Off-by-One Errors:

// Test boundaries explicitly
describe('pagination', () => {
  test('handles empty list', () => {
    expect(paginate([], 1, 10)).toEqual([]);
  });

  test('handles single item', () => {
    expect(paginate([item], 1, 10)).toEqual([item]);
  });

  test('handles last page with partial items', () => {
    const items = Array.from({ length: 25 }, (_, i) => i);
    expect(paginate(items, 3, 10)).toHaveLength(5);
  });
});

3. Identifying Potential Issues

Proactively identify issues before they become bugs.

Security Vulnerabilities

Test for common security issues:

describe('security', () => {
  test('prevents SQL injection', async () => {
    const malicious = "'; DROP TABLE expenses; --";
    await expect(
      searchExpenses(malicious)
    ).resolves.not.toThrow();
  });

  test('sanitizes XSS in descriptions', () => {
    const xss = '<script>alert("xss")</script>';
    const expense = createExpense({ description: xss });
    expect(expense.description).not.toContain('<script>');
  });

  test('requires authentication for expense operations', async () => {
    await request(app)
      .post('/api/expenses')
      .send({ amount: 50 })
      .expect(401);
  });
});

Performance Issues

Test for performance problems:

test('processes large expense list efficiently', () => {
  const largeList = Array.from({ length: 10000 }, (_, i) => ({
    amount: i,
    category: 'test'
  }));

  const start = performance.now();
  const total = calculateTotal(largeList);
  const duration = performance.now() - start;

  expect(duration).toBeLessThan(100); // Should complete in <100ms
  expect(total).toBe(49995000);
});

Logic Errors

Use parameterized tests to catch edge cases:

test.each([
  // [input, expected, description]
  [[10, 20, 30], 60, 'normal positive values'],
  [[0, 0, 0], 0, 'all zeros'],
  [[-10, 20, -5], 5, 'mixed positive and negative'],
  [[0.1, 0.2], 0.3, 'decimal precision'],
  [[Number.MAX_SAFE_INTEGER], Number.MAX_SAFE_INTEGER, 'large numbers'],
])('calculateTotal(%p) = %p (%s)', (amounts, expected, description) => {
  const expenses = amounts.map(amount => ({ amount, category: 'test' }));
  expect(calculateTotal(expenses)).toBeCloseTo(expected);
});

4. Test Coverage Analysis

Use automated tools to identify gaps in test coverage.

Finding Untested Code

Run the provided script to identify source files without tests:

python3 scripts/find_untested_code.py src

The script will:

• Scan source directory for all code files
• Identify which files lack corresponding test files
• Categorize untested files by type (components, services, utils, etc.)
• Prioritize files that need testing most

Interpretation:

• API/Services: High priority - test business logic and data operations
• Models: High priority - test data validation and transformations
• Hooks: Medium priority - test stateful behavior
• Components: Medium priority - test complex UI logic
• Utils: Low priority - test as needed for complex functions

Analyzing Coverage Reports

Run the coverage analysis script after generating coverage:

# Generate coverage (using Jest example)
npm test -- --coverage

# Analyze coverage gaps
python3 scripts/analyze_coverage.py coverage/coverage-final.json

The script identifies:

• Files below coverage threshold (default 80%)
• Statement, branch, and function coverage percentages
• Priority files to improve

Coverage targets:

• Critical paths: 90%+ coverage
• Business logic: 85%+ coverage
• UI components: 75%+ coverage
• Utilities: 70%+ coverage

5. Test Maintenance and Quality

Ensure tests remain valuable and maintainable.

Test Code Quality Principles

DRY (Don't Repeat Yourself):

// Extract common setup
function createTestExpense(overrides = {}) {
  return {
    amount: 50,
    category: 'food',
    description: 'Test expense',
    date: new Date('2024-01-01'),
    ...overrides
  };
}

test('filters by category', () => {
  const expenses = [
    createTestExpense({ category: 'food' }),
    createTestExpense({ category: 'transport' }),
  ];
  // ...
});

Clear test data:

// Bad: Magic numbers
expect(calculateDiscount(100, 0.15)).toBe(85);

// Good: Named constants
const ORIGINAL_PRICE = 100;
const DISCOUNT_RATE = 0.15;
const EXPECTED_PRICE = 85;
expect(calculateDiscount(ORIGINAL_PRICE, DISCOUNT_RATE)).toBe(EXPECTED_PRICE);

Avoid test interdependence:

// Bad: Tests depend on execution order
let sharedState;
test('test 1', () => {
  sharedState = { value: 1 };
});
test('test 2', () => {
  expect(sharedState.value).toBe(1); // Depends on test 1
});

// Good: Independent tests
test('test 1', () => {
  const state = { value: 1 };
  expect(state.value).toBe(1);
});
test('test 2', () => {
  const state = { value: 1 };
  expect(state.value).toBe(1);
});

Workflow Decision Tree

Follow this decision tree to determine the testing approach:

1. Adding new functionality?

   • Yes → Write tests first (TDD)
     • Write failing test
     • Implement feature
     • Verify test passes
     • Refactor
   • No → Go to step 2

2. Fixing a bug?

   • Yes → Apply bug analysis process
     • Reproduce the bug
     • Write failing test demonstrating bug
     • Fix the implementation
     • Verify test passes
   • No → Go to step 3

3. Improving test coverage?

   • Yes → Use coverage tools
     • Run find_untested_code.py to identify gaps
     • Run analyze_coverage.py on coverage reports
     • Prioritize critical paths
     • Write tests for untested code
   • No → Go to step 4

4. Analyzing code quality?

   • Yes → Systematic review
     • Check for security vulnerabilities
     • Test edge cases and error handling
     • Verify performance characteristics
     • Review error handling

Testing Frameworks and Tools

Recommended Stack

Unit/Integration Testing:

• Jest or Vitest for test runner
• Testing Library for React components
• Supertest for API testing
• MSW (Mock Service Worker) for API mocking

E2E Testing:

• Playwright or Cypress
• Page Object Model pattern

Coverage:

• Istanbul (built into Jest/Vitest)
• Coverage reports in JSON format

Running Tests

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test -- ExpenseCalculator.test.ts

# Run in watch mode
npm test -- --watch

# Run E2E tests
npm run test:e2e

Reference Documentation

For detailed patterns and techniques, refer to:

• references/testing_patterns.md - Comprehensive testing patterns, best practices, and code examples
• references/bug_analysis.md - In-depth bug analysis framework, common bug patterns, and debugging techniques

These references contain extensive examples and advanced techniques. Load them when:

• Dealing with complex testing scenarios
• Need specific pattern implementations
• Debugging unusual issues
• Seeking best practices for specific situations

Scripts

analyze_coverage.py

Analyze Jest/Istanbul coverage reports to identify gaps:

python3 scripts/analyze_coverage.py [coverage-file]

Automatically finds common coverage file locations if not specified.

Output:

• Files below coverage threshold
• Statement, branch, and function coverage percentages
• Priority files to improve

find_untested_code.py

Find source files without corresponding test files:

python3 scripts/find_untested_code.py [src-dir] [--pattern test|spec]

Output:

• Total source and test file counts
• Test file coverage percentage
• Untested files categorized by type (API, services, components, etc.)
• Recommendations for prioritization

Best Practices Summary

1. Write tests first (TDD) when adding new features
2. Test behavior, not implementation - tests should survive refactoring
3. Keep tests independent - no shared state between tests
4. Use descriptive names - test names should explain the scenario
5. Cover edge cases - null, empty, boundary values, error conditions
6. Mock external dependencies - tests should be fast and reliable
7. Maintain high coverage - 80%+ for critical code
8. Fix failing tests immediately - never commit broken tests
9. Refactor tests - apply same quality standards as production code
10. Use tools - automate coverage analysis and gap identification

Finance Manager

A comprehensive toolkit for personal finance management that processes transaction data, performs sophisticated financial analysis, generates actionable insights, and creates beautiful visual reports.

Core Capabilities

1. Transaction Data Processing: Extract financial data from PDFs, CSVs, or JSON files
2. Financial Analysis: Calculate key metrics, identify spending patterns, and track savings
3. Visualization: Generate interactive HTML reports with charts and graphs
4. Budget Recommendations: Provide personalized, actionable advice based on spending patterns
5. Trend Analysis: Identify spending patterns, anomalies, and opportunities for optimization

Workflow

1. Data Extraction and Preparation

For PDF files:

python scripts/extract_pdf_data.py <input.pdf> <output.csv>

For CSV/JSON files:

• Ensure data has columns: Date, Description, Income (category), Type, Amount
• Date format: YYYY-MM-DD or parseable date string
• Amount: Positive for income, negative for expenses

2. Financial Analysis

Run comprehensive analysis on transaction data:

python scripts/analyze_finances.py <transactions.csv> > analysis_output.json

Output includes:

• Summary statistics (total income, expenses, net savings, savings rate)
• Spending trends (daily averages, top expenses, category percentages)
• Budget recommendations (personalized based on spending patterns)
• Visualization data (prepared for charting)

3. Report Generation

Create interactive HTML report with visualizations:

python scripts/generate_report.py <analysis_output.json> <report.html>

Report features:

• Summary dashboard with key metrics
• Interactive pie chart showing spending by category
• Bar chart comparing income vs expenses over time
• Color-coded indicators (green for positive, red for negative)
• Personalized recommendations section
• Responsive design for all devices

4. Complete Workflow Example

# Extract data from PDF
python scripts/extract_pdf_data.py finance_data.pdf transactions.csv

# Analyze the data
python scripts/analyze_finances.py transactions.csv > analysis.json

# Generate visual report
python scripts/generate_report.py analysis.json financial_report.html

Key Metrics and Benchmarks

Savings Rate

Savings Rate = (Total Income - Total Expenses) / Total Income × 100

Benchmarks:

• Below 10%: Needs improvement
• 10-20%: Good
• 20-30%: Excellent
• Above 30%: Outstanding

Category Guidelines (% of income)

• Housing: 25-30%
• Transportation: 10-15%
• Food: 10-15%
• Utilities: 5-10%
• Savings: Minimum 20%

For detailed frameworks and methodologies, see references/financial_frameworks.md.

Analysis Features

Summary Statistics

• Total income and expenses for the period
• Net savings (can be positive or negative)
• Savings rate percentage
• Transaction count
• Date range covered

Spending Trends

• Daily average spending
• Top 5 largest expenses with details
• Category percentage breakdown
• Spending patterns over time

Budget Recommendations

The system generates personalized recommendations based on:

• Savings rate thresholds
• Category spending percentages
• Income diversification
• Budget guideline comparisons

Example recommendations:

• "⚠️ Your savings rate is below 10%. Consider reducing discretionary spending."
• "🍽️ Food spending is 18% of expenses. Consider meal planning to reduce costs."
• "✅ Excellent savings rate! You're on track for strong financial health."

Visualization Components

Category Spending Chart (Doughnut)

Shows proportional breakdown of expenses by category with color coding.

Income vs Expenses Chart (Bar)

Displays monthly comparison of income and expenses to identify cash flow trends.

Interactive Features

• Hover tooltips showing exact values
• Responsive design adapting to screen size
• Color-coded positive (green) and negative (red) indicators

Tips for Best Results

Data Quality

• Ensure all transactions are properly categorized
• Use consistent category names
• Include complete date information
• Verify amounts are correctly signed (+ for income, - for expenses)

Analysis Frequency

• Run monthly analysis for trend tracking
• Generate reports at month-end for review
• Compare month-over-month to identify changes

Action on Recommendations

• Prioritize recommendations by potential impact
• Set specific, measurable goals based on insights
• Track progress by re-running analysis regularly

Dependencies

All scripts require Python 3.7+ with standard libraries. Additional requirements:

For PDF extraction:

pip install pdfplumber --break-system-packages

For data analysis:

pip install pandas --break-system-packages

All visualization dependencies are loaded from CDN in the HTML output (Chart.js).

File Organization

finance-manager/
├── scripts/
│   ├── extract_pdf_data.py     # PDF → CSV conversion
│   ├── analyze_finances.py     # Financial analysis engine
│   └── generate_report.py      # HTML report generator
└── references/
    └── financial_frameworks.md # Detailed analysis methodologies

Customization

Adding Custom Categories

Edit the category definitions in analyze_finances.py to match your tracking system.

Adjusting Thresholds

Modify recommendation thresholds in the generate_budget_recommendations() function to match personal goals.

Styling Reports

Customize the HTML_TEMPLATE in generate_report.py to adjust colors, fonts, or layout.

Common Use Cases

Monthly Review: "Analyze my October spending and create a report"

Budget Optimization:
"Where am I spending too much money?"

Trend Analysis: "How does my spending this month compare to last month?"

Goal Setting: "What's my savings rate and how can I improve it?"

Category Insights: "Break down my food spending by transaction"

PDF Processing: "Extract all transactions from my bank statement PDF"

Best Practices

1. Consistent Categorization: Use the same category names across all transactions
2. Regular Analysis: Run monthly to spot trends early
3. Act on Insights: Use recommendations to make specific spending changes
4. Track Progress: Compare reports month-over-month
5. Verify Data: Always check extracted PDF data for accuracy before analysis

Reference Materials

For comprehensive financial frameworks, budgeting guidelines, and analysis methodologies, read:

view references/financial_frameworks.md

This includes:

• The 50/30/20 budget rule
• Category spending benchmarks
• Financial health indicators
• Analysis workflow details
• Visualization best practices
• Recommendation logic

Personal Assistant

Overview

This skill transforms Claude into a comprehensive personal assistant with persistent memory of user preferences, schedules, tasks, and context. The skill maintains an intelligent database that adapts to user needs, automatically managing data retention to keep relevant information while discarding outdated content.

When to Use This Skill

Invoke this skill for personal assistance queries, including:

• Task management and to-do lists
• Schedule and calendar management
• Reminder setting and tracking
• Habit monitoring and productivity tips
• Time management and planning
• Personal goal tracking
• Routine optimization
• Preference-based recommendations
• Context-aware assistance

Workflow

Step 1: Check for Existing Profile

Before providing any personalized assistance, always check if a user profile exists:

python3 scripts/assistant_db.py has_profile

If the output is "false", proceed to Step 2 (Initial Setup). If "true", proceed to Step 3 (Load Profile and Context).

Step 2: Initial Profile Setup (First Run Only)

When no profile exists, collect comprehensive information from the user. Use a conversational, friendly approach to gather this data.

Essential Information to Collect:

1. Personal Details

   • Name and preferred form of address
   • Timezone
   • Location (city/country)

2. Schedule & Working Habits

   • Typical work hours
   • Work schedule type (9-5, flexible, shift work, etc.)
   • Preferred working times (morning person vs night owl)
   • Break preferences
   • Meeting preferences

3. Goals & Priorities

   • Short-term goals (next 1-3 months)
   • Long-term goals (6+ months)
   • Priority areas (career, health, relationships, learning, etc.)
   • Success metrics

4. Habits & Routines

   • Morning routine
   • Evening routine
   • Exercise habits
   • Sleep schedule
   • Meal times

5. Preferences & Communication Style

   • Communication preference (detailed vs concise)
   • Reminder style (gentle vs firm)
   • Notification preferences
   • Task organization style (by priority, category, time, etc.)

6. Current Commitments

   • Recurring commitments (weekly meetings, classes, etc.)
   • Regular activities (gym, hobbies, etc.)
   • Family or social obligations

7. Tools & Integration

   • Calendar system used (Google, Outlook, Apple, etc.)
   • Task management preferences
   • Note-taking system

Example Setup Flow:

Hi! I'm your personal assistant. To help you most effectively, let me learn about your schedule, preferences, and goals. This will take just a few minutes.

Let's start with the basics:
1. What's your name, and how would you like me to address you?
2. What timezone are you in?
3. What's your typical work schedule like?

[Continue conversationally through all sections]

Saving the Profile:

After collecting information, save it using Python:

import sys
import json
sys.path.append('[SKILL_DIR]/scripts')
from assistant_db import save_profile

profile = {
    "name": "User's name",
    "preferred_name": "How they like to be addressed",
    "timezone": "America/New_York",
    "location": "New York, USA",
    "work_hours": {
        "start": "09:00",
        "end": "17:00",
        "flexible": True
    },
    "preferences": {
        "communication_style": "concise",
        "reminder_style": "gentle",
        "task_organization": "by_priority"
    },
    "goals": {
        "short_term": ["list", "of", "goals"],
        "long_term": ["list", "of", "goals"]
    },
    "routines": {
        "morning": "Description of morning routine",
        "evening": "Description of evening routine"
    },
    "working_style": "morning person",
    "recurring_commitments": [
        {"title": "Team standup", "frequency": "daily", "time": "10:00"},
        {"title": "Gym", "frequency": "3x per week", "preferred_times": ["18:00", "19:00"]}
    ]
}

save_profile(profile)

Replace [SKILL_DIR] with the actual skill directory path.

Confirmation:

Perfect! I've saved your profile. From now on, I'll provide personalized assistance based on your schedule, preferences, and goals. I'll help you stay organized, track your tasks, and optimize your time.

You can update your profile anytime by asking me to modify your preferences or schedule.

Step 3: Load Profile and Context

For all personal assistance queries, load the user's data:

# Check profile status
python3 scripts/assistant_db.py has_profile

# Get full profile
python3 scripts/assistant_db.py get_profile

# Get current tasks
python3 scripts/assistant_db.py get_tasks

# Get schedule
python3 scripts/assistant_db.py get_schedule

# Get context and notes
python3 scripts/assistant_db.py get_context

# Get quick summary
python3 scripts/assistant_db.py summary

Or use Python imports for more control:

import sys
sys.path.append('[SKILL_DIR]/scripts')
from assistant_db import get_profile, get_tasks, get_schedule, get_context

profile = get_profile()
tasks = get_tasks()
schedule = get_schedule()
context = get_context()

Step 4: Provide Personalized Assistance

Apply the loaded profile and context to provide tailored assistance:

Key Principles:

1. Respect User Preferences

   • Use their preferred communication style
   • Follow their task organization preferences
   • Honor their working hours and routines

2. Leverage Context

   • Reference their goals when suggesting tasks
   • Consider their schedule when proposing activities
   • Adapt to their working style (morning person, etc.)

3. Be Proactive

   • Suggest task prioritization based on goals
   • Remind about recurring commitments
   • Flag scheduling conflicts
   • Propose routine optimizations

4. Maintain Context

   • Track important interactions
   • Remember ongoing projects
   • Note temporary context for continuity

Example Applications:

Scenario 1: Task Management

User: "I need to finish the quarterly report"

Claude: [Loads profile - finds: works 9-5, morning person, prefers focused blocks]

I'll add that to your tasks. Based on your preference for morning work, I recommend
scheduling this during your 9-11am block tomorrow when you're most productive.

The report is due when? I'll set an appropriate priority and reminder.

[Adds task with context-aware details]

Scenario 2: Schedule Conflict

User: "Can I schedule a dentist appointment at 10am Tuesday?"

Claude: [Checks schedule - finds: Team standup at 10am daily]

I notice you have your daily team standup at 10am. Would you like to:
1. Schedule the dentist for 11am instead
2. Move your standup for that day
3. Choose a different day entirely

What works best for you?

Scenario 3: Goal-Aligned Suggestion

User: "What should I focus on this week?"

Claude: [Loads profile - finds short-term goal: "Learn Python"]

Based on your goal to learn Python, I recommend dedicating 3-4 hours this week to:
1. Tuesday 7-8pm: Python tutorial (after gym, before evening routine)
2. Thursday 7-8pm: Practice exercises
3. Saturday 10-12pm: Build a small project

This fits your schedule and keeps you on track for your 3-month learning goal.
Shall I add these to your calendar?

Step 5: Task Management Operations

Use the task management system for organizing user tasks:

Adding Tasks:

import sys
sys.path.append('[SKILL_DIR]/scripts')
from assistant_db import add_task, add_context

task = {
    "title": "Complete quarterly report",
    "description": "Q4 financial analysis",
    "priority": "high",  # high, medium, low
    "category": "work",
    "due_date": "2025-11-15",
    "estimated_time": "3 hours"
}

add_task(task)
add_context("interaction", "Added Q4 report task", "normal")

Quick Task Operations via CLI:

# List all tasks in formatted view
python3 scripts/task_helper.py list

# Add a quick task
python3 scripts/task_helper.py add "Buy groceries" medium "2025-11-08" personal

# Complete a task
python3 scripts/task_helper.py complete <task_id>

# View overdue tasks
python3 scripts/task_helper.py overdue

# View today's tasks
python3 scripts/task_helper.py today

# View this week's tasks
python3 scripts/task_helper.py week

# View tasks by category
python3 scripts/task_helper.py category work

Completing Tasks:

from assistant_db import complete_task

complete_task(task_id)

Updating Tasks:

from assistant_db import update_task

update_task(task_id, {
    "priority": "urgent",
    "due_date": "2025-11-10"
})

Step 6: Schedule and Event Management

Manage calendar events and recurring commitments:

Adding Events:

from assistant_db import add_event

# One-time event
event = {
    "title": "Dentist appointment",
    "date": "2025-11-12",
    "time": "14:00",
    "duration": "1 hour",
    "location": "Downtown Dental",
    "notes": "Bring insurance card"
}

add_event(event, recurring=False)

# Recurring event
recurring_event = {
    "title": "Team standup",
    "frequency": "daily",
    "time": "10:00",
    "duration": "15 minutes",
    "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
}

add_event(recurring_event, recurring=True)

Getting Upcoming Events:

from assistant_db import get_events

# Get events for next 7 days
upcoming = get_events(days_ahead=7)

# Get events for next 30 days
monthly = get_events(days_ahead=30)

Step 7: Context Management and Memory

Maintain context for continuity and personalized assistance:

Adding Context:

from assistant_db import add_context

# Track an interaction
add_context("interaction", "User mentioned struggling with morning productivity", "normal")

# Add an important note (kept indefinitely)
add_context("note", "User prefers written communication over calls for work matters", "high")

# Add temporary context (auto-cleaned after 7 days)
add_context("temporary", "Currently working on project X deadline next week", "normal")

Context Importance Levels:

• "low" - Automatically cleaned up quickly
• "normal" - Standard retention (30 days for interactions, 7 days for temporary)
• "high" - Kept indefinitely (for important notes) or extended retention

Retrieving Context:

from assistant_db import get_context

# Get all context
all_context = get_context()

# Get specific type
interactions = get_context("recent_interactions")
notes = get_context("important_notes")
temp = get_context("temporary_context")

Step 8: Intelligent Data Cleanup

The system automatically manages data retention, but you can trigger manual cleanup:

# Clean up data older than 30 days (default)
python3 scripts/assistant_db.py cleanup

# Clean up with custom retention period
python3 scripts/assistant_db.py cleanup 60

What Gets Cleaned:

• ✓ Completed tasks older than retention period
• ✓ Past one-time events
• ✓ Old interactions (unless marked high importance)
• ✓ Temporary context older than 7 days
• ✗ User profile (never cleaned)
• ✗ Pending tasks (never cleaned)
• ✗ Important notes (never cleaned)
• ✗ Recurring events (never cleaned)

Step 9: Updating User Profile

When users want to update their profile or preferences:

from assistant_db import get_profile, save_profile

# Load current profile
profile = get_profile()

# Update specific fields
profile["work_hours"]["start"] = "08:00"
profile["preferences"]["reminder_style"] = "firm"

# Save updated profile
save_profile(profile)

Or update schedule information:

from assistant_db import get_schedule, save_schedule

schedule = get_schedule()
schedule["working_hours"]["Friday"] = {"start": "09:00", "end": "15:00"}
save_schedule(schedule)

Best Practices

1. Always Load Context First

   • Check profile status before any personalized assistance
   • Load relevant data (profile, tasks, schedule) at the start

2. Be Proactive

   • Suggest task prioritization
   • Flag scheduling conflicts
   • Remind about goals
   • Propose optimizations

3. Respect Preferences

   • Honor communication style preferences
   • Follow task organization preferences
   • Respect working hours and boundaries

4. Maintain Continuity

   • Track important interactions in context
   • Reference previous conversations
   • Remember ongoing projects

5. Keep Data Fresh

   • Periodically run cleanup (suggest monthly)
   • Mark important information appropriately
   • Use temporary context for short-term tracking

6. Provide Value

   • Make connections between tasks and goals
   • Optimize schedules based on working style
   • Offer personalized productivity insights

7. Update Incrementally

   • If user mentions new preferences in conversation, offer to update profile
   • Add new commitments to schedule as they arise
   • Track context changes naturally

Example Interactions

Example 1: First-Time User

User: "Help me organize my week"

Claude: [Checks profile - finds none]

I'd love to help you organize your week! To provide the most personalized assistance,
let me first learn about your schedule and preferences. This will only take a few minutes.

What's your typical work schedule like? For example, do you work 9-5, have flexible
hours, or something else?

[Proceeds through profile setup]

Great! Now let me look at your week and help you organize it effectively...

Example 2: Task Management

User: "I have so many things to do, I'm overwhelmed"

Claude: [Loads tasks - finds 15 pending tasks, 8 with no due date]

I can see you have 15 pending tasks. Let me help you prioritize based on your goals
and schedule.

High Priority (Due Soon):
1. Quarterly report - Due Tuesday (aligns with your career goals)
2. Client presentation - Due Thursday

Medium Priority (This Week):
3. Code review - No deadline but good for Friday afternoon
4. Team feedback - Due next Monday

Let's start with the top 2. Your morning blocks (9-11am) work best for focused work
like the quarterly report. Shall I schedule it for tomorrow morning?

[Helps organize and prioritize based on profile]

Example 3: Schedule Optimization

User: "I want to start exercising regularly"

Claude: [Loads profile - finds: evening person, free 18:00-19:00 most days]

Based on your schedule and preferences, I can see you're typically free between
6-7pm on weekdays. This aligns well with your peak energy time in the evenings.

I recommend:
- Monday, Wednesday, Friday: 18:00-19:00 (gym or home workout)
- Start with 30-minute sessions

This gives you recovery days and doesn't conflict with your Tuesday team dinner
or Thursday book club.

Shall I add these as recurring events to your calendar?

Example 4: Returning User with Context

User: "How's my progress on learning Python?"

Claude: [Loads context - finds: Goal to learn Python, completed 4 tutorial sessions,
last one was 5 days ago]

You're making good progress! You've completed 4 Python tutorial sessions over the
past 3 weeks. However, I notice it's been 5 days since your last session.

To maintain momentum toward your 3-month goal, let's schedule your next session.
Your usual Thursday 7pm slot is open tomorrow. Does that work?

Also, you're at the point where building a small project would be valuable. What
interests you - a web scraper, a to-do app, or something else?

Example 5: Preference Update

User: "I've started a new job, my schedule has changed"

Claude: [Loads current profile]

Congratulations on the new job! Let me update your profile with your new schedule.

What are your new working hours? And have any of your recurring commitments changed?

[Collects updated information and saves]

Perfect! I've updated your profile with your new 8-4 schedule and remote work setup.
I'll adjust all my suggestions accordingly. Your morning productivity block is now
8-10am instead of 9-11am.

Technical Notes

Data Storage Location: All data is stored in ~/.claude/personal_assistant/:

• profile.json - User profile and preferences
• tasks.json - Task list and completed tasks
• schedule.json - Calendar events and recurring commitments
• context.json - Interaction history, notes, and temporary context

Database Commands:

# Profile management
python3 scripts/assistant_db.py has_profile
python3 scripts/assistant_db.py get_profile

# Task management
python3 scripts/assistant_db.py get_tasks

# Schedule management
python3 scripts/assistant_db.py get_schedule

# Context management
python3 scripts/assistant_db.py get_context

# Utilities
python3 scripts/assistant_db.py summary      # Quick overview
python3 scripts/assistant_db.py cleanup [days]  # Clean old data
python3 scripts/assistant_db.py export       # Export all data
python3 scripts/assistant_db.py reset        # Reset everything

Task Helper Commands:

python3 scripts/task_helper.py list
python3 scripts/task_helper.py add <title> [priority] [due_date] [category]
python3 scripts/task_helper.py complete <task_id>
python3 scripts/task_helper.py overdue
python3 scripts/task_helper.py today
python3 scripts/task_helper.py week
python3 scripts/task_helper.py category <name>

Data Retention Policy:

• User profile: Never auto-deleted
• Pending tasks: Never auto-deleted
• Completed tasks: Deleted after 30 days (configurable)
• One-time past events: Deleted after 30 days (configurable)
• Recurring events: Never auto-deleted
• Recent interactions: Deleted after 30 days unless marked "high" importance
• Important notes: Never auto-deleted
• Temporary context: Deleted after 7 days

Profile Data Structure:

{
  "initialized": true,
  "name": "John Doe",
  "preferred_name": "John",
  "timezone": "America/New_York",
  "location": "New York, USA",
  "work_hours": {
    "start": "09:00",
    "end": "17:00",
    "flexible": true
  },
  "preferences": {
    "communication_style": "concise",
    "reminder_style": "gentle",
    "task_organization": "by_priority"
  },
  "goals": {
    "short_term": ["Learn Python", "Run 5K"],
    "long_term": ["Career advancement", "Financial independence"]
  },
  "working_style": "morning person"
}

Resources

scripts/assistant_db.py

Main database management module providing:

• Profile management (get, save, check initialization)
• Task CRUD operations (add, update, complete, delete)
• Schedule and event management
• Context tracking with importance levels
• Intelligent data cleanup
• Data export and summary functions

scripts/task_helper.py

Convenience script for quick task operations:

• Formatted task listings
• Quick task addition
• Task filtering (overdue, today, this week, by category)
• Task completion by ID or title match

Resume Manager

Overview

This skill transforms Claude into a comprehensive resume management system that maintains a structured database of your professional profile and generates tailored, professionally styled PDF resumes for specific job applications. The skill intelligently selects and highlights the most relevant experiences, projects, and skills based on the target role.

When to Use This Skill

Invoke this skill for resume-related tasks:

• Creating tailored resumes for job applications
• Updating professional experiences and projects
• Managing skills and certifications
• Tracking career progression
• Generating role-specific resumes
• Maintaining a comprehensive career portfolio
• Optimizing resume content for ATS systems

Workflow

Step 1: Check for Existing Data

Before any resume operations, check if the database is initialized:

python3 scripts/resume_db.py is_initialized

If output is "false", proceed to Step 2 (Initial Setup). If "true", proceed to Step 3 (Resume Operations).

Step 2: Initial Setup - Extract from Existing Resume

When no data exists, ask the user to provide their existing resume.

Prompt the User:

To help you create tailored resumes, I need to build a database of your professional
profile. Please provide your existing resume in one of these ways:

1. Upload your resume file (PDF, DOCX, or TXT)
2. Paste the content of your resume
3. Provide a link to your online resume/LinkedIn profile

I'll extract all the information and organize it in a structured database that I can
use to generate customized resumes for different job applications.

Extracting Data from Resume:

Once the user provides their resume, extract the following information:

1. Personal Information:

• Full name
• Email address
• Phone number
• Location (city, state/country)
• LinkedIn profile URL
• GitHub profile URL
• Personal website
• Professional summary/objective

2. Work Experience: For each role, extract:

• Position/Job title
• Company name
• Location
• Start date (format: "Mon YYYY" like "Jan 2022")
• End date (or "Present")
• Brief description
• Key highlights/achievements (bullet points)
• Technologies/tools used

3. Projects: For each project, extract:

• Project name
• Date or time period
• Description
• Key highlights/achievements
• Technologies used
• Link (if available)

4. Education: For each degree, extract:

• Degree name (e.g., "Bachelor of Science in Computer Science")
• School/University name
• Location
• Graduation date
• GPA (if mentioned)
• Honors (if any)
• Relevant coursework

5. Skills: Extract and categorize skills:

• Programming Languages
• Frameworks & Libraries
• Tools & Technologies
• Practices & Methodologies
• Soft skills

6. Additional Sections:

• Certifications (name, issuer, date)
• Awards & Honors
• Publications
• Volunteer work
• Languages spoken

Saving the Extracted Data:

After extraction, save to the database using Python:

import sys
import json
sys.path.append('[SKILL_DIR]/scripts')
from resume_db import initialize_from_data

resume_data = {
    "personal_info": {
        "name": "Full Name",
        "email": "email@example.com",
        "phone": "+1 (555) 123-4567",
        "location": "City, State",
        "linkedin": "linkedin.com/in/username",
        "github": "github.com/username",
        "website": "website.com",
        "summary": "Professional summary..."
    },
    "experiences": [
        {
            "position": "Senior Software Engineer",
            "company": "Company Name",
            "location": "City, State",
            "start_date": "Jan 2022",
            "end_date": "Present",
            "description": "Brief description",
            "highlights": [
                "Achievement 1 with quantifiable results",
                "Achievement 2 with impact metrics",
                "Achievement 3 with technologies used"
            ],
            "technologies": ["Python", "AWS", "Docker"]
        }
    ],
    "projects": [
        {
            "name": "Project Name",
            "date": "2023",
            "description": "Project description",
            "highlights": [
                "Key achievement or feature",
                "Impact or result"
            ],
            "technologies": ["React", "Node.js", "PostgreSQL"],
            "link": "github.com/username/project"
        }
    ],
    "education": [
        {
            "degree": "Bachelor of Science in Computer Science",
            "school": "University Name",
            "location": "City, State",
            "graduation_date": "May 2019",
            "gpa": "3.8/4.0",
            "honors": "Magna Cum Laude",
            "relevant_coursework": ["Data Structures", "Algorithms", "Machine Learning"]
        }
    ],
    "skills": {
        "Languages": ["Python", "JavaScript", "Java"],
        "Frameworks": ["React", "Django", "Spring"],
        "Tools": ["Docker", "AWS", "Git"],
        "Practices": ["Agile", "CI/CD", "TDD"]
    },
    "certifications": [
        {
            "name": "AWS Certified Solutions Architect",
            "issuer": "Amazon Web Services",
            "date": "2023"
        }
    ],
    "awards": [],
    "publications": [],
    "volunteer": [],
    "languages": ["English (Native)", "Spanish (Fluent)"],
    "interests": []
}

initialize_from_data(resume_data)

Replace [SKILL_DIR] with the actual skill directory path.

Confirmation:

Perfect! I've extracted and saved your professional profile:

• Personal Information: ✓
• Work Experience: X positions
• Projects: X projects
• Education: X degrees
• Skills: X categories
• Certifications: X certifications

Your resume database is now ready. I can generate customized resumes for any job
you're applying to. Just tell me the job title or description, and I'll create a
tailored one-page PDF highlighting your most relevant experience and skills.

Step 3: Generate Tailored Resume for Job Application

When a user requests a resume for a specific role:

Step 3.1: Understand the Target Role

Ask the user about the role:

To create the perfect resume for this position, I need to understand the role better.

1. What's the job title?
2. Can you share the job description or key requirements?
3. What are the must-have skills or technologies mentioned?

Step 3.2: Extract Keywords and Requirements

From the job description, identify:

• Required technical skills
• Preferred technologies
• Key responsibilities
• Important keywords for ATS
• Industry-specific terms
• Experience level indicators

Step 3.3: Generate Tailored Resume

Use the PDF generator to create a customized resume:

import sys
sys.path.append('[SKILL_DIR]/scripts')
from pdf_generator import generate_resume

# Keywords from job description
job_keywords = [
    "python", "aws", "kubernetes", "microservices",
    "agile", "rest api", "postgresql", "docker"
]

job_title = "Senior Backend Engineer"

# Output path
output_path = f"~/Downloads/{job_title.replace(' ', '_')}_Resume.pdf"

# Generate resume
generate_resume(
    output_path=output_path,
    job_title=job_title,
    job_keywords=job_keywords
)

The generator will:

• Filter experiences relevant to the keywords
• Select projects that match the role
• Highlight applicable skills
• Keep it to one page
• Use professional styling
• Optimize for ATS parsing

Step 3.4: Review and Iterate

After generating:

1. Inform the user where the PDF was saved
2. Offer to make adjustments
3. Suggest additional highlights if space allows
4. Recommend customizations for specific requirements

Step 4: Update Resume Database

When users want to add or update information:

Adding New Experience:

from resume_db import add_experience

new_exp = {
    "position": "Lead Software Engineer",
    "company": "New Company",
    "location": "Remote",
    "start_date": "Mar 2024",
    "end_date": "Present",
    "description": "Leading backend infrastructure team",
    "highlights": [
        "Scaled services to handle 50M+ daily requests",
        "Reduced infrastructure costs by 30% through optimization",
        "Built CI/CD pipeline improving deployment speed by 10x"
    ],
    "technologies": ["Go", "Kubernetes", "PostgreSQL", "AWS"]
}

add_experience(new_exp)

Adding New Project:

from resume_db import add_project

new_project = {
    "name": "Real-time Analytics Dashboard",
    "date": "2024",
    "description": "Built real-time analytics platform processing 1M+ events/minute",
    "highlights": [
        "Implemented using streaming architecture with Kafka and Redis",
        "Created interactive visualizations with React and D3.js",
        "Achieved sub-second query latency on complex aggregations"
    ],
    "technologies": ["React", "Kafka", "Redis", "Python", "TimescaleDB"],
    "link": "github.com/username/analytics-dashboard"
}

add_project(new_project)

Updating Skills:

from resume_db import add_skill, update_skills

# Add individual skill
add_skill("Languages", "Rust")
add_skill("Tools", "Terraform")

# Or update entire skills dictionary
skills = {
    "Languages": ["Python", "Go", "JavaScript", "Rust", "SQL"],
    "Frameworks": ["Django", "FastAPI", "React", "Next.js"],
    "Cloud & DevOps": ["AWS", "Kubernetes", "Docker", "Terraform", "CI/CD"],
    "Databases": ["PostgreSQL", "MongoDB", "Redis", "Elasticsearch"],
    "Practices": ["Microservices", "TDD", "Agile", "System Design"]
}

update_skills(skills)

Adding Certification:

from resume_db import add_certification

cert = {
    "name": "Google Cloud Professional Architect",
    "issuer": "Google Cloud",
    "date": "2024",
    "credential_id": "ABC123",
    "link": "credentials.google.com/..."
}

add_certification(cert)

Step 5: View and Manage Resume Data

View Summary:

python3 scripts/resume_db.py summary

View Specific Sections:

# Personal info
python3 scripts/resume_db.py get_personal_info

# All experiences
python3 scripts/resume_db.py get_experiences

# All projects
python3 scripts/resume_db.py get_projects

# Education
python3 scripts/resume_db.py get_education

# Skills
python3 scripts/resume_db.py get_skills

Search Across All Data:

python3 scripts/resume_db.py search "machine learning"

Export All Data:

python3 scripts/resume_db.py export > resume_backup.json

Step 6: Resume Optimization Tips

When generating resumes, provide these optimization tips:

Content Optimization:

• Use action verbs (Led, Built, Architected, Improved, Reduced)
• Include quantifiable metrics (X% improvement, Y users, Z revenue)
• Tailor highlights to match job requirements
• Keep bullet points concise (1-2 lines max)
• Focus on impact, not just responsibilities

ATS Optimization:

• Use standard section headers (Experience, Education, Skills)
• Include keywords from job description naturally
• Avoid tables, columns, headers/footers
• Use standard fonts (which the PDF generator does)
• Spell out acronyms once: "Application Programming Interface (API)"

One-Page Strategy:

• Prioritize recent and relevant experience (last 5-7 years)
• Include 3-4 bullet points per role
• Limit to 2-3 projects maximum
• Condense older or less relevant experience
• Remove outdated technologies unless specifically required

Best Practices

1. Keep Data Current

   • Update experiences as projects complete
   • Add new skills as you learn them
   • Maintain quantifiable achievements
   • Record certifications immediately

2. Write Effective Bullet Points

   • Start with action verbs
   • Include metrics and outcomes
   • Show progression and impact
   • Use the STAR method (Situation, Task, Action, Result)

3. Organize Skills Strategically

   • Group by category for clarity
   • Put most relevant skills first
   • Remove outdated technologies
   • Be honest about proficiency levels

4. Tailor Every Resume

   • Match keywords to job description
   • Emphasize relevant experience
   • Reorder bullet points by relevance
   • Adjust technical skills section

5. Maintain Professional Tone

   • Use third-person implied (no "I")
   • Keep language concise and clear
   • Avoid jargon unless industry-standard
   • Proofread for errors

Example Interactions

Example 1: Initial Setup

User: "Help me create a resume for job applications"

Claude: [Checks database - finds not initialized]

To help you create tailored resumes, I need to build a database of your professional
profile. Please provide your existing resume in one of these ways:

1. Upload your resume file (PDF, DOCX, or TXT)
2. Paste the content of your resume
3. Provide a link to your online resume/LinkedIn profile

[User provides resume]

Claude: [Extracts data and initializes database]

Perfect! I've extracted and saved your professional profile:
• Personal Information: ✓
• Work Experience: 3 positions
• Projects: 2 projects
• Education: 1 degree
• Skills: 4 categories
• Certifications: 2 certifications

Your resume database is ready! Tell me about a job you're applying to and I'll
generate a customized one-page PDF resume.

Example 2: Generate Resume for Specific Role

User: "I need a resume for a Senior Backend Engineer position at a fintech startup"

Claude: [Database initialized]

Great! To create the perfect resume for this Senior Backend Engineer role, can you
share the job description or tell me about the key requirements?

User: [Shares job description mentioning Python, AWS, microservices, PostgreSQL, etc.]

Claude: [Extracts keywords: python, aws, microservices, postgresql, fintech, api]

[Generates PDF using relevant experiences and projects]

I've created your tailored resume: ~/Downloads/Senior_Backend_Engineer_Resume.pdf

The resume highlights:
✓ Your 5 years of backend experience with Python and microservices
✓ AWS and Kubernetes expertise from your current role
✓ PostgreSQL and database optimization achievements
✓ Your fintech-relevant project on payment processing
✓ All technical skills matching the job requirements

The resume is optimized for ATS systems and kept to exactly one page. Would you
like me to adjust anything?

Example 3: Update Experience

User: "I just completed a major project - built a real-time analytics system processing 1M events per minute using Kafka"

Claude: [Loads resume data]

Excellent achievement! Let me add this to your profile. A few questions:

1. Should I add this as a new bullet point to your current role, or as a separate project?
2. What technologies did you use besides Kafka?
3. What was the business impact or outcome?

User: "Add it to my current role. Used Kafka, Redis, Python, and TimescaleDB. Reduced report generation time from hours to seconds."

Claude: [Updates experience]

✓ Updated your current role with this achievement:

"Built real-time analytics system processing 1M+ events/minute using Kafka, Redis, and TimescaleDB, reducing report generation time from hours to seconds"

This will now appear in future resumes, especially for roles requiring streaming
data, Kafka, or analytics experience.

Example 4: Multiple Resume Versions

User: "I'm applying to both backend and full-stack positions. Can you create resumes for both?"

Claude: Sure! Let's create two targeted versions.

[Generates backend-focused resume emphasizing API development, microservices, databases]
✓ Backend Engineer Resume: Emphasizes your Python/Go backend work, API design, and infrastructure scaling

[Generates full-stack resume including both backend and frontend projects]
✓ Full-Stack Engineer Resume: Balances your backend expertise with React projects and full-stack achievements

Both resumes are one page and optimized for their respective roles. The main
differences are:
- Backend version: More emphasis on system design, performance, and infrastructure
- Full-stack version: Includes your React projects and mentions end-to-end ownership

Which one would you like to review first?

Example 5: Resume Review and Optimization

User: "Can you review my resume data and suggest improvements?"

Claude: [Analyzes resume database]

I've reviewed your profile. Here are my recommendations:

**Strengths:**
✓ Good mix of quantifiable achievements
✓ Recent experience with in-demand technologies
✓ Clear progression in roles and responsibilities

**Areas for Improvement:**

1. **Add Metrics** to these bullet points:
   - "Improved API performance" → Add percentage improvement
   - "Led team of engineers" → Specify team size and outcomes

2. **Update Skills** section:
   - Remove outdated: jQuery, Bower (unless specifically needed)
   - Add trending: TypeScript, Next.js (if you've used them)

3. **Expand Recent Project**:
   - Your latest project mentions "built authentication system"
   - Add: number of users, security standards followed, or technologies used

4. **Certifications**:
   - Your AWS cert expires soon - plan to renew
   - Consider adding Kubernetes cert you mentioned pursuing

Would you like me to help update any of these areas?

Technical Notes

Data Storage:

• Location: ~/.claude/resume_data.json
• Format: Structured JSON
• Backup: Use python3 scripts/resume_db.py export

PDF Generation:

• Library: reportlab (requires: pip install reportlab)
• Page size: US Letter (8.5" x 11")
• Margins: 0.75 inches all sides
• Font: Helvetica family
• Optimized for: One-page resumes, ATS compatibility

Resume Styling:

• Professional color scheme (blues and grays)
• Clear section headers with underlines
• Consistent spacing and formatting
• Bullet points for achievements
• Contact info in header
• Technical skills as comma-separated lists

Database Commands:

# Check initialization
python3 scripts/resume_db.py is_initialized

# View data
python3 scripts/resume_db.py summary
python3 scripts/resume_db.py get_experiences
python3 scripts/resume_db.py get_projects
python3 scripts/resume_db.py get_education
python3 scripts/resume_db.py get_skills

# Search
python3 scripts/resume_db.py search "keyword"

# Export/Backup
python3 scripts/resume_db.py export > backup.json

# Reset (caution!)
python3 scripts/resume_db.py reset

PDF Generation Commands:

# Generate general resume
python3 scripts/pdf_generator.py output.pdf

# Generate with job title
python3 scripts/pdf_generator.py output.pdf --title "Senior Software Engineer"

# Generate with keyword filtering
python3 scripts/pdf_generator.py output.pdf --keywords python aws kubernetes docker

Data Structure Example:

{
  "initialized": true,
  "personal_info": {
    "name": "Your Name",
    "email": "email@example.com",
    "phone": "+1 (555) 123-4567",
    "location": "City, State",
    "linkedin": "linkedin.com/in/username",
    "github": "github.com/username",
    "summary": "Professional summary"
  },
  "experiences": [
    {
      "id": 1234567890.123,
      "position": "Senior Engineer",
      "company": "Company Name",
      "location": "City, State",
      "start_date": "Jan 2022",
      "end_date": "Present",
      "highlights": ["Achievement 1", "Achievement 2"],
      "technologies": ["Python", "AWS"]
    }
  ],
  "skills": {
    "Languages": ["Python", "JavaScript"],
    "Frameworks": ["Django", "React"]
  }
}

Resources

scripts/resume_db.py

Complete database management system providing:

• Data initialization and persistence
• CRUD operations for all resume sections
• Relevance-based filtering for experiences/projects
• Keyword-based skill matching
• Search functionality across all data
• Data export and backup
• CLI interface for all operations