Imported from JiayiV/question_mixing (skills/public-03-claude-skills-main-documentation-implementation-skills-refactoring-plan-613c6d86/SKILL.md). Install upstream with npx skills add JiayiV/question_mixing --skill public-03-claude-skills-main-documentation-implementation-skills-refactoring-plan-613c6d86. Copyright stays with the author.

Claude Skills Systematic Refactoring Plan

Goal: Optimize all 36 skills to follow Anthropic's official best practices while maintaining comprehensive domain expertise.

Approach: Phased refinement with metadata enhancement integrated throughout.

Timeline: 4 weeks (progressive implementation)

Expected Outcome: Better Claude activation, faster loading, clearer skill discovery, professional metadata.

📊 Executive Summary

Current State Analysis

Strengths:

✅ 36 production-ready skills with comprehensive domain expertise
✅ 97 Python automation tools
✅ Excellent reference materials and frameworks
✅ Real-world benchmarks and best practices

Optimization Opportunities:

⚠️ SKILL.md files too long (200-1,000 lines vs. recommended 50-200)
⚠️ Missing metadata (license, version, category)
⚠️ No keywords sections for better discovery
⚠️ Not using allowed-tools for security/safety
⚠️ Some skills too broad (covering multiple capabilities)

Expected Improvements

After Refactoring:

✅ Faster skill loading (50-70% reduction in SKILL.md size)
✅ Better Claude activation (clearer triggers)
✅ Professional metadata (license, versioning, categorization)
✅ Enhanced discovery (keywords sections)
✅ Safer execution (allowed-tools restrictions)
✅ Maintained expertise (moved to references/, not deleted)

ROI:

Implementation time: ~40 hours
Benefit: Permanent improvement to all 36 skills
User impact: Better Claude performance, clearer documentation

🎯 Refactoring Principles

Following Anthropic's Official Pattern

Focused Scope - One skill = one clear capability (not entire domains)
Lean SKILL.md - 50-200 lines (core instructions only)
Progressive Disclosure - Metadata → SKILL.md → References → Scripts
Rich Descriptions - What + When + Triggers + Keywords
Proper Metadata - License, version, category tracking
Tool Restrictions - Use allowed-tools for safety when appropriate
Keywords Section - Help users discover skills

What NOT to Change

✅ Keep all Python scripts (they're excellent)
✅ Keep all reference materials (move to references/)
✅ Keep all frameworks and benchmarks
✅ Keep domain expertise (just reorganize)
✅ Keep current folder structure (already good)

Optimization Strategy

Move FROM SKILL.md:

Detailed frameworks (reference in 1-2 sentences, full content in references/)
Extensive examples (keep 1-2, move rest to references/examples.md)
Long procedural guides (summarize, detail in references/)
Comprehensive checklists (link to references/)

Keep IN SKILL.md:

Quick start guide (3-5 examples)
Core workflow overview (high-level steps)
When to use each script/reference (pointers)
Essential decision points
Keywords for discovery

Phase 1: Foundation Enhancement (Week 1)

Goal: Add professional metadata and discovery aids to all 36 skills

Time: ~20 hours (30 min per skill × 36 skills + 2 hours documentation)

Task 1.1: Create Metadata Template

File: .claude/skills-metadata-template.yaml

---
name: skill-name
description: [What it does in 1 sentence]. [Key capabilities in 1 sentence]. Use when [primary trigger], [secondary trigger], or when user mentions [keyword 1], [keyword 2], [keyword 3].
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: marketing | c-level | product | engineering | regulatory
  domain: content | demand-gen | product-marketing | ceo-advisory | etc
  updated: 2025-10-20
  python-tools: script1.py, script2.py, script3.py
  tech-stack: HubSpot, GA4, React, etc (if applicable)
---

Task 1.2: Update All Marketing Skills (3 skills, 1.5 hours)

For each skill:

content-creator

Current:

---
name: content-creator
description: Comprehensive content marketing skill for creating blog posts, social media content, and SEO-optimized materials. Includes brand voice development, content templates, SEO analysis tools, and social media optimization strategies. Use when creating any marketing content, developing brand guidelines, optimizing for SEO, or planning content calendars.
---

Enhanced:

---
name: content-creator
description: Create SEO-optimized marketing content with consistent brand voice. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creating social media content, analyzing brand voice, optimizing SEO, planning content calendars, or when user mentions content creation, brand voice, SEO optimization, social media marketing, or content strategy.
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: marketing
  domain: content-marketing
  updated: 2025-10-20
  python-tools: brand_voice_analyzer.py, seo_optimizer.py
  tech-stack: SEO, social-media-platforms
---

# Content Creator

...existing content with added keywords section...

## Keywords
content creation, blog posts, SEO, brand voice, social media, content calendar, marketing content, content strategy, content marketing, brand consistency, content optimization, social media marketing, content planning

marketing-demand-acquisition

Enhanced:

---
name: marketing-demand-acquisition
description: Multi-channel demand generation, paid media optimization, SEO strategy, and partnership programs for Series A+ startups. Includes CAC calculator, channel playbooks, HubSpot integration, and international expansion tactics. Use when planning demand generation campaigns, optimizing paid media, building SEO strategies, establishing partnerships, or when user mentions demand gen, paid ads, LinkedIn ads, Google ads, CAC, acquisition, lead generation, or pipeline generation.
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: marketing
  domain: demand-generation
  updated: 2025-10-20
  python-tools: calculate_cac.py
  tech-stack: HubSpot, LinkedIn-Ads, Google-Ads, Meta-Ads, SEO-tools
  target-market: B2B-SaaS, Series-A+
---

## Keywords
demand generation, paid media, paid ads, LinkedIn ads, Google ads, Meta ads, CAC, customer acquisition cost, lead generation, MQL, SQL, pipeline generation, acquisition strategy, performance marketing, paid social, paid search, partnerships, affiliate marketing, SEO strategy

marketing-strategy-pmm

Enhanced:

---
name: marketing-strategy-pmm
description: Product marketing, positioning, GTM strategy, and competitive intelligence. Includes ICP definition, April Dunford positioning methodology, launch playbooks, competitive battlecards, and international market entry guides. Use when developing positioning, planning product launches, creating messaging, analyzing competitors, entering new markets, enabling sales, or when user mentions product marketing, positioning, GTM, go-to-market, competitive analysis, market entry, or sales enablement.
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: marketing
  domain: product-marketing
  updated: 2025-10-20
  frameworks: April-Dunford, ICP-definition, messaging-hierarchy
  target-market: B2B-SaaS, international-expansion
---

## Keywords
product marketing, positioning, GTM, go-to-market strategy, competitive analysis, competitive intelligence, battlecards, ICP, ideal customer profile, messaging, value proposition, product launch, market entry, international expansion, sales enablement, win loss analysis

Task 1.3: Update All C-Level Skills (2 skills, 1 hour)

ceo-advisor

---
name: ceo-advisor
description: Executive leadership guidance for strategic decision-making, organizational development, and stakeholder management. Includes strategy analyzer, financial scenario modeling, board governance, and investor relations frameworks. Use when planning strategy, modeling financial scenarios, preparing board presentations, managing investors, developing culture, or when user mentions strategic planning, board meetings, investor updates, organizational culture, or executive decisions.
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: c-level
  domain: ceo-leadership
  updated: 2025-10-20
  python-tools: strategy_analyzer.py, financial_scenario_analyzer.py
---

## Keywords
CEO, executive leadership, strategic planning, board governance, investor relations, financial modeling, organizational culture, stakeholder management, executive decisions, board presentations, strategic initiatives

cto-advisor

---
name: cto-advisor
description: Technical leadership guidance for engineering teams, architecture decisions, and technology strategy. Includes tech debt analyzer, team scaling calculator, engineering metrics, technology evaluation, and ADR templates. Use when assessing technical debt, scaling engineering teams, evaluating technologies, making architecture decisions, or when user mentions tech debt, engineering metrics, team scaling, technology selection, or architecture decisions.
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: c-level
  domain: cto-leadership
  updated: 2025-10-20
  python-tools: tech_debt_analyzer.py, team_scaling_calculator.py
  frameworks: DORA-metrics, architecture-decision-records
---

## Keywords
CTO, technical leadership, tech debt, technical debt, engineering team, team scaling, architecture decisions, technology evaluation, engineering metrics, DORA metrics, ADR, architecture decision records, technology strategy

Task 1.4: Update All Product Team Skills (5 skills, 2.5 hours)

Standard metadata template for product skills:

license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: product
  domain: [product-management|agile-delivery|product-strategy|ux-research|ui-design]
  updated: 2025-10-20
  python-tools: [specific tools]

Keywords sections to add:

product-manager-toolkit: product management, RICE, prioritization, feature prioritization, customer interviews, PRD, product requirements, product discovery, user research, product metrics
agile-product-owner: agile, product owner, user stories, sprint planning, backlog, velocity, acceptance criteria, sprint execution, scrum, agile ceremonies
product-strategist: product strategy, OKR, objectives and key results, product vision, roadmap, strategic planning, product positioning, team organization
ux-researcher-designer: UX research, user research, personas, journey mapping, usability testing, design thinking, user interviews, research synthesis
ui-design-system: UI design, design system, design tokens, component library, design consistency, visual design, responsive design, design handoff

Task 1.5: Update All Engineering Skills (14 skills, 7 hours)

Add to all engineering core skills:

license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: engineering
  domain: [architecture|frontend|backend|fullstack|qa|devops|secops|review|security]
  updated: 2025-10-20
  python-tools: [specific tools]
  tech-stack: React, Next.js, Node.js, PostgreSQL, etc

Add allowed-tools where appropriate:

senior-architect: allowed-tools: Read, Grep, Glob, Bash (analysis-heavy)
code-reviewer: allowed-tools: Read, Grep, Glob (read-only review)
senior-qa: allowed-tools: Read, Bash (testing execution)

AI/ML/Data skills metadata:

category: engineering
domain: [data-science|data-engineering|ml-ops|prompt-engineering|computer-vision]
tech-stack: PyTorch, TensorFlow, Spark, Airflow, etc

Task 1.6: Update All RA/QM Skills (12 skills, 6 hours)

Add to all RA/QM skills:

license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: regulatory-quality
  domain: [regulatory|quality-management|risk|security|audit|compliance]
  updated: 2025-10-20
  python-tools: [specific tools]
  compliance-frameworks: [ISO-13485|ISO-14971|ISO-27001|EU-MDR|FDA-QSR|GDPR]
  industry: HealthTech, MedTech
---

Add allowed-tools for audit skills:

qms-audit-expert: allowed-tools: Read, Grep, Glob (read-only audit)
isms-audit-expert: allowed-tools: Read, Grep, Glob (read-only audit)

Phase 2: Pilot Optimization (Week 2)

Goal: Refine 3 representative skills as proof of concept

Time: ~12 hours (4 hours per skill)

Selected Pilot Skills:

content-creator (Marketing) - 236 lines → target 120 lines
product-manager-toolkit (Product) - 352 lines → target 150 lines
senior-fullstack (Engineering) - Estimate ~300 lines → target 150 lines

Task 2.1: Refactor content-creator Skill

Current Issues:

236 lines (good but can be better)
Contains full brand voice framework details
Extensive social media platform guidance
Many detailed examples

Refactoring Steps:

Step 1: Enhanced Frontmatter (Already done in Phase 1)

Step 2: Add Keywords Section

# Content Creator

Professional-grade brand voice analysis, SEO optimization, and platform-specific content frameworks.

## Keywords
content creation, blog posts, SEO, brand voice, social media, content calendar, marketing content, content strategy, content marketing, brand consistency, content optimization, social media marketing, content planning, blog writing, content frameworks, brand guidelines, social media strategy

Step 3: Slim Down SKILL.md

Current Structure (236 lines):

Quick Start: 15 lines
Core Workflows: 120 lines (4 workflows with details)
Key Scripts: 40 lines
Reference Documents: 25 lines
Best Practices: 36 lines

Refined Structure (120 lines):

Quick Start: 15 lines (keep as-is)
Core Workflows: 40 lines (overview only, point to references)
Key Scripts: 20 lines (essentials only)
Reference Documents: 15 lines (clear pointers)
Best Practices: 15 lines (top 5 only)
Keywords: 5 lines
Examples: 10 lines (2 concrete examples)

Moved to References:

Create new reference files:

references/brand-voice-detailed-framework.md - Move detailed archetype descriptions
references/social-media-platform-deep-dive.md - Move platform-specific details
references/content-creation-examples.md - Move extensive examples

Updated SKILL.md Content:

### Establishing Brand Voice

1. **Analyze Existing Content**
   ```bash
   python scripts/brand_voice_analyzer.py existing_content.txt

Define Voice Attributes
- Review personality archetypes in references/brand-voice-detailed-framework.md
- Select primary and secondary archetypes
- Document chosen voice
Create Consistent Content
- Apply voice across all content
- Verify consistency with analyzer

For complete brand voice framework including all 5 archetypes, tone dimensions, and implementation guide, see references/brand-voice-detailed-framework.md.


#### Step 4: Create New Reference Files

**references/brand-voice-detailed-framework.md** (New file, ~150 lines)
- Move all archetype details here
- Full tone attribute framework
- Extensive voice samples
- Implementation checklists

**references/social-media-platform-deep-dive.md** (New file, ~200 lines)
- Move all platform-specific details
- Posting time recommendations
- Character limits and formats
- Algorithm optimization tactics

**references/content-creation-examples.md** (New file, ~100 lines)
- 10+ complete content examples
- Before/after SEO optimization
- Various content types

---

### Task 2.2: Refactor product-manager-toolkit Skill

**Current Issues:**
- 352 lines (too long)
- Covers RICE + Interviews + PRDs + Discovery + Metrics
- Multiple distinct workflows

**Refactoring Steps:**

#### Step 1: Enhanced Frontmatter (Already done in Phase 1)

#### Step 2: Add Keywords
```markdown
## Keywords
product management, RICE prioritization, feature prioritization, customer interviews, user research, PRD, product requirements document, product discovery, customer discovery, product metrics, north star metric, product strategy, backlog prioritization, roadmap planning

Step 3: Slim Down SKILL.md

Current: 352 lines → Target: 150 lines

Keep in SKILL.md:

Quick start (3 commands)
High-level workflow overview
Script usage basics
Pointers to references

Move to References:

Detailed RICE methodology → references/rice-prioritization-guide.md
Interview frameworks → references/customer-discovery-methods.md
Full PRD templates → Already in references/ ✅
Extensive metrics frameworks → references/product-metrics-frameworks.md

Refined Structure:

# Product Manager Toolkit

## Keywords
[as above]

## Quick Start

Three core capabilities, pick yours:

### Feature Prioritization
```bash
python scripts/rice_prioritizer.py features.csv --capacity 20

Interview Analysis

python scripts/customer_interview_analyzer.py transcript.txt

PRD Creation

Use templates from references/prd_templates.md

Core Workflows

1. Feature Prioritization

Score features with RICE framework:

Gather feature requests
Score with RICE (Reach × Impact × Confidence / Effort)
Generate roadmap

For complete RICE methodology, see references/rice-prioritization-guide.md.

2. Customer Discovery

Extract insights from interviews:

Conduct interviews
Analyze with customer_interview_analyzer.py
Synthesize findings

For interview frameworks and methodologies, see references/customer-discovery-methods.md.

3. PRD Development

Document requirements:

Choose template from references/prd_templates.md
Fill sections based on discovery
Collaborate with stakeholders

Scripts

rice_prioritizer.py

Calculate RICE scores and generate roadmaps.

Usage: python scripts/rice_prioritizer.py features.csv --capacity 20
Output: Prioritized list, portfolio analysis, roadmap

customer_interview_analyzer.py

Extract insights from interview transcripts.

Usage: python scripts/customer_interview_analyzer.py transcript.txt
Output: Pain points, feature requests, themes, sentiment

References

rice-prioritization-guide.md - Complete RICE methodology
customer-discovery-methods.md - Interview frameworks, synthesis
prd_templates.md - 4 PRD formats with examples
product-metrics-frameworks.md - North Star, funnel analysis, feature metrics

Best Practices

Start with customer problems, not solutions
Use RICE for objective prioritization
Keep PRDs focused on "why" not "how"
Measure everything: adoption, frequency, retention

Examples

Example 1: Quarterly Planning

User: "Help me prioritize our backlog for Q1"

Export features to CSV
Run rice_prioritizer.py with team capacity
Review portfolio balance (quick wins vs big bets)

Example 2: Interview Synthesis

User: "Analyze these 5 customer interviews"

Run analyzer on each transcript
Identify common themes across interviews
Map to opportunity areas


**Result:** 150 lines (58% reduction from 352)

---

### Task 2.3: Refactor senior-fullstack Skill

**Refactoring Steps:**

#### Step 1: Enhanced Frontmatter

```yaml
---
name: senior-fullstack
description: End-to-end application development with Next.js, GraphQL, PostgreSQL stack. Includes project scaffolder, code quality analyzer, architecture patterns, and complete development workflows. Use when building fullstack applications, scaffolding new projects, analyzing code quality, implementing architecture patterns, or when user mentions fullstack development, Next.js projects, code quality analysis, or project setup.
license: MIT
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
metadata:
  version: 1.0.0
  author: borghei
  category: engineering
  domain: fullstack-development
  updated: 2025-10-20
  python-tools: fullstack_scaffolder.py, project_scaffolder.py, code_quality_analyzer.py
  tech-stack: Next.js, React, GraphQL, PostgreSQL, Node.js, TypeScript, Docker
---

Step 2: Add Keywords

## Keywords
fullstack development, fullstack engineer, Next.js, React, GraphQL, PostgreSQL, project scaffolding, code quality analysis, architecture patterns, TypeScript, Node.js, fullstack project, end-to-end development, project setup, code analysis, quality metrics

Step 3: Slim Down SKILL.md

Estimated Current: ~300 lines → Target: 150 lines

Keep:

Quick start (3 script examples)
High-level capabilities overview
Script descriptions
Essential workflows

Move:

Detailed architecture patterns → references/
Extensive tech stack guide → references/
Long development workflow details → references/

Phase 3: Full Rollout (Week 3)

Goal: Apply refinements to remaining 33 skills

Time: ~20 hours

Task 3.1: Product Team Skills (4 remaining, 8 hours)

Apply same pattern to:

agile-product-owner
product-strategist
ux-researcher-designer
ui-design-system

For each:

✅ Metadata already added (Phase 1)
Add keywords section
Reduce SKILL.md to <200 lines
Move details to references/

Task 3.2: Engineering Core Skills (8 remaining, 6 hours)

Skills:

senior-architect
senior-frontend
senior-backend
senior-qa
senior-devops
senior-secops
code-reviewer
senior-security

For each:

✅ Metadata already added (Phase 1)
Add appropriate allowed-tools
Add keywords section
Reduce to <200 lines
Move patterns to references/

Task 3.3: Engineering AI/ML/Data Skills (5 skills, 4 hours)

Skills:

senior-data-scientist
senior-data-engineer
senior-ml-engineer
senior-prompt-engineer
senior-computer-vision

For each:

✅ Metadata already added (Phase 1)
Add keywords section
Optimize SKILL.md length
Add ML/AI specific frameworks to metadata

Task 3.4: RA/QM Skills (12 skills, 2 hours)

Note: These skills likely already follow good patterns

For each:

✅ Metadata already added (Phase 1)
Add keywords section
Add compliance frameworks to metadata
Add allowed-tools for audit skills

Phase 4: Validation & Documentation (Week 4)

Goal: Test, validate, and document the refined skills

Time: ~8 hours

Task 4.1: Testing Protocol (4 hours)

Test Each Skill:

Activation Test
- Ask question that should trigger skill
- Verify Claude uses the skill
- Check skill loads correctly
Script Test
- Run each Python script with --help
- Verify scripts still work
- Check paths are correct
Reference Test
- Verify all reference links work
- Check references/ files load correctly
- Ensure no broken links

Test Matrix Template:

Skill Name	Activation Test	Scripts Test	References Test	Issues
content-creator	✅ Pass	✅ Pass	✅ Pass	None
...

Task 4.2: Update Documentation (2 hours)

Update These Files:

README.md:

Add note about skill structure following Anthropic best practices
Update any references to skill lengths
Add "Skills optimized for Claude AI activation" badge

CLAUDE.md:

Add section on skill refactoring
Document metadata standards
Include keywords best practices

Create SKILLS_AUTHORING_GUIDE.md:

# Skills Authoring Guide

## Anthropic Best Practices

Our skills follow Anthropic's official Agent Skills specification.

## Skill Template

[Include refined template]

## Metadata Standards

All skills include:
- MIT license
- Version tracking (semantic versioning)
- Author attribution
- Category and domain classification
- Tool and tech stack documentation

## SKILL.md Structure

Target length: 100-200 lines
- Keywords section
- Quick start (2-3 examples)
- Core workflows (high-level)
- Scripts overview
- References guide
- Best practices (top 5)
- Examples (2-3 concrete)

## Progressive Disclosure

- SKILL.md: Core instructions only
- references/: Detailed frameworks and guides
- scripts/: Automation tools
- assets/: Templates and resources

Task 4.3: Version Control (2 hours)

Create Git Tags:

# Tag current state before refactoring
git tag v1.0.0-pre-refactor

# After refactoring
git tag v1.1.0-refactored

Commit Strategy:

# Phase 1
git commit -m "feat: add professional metadata to all 36 skills

- Add MIT license to all skills
- Add semantic versioning (v1.0.0)
- Add category and domain classification
- Add python-tools and tech-stack documentation
- Add keywords sections for better discovery"

# Phase 2
git commit -m "refactor: optimize 3 pilot skills following Anthropic best practices

- Reduce content-creator from 236 to 120 lines
- Reduce product-manager-toolkit from 352 to 150 lines
- Reduce senior-fullstack from 300 to 150 lines
- Move detailed content to references/
- Add allowed-tools where appropriate"

# Phase 3
git commit -m "refactor: optimize remaining 33 skills following Anthropic pattern

- Reduce all SKILL.md files to <200 lines
- Move detailed frameworks to references/
- Add keywords sections to all skills
- Add allowed-tools for restricted skills"

📐 Before/After Examples

Example 1: content-creator Skill

BEFORE (236 lines total):

---
name: content-creator
description: Comprehensive content marketing skill for creating blog posts, social media content, and SEO-optimized materials. Includes brand voice development, content templates, SEO analysis tools, and social media optimization strategies. Use when creating any marketing content, developing brand guidelines, optimizing for SEO, or planning content calendars.
---

# Content Creator

A comprehensive skill for creating high-performing marketing content with consistent brand voice, SEO optimization, and platform-specific best practices.

## Quick Start

### For Brand Voice Development
1. Run `scripts/brand_voice_analyzer.py` on existing content to establish baseline
2. Review `references/brand_guidelines.md` to select voice attributes
3. Apply chosen voice consistently across all content

[... 220 more lines including detailed frameworks, extensive examples, etc.]

AFTER (120 lines total):

---
name: content-creator
description: Create SEO-optimized marketing content with consistent brand voice. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creating social media content, analyzing brand voice, optimizing SEO, planning content calendars, or when user mentions content creation, brand voice, SEO optimization, social media marketing, or content strategy.
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: marketing
  domain: content-marketing
  updated: 2025-10-20
  python-tools: brand_voice_analyzer.py, seo_optimizer.py
  tech-stack: SEO, social-media-platforms
---

# Content Creator

Professional-grade brand voice analysis, SEO optimization, and platform-specific content frameworks.

## Keywords
content creation, blog posts, SEO, brand voice, social media, content calendar, marketing content, content strategy, content marketing, brand consistency, content optimization, social media marketing, content planning, blog writing

## Quick Start

### Brand Voice Development
```bash
python scripts/brand_voice_analyzer.py existing_content.txt

Then select archetypes from references/brand-voice-detailed-framework.md

SEO-Optimized Content

python scripts/seo_optimizer.py article.md "primary keyword" "secondary,keywords"

Apply recommendations to improve SEO score to >75/100

Social Media Content

Review platform in references/social-media-platform-deep-dive.md
Use templates from references/content_frameworks.md
Optimize for platform algorithms

Core Workflows

1. Brand Voice Consistency

Establish and maintain brand voice:

Analyze existing content with brand_voice_analyzer.py
Select personality archetypes (see references/brand-voice-detailed-framework.md)
Apply consistently across all content
Verify with analyzer

2. SEO Content Creation

Create optimized content:

Research keywords for topic
Write content using framework from references/content_frameworks.md
Run seo_optimizer.py to analyze and score
Apply recommendations (target score >75/100)

3. Platform-Specific Social Media

Optimize for each platform:

Select platform and review references/social-media-platform-deep-dive.md
Use appropriate template from references/content_frameworks.md
Follow platform-specific best practices
Schedule with content calendar

4. Content Calendar Planning

Plan and organize content:

Use assets/content_calendar_template.md
Balance content types and platforms
Align with marketing campaigns
Track performance

Scripts

brand_voice_analyzer.py

Analyze text for brand voice characteristics and readability.

Usage: python scripts/brand_voice_analyzer.py content.txt [json]
Output: Formality, tone, readability scores, recommendations

seo_optimizer.py

Comprehensive SEO analysis and scoring.

Usage: python scripts/seo_optimizer.py article.md "keyword" "secondary,keywords"
Output: SEO score (0-100), keyword density, meta tags, recommendations

References

brand-voice-detailed-framework.md - 5 personality archetypes, tone dimensions, voice samples
brand_guidelines.md - Quick brand voice reference
content_frameworks.md - 15+ content type templates (blog, email, social, video, case studies)
social-media-platform-deep-dive.md - Deep platform optimization (LinkedIn, Twitter, Instagram, Facebook, TikTok)
content-creation-examples.md - 10+ complete examples with before/after

Best Practices

✅ Run brand_voice_analyzer.py on all content before publishing
✅ Target SEO score >75/100 for all blog content
✅ Match content type to platform (see social media guide)
✅ Plan content 30 days ahead with calendar
✅ Analyze performance monthly and refine

Examples

Example 1: Blog Post Creation

User: "Write a blog post about AI automation for marketing teams"
1. Review framework: references/content_frameworks.md (Blog Post template)
2. Create draft in chosen brand voice archetype
3. Run: python scripts/seo_optimizer.py draft.md "AI marketing automation"
4. Apply recommendations (score improved 68→82)
5. Publish optimized content

Example 2: Social Media Campaign

User: "Create LinkedIn content calendar for product launch"
1. Review: references/social-media-platform-deep-dive.md (LinkedIn section)
2. Use: assets/content_calendar_template.md
3. Create 30-day calendar with post types
4. Apply LinkedIn best practices (posting times, formats)


**Result:** 120 lines (49% reduction), all expertise retained in references/

---

### Example 2: product-manager-toolkit Skill

#### BEFORE (352 lines):
- Covers RICE + Interviews + PRDs + Discovery + Metrics in one file
- Extensive frameworks embedded
- Many detailed examples

#### AFTER (150 lines):
- Clear quick start with 3 capabilities
- High-level workflow overview
- Strong pointers to detailed references
- 2 concrete examples
- Keywords section for discovery

**New Reference Files Created:**
- `references/rice-prioritization-guide.md` (detailed RICE methodology)
- `references/customer-discovery-methods.md` (interview frameworks)
- `references/product-metrics-frameworks.md` (North Star, funnels, feature metrics)

---

## 📋 Implementation Checklist

### Week 1: Foundation Enhancement

**Marketing Skills (3 skills):**
- [ ] content-creator - Add metadata, keywords
- [ ] marketing-demand-acquisition - Add metadata, keywords
- [ ] marketing-strategy-pmm - Add metadata, keywords

**C-Level Skills (2 skills):**
- [ ] ceo-advisor - Add metadata, keywords
- [ ] cto-advisor - Add metadata, keywords

**Product Skills (5 skills):**
- [ ] product-manager-toolkit - Add metadata, keywords
- [ ] agile-product-owner - Add metadata, keywords
- [ ] product-strategist - Add metadata, keywords
- [ ] ux-researcher-designer - Add metadata, keywords
- [ ] ui-design-system - Add metadata, keywords

**Engineering Core (9 skills):**
- [ ] senior-architect - Add metadata, keywords, allowed-tools
- [ ] senior-frontend - Add metadata, keywords
- [ ] senior-backend - Add metadata, keywords
- [ ] senior-fullstack - Add metadata, keywords, allowed-tools
- [ ] senior-qa - Add metadata, keywords, allowed-tools
- [ ] senior-devops - Add metadata, keywords
- [ ] senior-secops - Add metadata, keywords
- [ ] code-reviewer - Add metadata, keywords, allowed-tools: Read, Grep, Glob
- [ ] senior-security - Add metadata, keywords

**Engineering AI/ML/Data (5 skills):**
- [ ] senior-data-scientist - Add metadata, keywords
- [ ] senior-data-engineer - Add metadata, keywords
- [ ] senior-ml-engineer - Add metadata, keywords
- [ ] senior-prompt-engineer - Add metadata, keywords
- [ ] senior-computer-vision - Add metadata, keywords

**RA/QM Skills (12 skills):**
- [ ] regulatory-affairs-head - Add metadata, keywords
- [ ] quality-manager-qmr - Add metadata, keywords
- [ ] quality-manager-qms-iso13485 - Add metadata, keywords
- [ ] capa-officer - Add metadata, keywords
- [ ] quality-documentation-manager - Add metadata, keywords
- [ ] risk-management-specialist - Add metadata, keywords
- [ ] information-security-manager-iso27001 - Add metadata, keywords
- [ ] mdr-745-specialist - Add metadata, keywords
- [ ] fda-consultant-specialist - Add metadata, keywords
- [ ] qms-audit-expert - Add metadata, keywords, allowed-tools: Read, Grep, Glob
- [ ] isms-audit-expert - Add metadata, keywords, allowed-tools: Read, Grep, Glob
- [ ] gdpr-dsgvo-expert - Add metadata, keywords

**Deliverables:**
- [ ] All 36 skills have complete metadata
- [ ] All 36 skills have keywords sections
- [ ] Git commit with changes

---

### Week 2: Pilot Optimization

- [ ] Refactor content-creator (236→120 lines)
- [ ] Create new reference files for content-creator
- [ ] Refactor product-manager-toolkit (352→150 lines)
- [ ] Create new reference files for PM toolkit
- [ ] Refactor senior-fullstack (est. 300→150 lines)
- [ ] Test all 3 pilot skills with Claude
- [ ] Document lessons learned
- [ ] Git commit with refactorings

**Success Criteria:**
- [ ] All 3 pilot SKILL.md files <200 lines
- [ ] Skills activate correctly when tested
- [ ] References load properly
- [ ] No broken links

---

### Week 3: Full Rollout

**Product Team (4 skills, 8 hours):**
- [ ] agile-product-owner optimization
- [ ] product-strategist optimization
- [ ] ux-researcher-designer optimization
- [ ] ui-design-system optimization

**Engineering (13 skills, 8 hours):**
- [ ] Optimize all engineering core skills (8 skills)
- [ ] Optimize all AI/ML/Data skills (5 skills)

**RA/QM (12 skills, 4 hours):**
- [ ] Optimize all RA/QM skills
- [ ] Ensure compliance frameworks documented

**Deliverables:**
- [ ] All 33 remaining skills optimized
- [ ] All SKILL.md files <200 lines
- [ ] All details moved to references/
- [ ] Git commit with complete rollout

---

### Week 4: Validation & Documentation

**Testing (4 hours):**
- [ ] Create test prompts for all 36 skills
- [ ] Run activation tests
- [ ] Document any issues
- [ ] Fix any broken references

**Documentation (2 hours):**
- [ ] Create SKILLS_AUTHORING_GUIDE.md
- [ ] Update README.md with optimization notes
- [ ] Update CLAUDE.md with refactoring info
- [ ] Document metadata standards

**Version Control (2 hours):**
- [ ] Tag v1.1.0-optimized
- [ ] Create CHANGELOG.md entry
- [ ] Update all README files
- [ ] Push final changes

---

## 🎯 Pilot Skill Refactoring Details

### Pilot 1: content-creator

**File Changes:**

1. **SKILL.md** - Reduce from 236 to 120 lines
2. **references/brand-voice-detailed-framework.md** (NEW) - 150 lines
3. **references/social-media-platform-deep-dive.md** (NEW) - 200 lines
4. **references/content-creation-examples.md** (NEW) - 100 lines

**Total:** 236 lines SKILL.md → 120 SKILL.md + 450 references = better organization

### Pilot 2: product-manager-toolkit

**File Changes:**

1. **SKILL.md** - Reduce from 352 to 150 lines
2. **references/rice-prioritization-guide.md** (NEW) - 180 lines
3. **references/customer-discovery-methods.md** (NEW) - 150 lines
4. **references/product-metrics-frameworks.md** (NEW) - 120 lines

**Total:** 352 lines SKILL.md → 150 SKILL.md + 450 references = better organization

### Pilot 3: senior-fullstack

**File Changes:**

1. **SKILL.md** - Reduce from ~300 to 150 lines
2. **references/fullstack-architecture-patterns.md** (NEW) - Move detailed patterns
3. **references/fullstack-development-guide.md** (NEW) - Move workflow details
4. **references/tech-stack-implementation.md** (NEW) - Move stack-specific guides

---

## 📊 Success Metrics

### Quantitative Metrics

**Before Refactoring:**
- Average SKILL.md length: ~300 lines
- Skills with metadata: 0/36 (0%)
- Skills with keywords: 0/36 (0%)
- Skills with allowed-tools: 0/36 (0%)
- Total lines in SKILL.md files: ~10,800 lines

**After Refactoring:**
- Average SKILL.md length: ~150 lines (50% reduction)
- Skills with metadata: 36/36 (100%)
- Skills with keywords: 36/36 (100%)
- Skills with allowed-tools: 8/36 (22% where appropriate)
- Total lines in SKILL.md files: ~5,400 lines
- New reference files created: ~30 files, ~4,500 lines

**Net Result:**
- Better organized (same total content)
- Faster skill loading
- Clearer discovery and activation
- Professional metadata

### Qualitative Metrics

- [ ] Claude activates skills more reliably
- [ ] Skills load faster (less context consumed)
- [ ] Clearer which skill to use when
- [ ] Better documented and versioned
- [ ] Easier for team to maintain

---

## 🔧 Implementation Tools & Scripts

### Script 1: Metadata Generator

**Purpose:** Generate consistent metadata for all skills

**Usage:**
```bash
python tools/generate_metadata.py --skill content-creator --category marketing --domain content-marketing --tools "brand_voice_analyzer.py, seo_optimizer.py"

Output:

---
name: content-creator
description: [existing description]
license: MIT
metadata:
  version: 1.0.0
  author: borghei
  category: marketing
  domain: content-marketing
  updated: 2025-10-20
  python-tools: brand_voice_analyzer.py, seo_optimizer.py
---

Script 2: SKILL.md Line Counter

Purpose: Track progress on reducing SKILL.md lengths

Usage:

python tools/count_skill_lines.py

Output:

Skill Line Count Report:
========================
content-creator: 236 lines (Target: 120) ⚠️
product-manager-toolkit: 352 lines (Target: 150) ⚠️
...
Average: 300 lines (Target: 150)
Total SKILL.md lines: 10,800 (Target: 5,400)

Script 3: Reference Link Validator

Purpose: Ensure all reference links work after refactoring

Usage:

python tools/validate_references.py

Output:

Validating references in all skills...
✅ content-creator: All 5 references valid
❌ product-manager-toolkit: Broken link to references/metrics.md
...

📚 Reference Migration Guide

When to Move Content to References

Move if:

Detailed framework (>50 lines)
Comprehensive checklists (>20 items)
Extensive examples (>5 examples)
Platform-specific details (>30 lines per platform)
Procedural guides (step-by-step >30 steps)

Keep in SKILL.md if:

Essential workflow (core process)
Critical decision points
Quick start examples (2-3)
Script usage basics
High-level overview

Reference File Naming

Pattern: references/[topic]-[type].md

Examples:

rice-prioritization-guide.md (not rice.md)
brand-voice-detailed-framework.md (not brand.md)
social-media-platform-deep-dive.md (not social.md)

Benefits:

Clear what's in the file
Easy to discover
Consistent naming

🎓 Training Your Team

For Skill Authors

Before creating/updating a skill:

Read Anthropic's skill-creator skill
Review this refactoring plan
Follow the refined template
Keep SKILL.md lean (<200 lines)
Use progressive disclosure

Checklist for new skills:

YAML frontmatter complete (name, description, license, metadata)
Description includes triggers and keywords
Keywords section added
SKILL.md under 200 lines
Detailed content in references/
Scripts in scripts/ with clear purposes
All links tested
Skill tested with Claude

🚀 Quick Start Implementation

Day 1: Setup (2 hours)

Create tools/ directory:

mkdir -p /Users/rezarezvani/projects/claude-code-skills/tools

Create helper scripts:

metadata_generator.py
line_counter.py
reference_validator.py

Backup current state:

git tag v1.0.0-pre-refactor
git branch refactoring/metadata-enhancement
git checkout refactoring/metadata-enhancement

Day 2-3: Metadata Enhancement (12 hours)

Batch 1 - Marketing & C-Level (5 skills, 2.5 hours):

Update all frontmatter
Add keywords sections
Test activation

Batch 2 - Product Team (5 skills, 2.5 hours):

Update all frontmatter
Add keywords sections
Test activation

Batch 3 - Engineering Core (9 skills, 4.5 hours):

Update all frontmatter
Add allowed-tools where appropriate
Add keywords sections

Batch 4 - Engineering AI/ML (5 skills, 2.5 hours):

Update all frontmatter
Add keywords sections

Day 4: RA/QM Skills (12 skills, 6 hours):

Update all frontmatter with compliance frameworks
Add keywords sections
Add allowed-tools for audit skills

Day 5: Commit Phase 1:

git add -A
git commit -m "feat: add professional metadata to all 36 skills"
git push origin refactoring/metadata-enhancement

Week 2: Pilot Optimization

Monday-Tuesday: content-creator (8 hours):

Slim down SKILL.md
Create 3 new reference files
Test thoroughly

Wednesday-Thursday: product-manager-toolkit (8 hours):

Slim down SKILL.md
Create 3 new reference files
Test thoroughly

Friday: senior-fullstack (4 hours):

Slim down SKILL.md
Organize references
Test thoroughly

Weekend: Review & Commit:

git add -A
git commit -m "refactor: optimize 3 pilot skills following Anthropic best practices"

🎯 Success Criteria

Phase 1 Success

All 36 skills have complete metadata
All 36 skills have keywords sections
No broken skills (all still work)
Git committed and pushed

Phase 2 Success

3 pilot skills reduced to <200 lines each
New reference files created and linked
All 3 skills activate correctly
No regression in functionality

Phase 3 Success

All 33 remaining skills optimized
All SKILL.md files <200 lines
No broken links or references
All skills tested and working

Phase 4 Success

All 36 skills validated
Documentation updated
SKILLS_AUTHORING_GUIDE.md created
Version tagged and pushed

📞 Support During Refactoring

Common Issues & Solutions

Issue: "I broke the skill after refactoring"

Solution: Revert to backup branch, identify what broke, fix incrementally

Issue: "Reference links don't work"

Solution: Use relative paths: references/file.md, not absolute paths

Issue: "Claude doesn't activate the skill anymore"

Solution: Check description has clear triggers, verify YAML syntax valid

Issue: "Keywords too generic"

Solution: Use specific terms users would actually say

💡 Pro Tips

Tip 1: One Skill at a Time

Don't try to refactor all 36 at once. Do 3-5 per day maximum.

Tip 2: Test Immediately

After each refactor, test the skill works. Don't batch testing.

Tip 3: Keep Backups

Tag before major changes: git tag v1.0-before-refactor-skill-name

Tip 4: Reference First

When in doubt, move to references/. You can always move back to SKILL.md if needed.

Tip 5: User Feedback

Have actual users test refined skills and provide feedback.

🎊 Final Outcome

After completing this plan, you'll have:

✅ 36 professionally structured skills following Anthropic's official pattern ✅ Complete metadata (license, version, categorization) ✅ Enhanced discovery (keywords, better descriptions) ✅ Optimized loading (lean SKILL.md, rich references) ✅ Safer execution (allowed-tools where appropriate) ✅ Better documentation (authoring guide, standards) ✅ Maintained expertise (all content retained, better organized)

Your skills will be:

Faster to load
Easier to discover
Clearer to use
Safer to execute
Better organized
Professionally versioned

While maintaining:

All 97 Python tools
All reference materials
All frameworks and benchmarks
All domain expertise

Ready to start? I recommend beginning with Phase 1, Task 1.2 - updating the 3 marketing skills as they're the smallest domain and perfect for learning the pattern!

About

Claude Skills Systematic Refactoring Plan

📋 Table of Contents

📊 Executive Summary

Current State Analysis

Expected Improvements

🎯 Refactoring Principles

Following Anthropic's Official Pattern

What NOT to Change

Optimization Strategy

Phase 1: Foundation Enhancement (Week 1)

Task 1.1: Create Metadata Template

Task 1.2: Update All Marketing Skills (3 skills, 1.5 hours)

content-creator

marketing-demand-acquisition

marketing-strategy-pmm

Task 1.3: Update All C-Level Skills (2 skills, 1 hour)

ceo-advisor

cto-advisor

Task 1.4: Update All Product Team Skills (5 skills, 2.5 hours)

Task 1.5: Update All Engineering Skills (14 skills, 7 hours)

Task 1.6: Update All RA/QM Skills (12 skills, 6 hours)

Phase 2: Pilot Optimization (Week 2)

Task 2.1: Refactor content-creator Skill

Step 1: Enhanced Frontmatter (Already done in Phase 1)

Step 2: Add Keywords Section

Step 3: Slim Down SKILL.md

Step 3: Slim Down SKILL.md

Interview Analysis

PRD Creation

Core Workflows

1. Feature Prioritization

2. Customer Discovery

3. PRD Development

Scripts

rice_prioritizer.py

customer_interview_analyzer.py

References

Best Practices

Examples

Example 1: Quarterly Planning

Example 2: Interview Synthesis

Step 2: Add Keywords

Step 3: Slim Down SKILL.md

Phase 3: Full Rollout (Week 3)

Task 3.1: Product Team Skills (4 remaining, 8 hours)

Task 3.2: Engineering Core Skills (8 remaining, 6 hours)

Task 3.3: Engineering AI/ML/Data Skills (5 skills, 4 hours)

Task 3.4: RA/QM Skills (12 skills, 2 hours)

Phase 4: Validation & Documentation (Week 4)

Task 4.1: Testing Protocol (4 hours)

Task 4.2: Update Documentation (2 hours)

Task 4.3: Version Control (2 hours)

📐 Before/After Examples

Example 1: content-creator Skill

BEFORE (236 lines total):

AFTER (120 lines total):

SEO-Optimized Content

Social Media Content

Core Workflows

1. Brand Voice Consistency

2. SEO Content Creation

3. Platform-Specific Social Media

4. Content Calendar Planning

Scripts

brand_voice_analyzer.py

seo_optimizer.py

References

Best Practices

Examples

Example 1: Blog Post Creation

Example 2: Social Media Campaign

Script 2: SKILL.md Line Counter

Script 3: Reference Link Validator

📚 Reference Migration Guide

When to Move Content to References

Reference File Naming

🎓 Training Your Team

For Skill Authors

🚀 Quick Start Implementation