@mclawnet/agent 0.5.8 → 0.6.1

package/skills/performance-analysis/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: performance-analysis
+description: Analyze application performance, identify bottlenecks, and provide optimization recommendations. Use when profiling slow code, diagnosing latency issues, optimizing database queries, reducing memory usage, or improving throughput.
+disable-model-invocation: true
+---
+
+# Performance Analysis
+
+Systematic performance analysis for identifying bottlenecks, profiling application behavior, and providing actionable optimization recommendations.
+
+## Overview
+
+Performance problems are always specific — "the app is slow" is a symptom, not a diagnosis. This skill provides a structured process to move from symptoms to root causes to fixes, covering CPU, memory, I/O, network, and database performance dimensions.
+
+## When to Use
+
+- Application or page load is slower than expected
+- Database queries are timing out or causing latency
+- Memory usage is growing unexpectedly
+- API endpoints are slow under load
+- Need to establish performance baselines before optimization
+- Preparing for increased traffic or scaling
+
+## When NOT to Use
+
+- **Code correctness bugs** — use the debugging skill; fix correctness before performance
+- **Architecture redesign** — use the `architecture` skill for structural changes
+- **Load testing setup** — this skill analyzes results, not runs load tests
+- **Premature optimization** — if there's no measured problem, don't optimize
+
+## Analysis Process
+
+### Step 1: Establish Baseline
+
+Before optimizing anything, measure the current state.
+
+**What to measure:**
+- Response time (p50, p95, p99)
+- Throughput (requests/second)
+- Error rate
+- Resource utilization (CPU, memory, disk I/O, network)
+
+**How to measure:**
+- **Browser**: Chrome DevTools → Performance tab, Lighthouse
+- **Backend**: APM tools (DataDog, New Relic), custom timing middleware
+- **Database**: Query execution plans, slow query logs
+- **System**: `top`/`htop`, `vmstat`, `iostat`, `netstat`
+
+**Record the baseline** — you can't prove an optimization works without a before/after comparison.
+
+### Step 2: Identify the Bottleneck Category
+
+Performance problems fall into five categories. Identify which one before diving into code:
+
+| Category | Symptoms | Diagnostic Tools |
+|---|---|---|
+| **CPU-bound** | High CPU usage, slow computation, blocking main thread | Profiler (flame graph), CPU sampling |
+| **Memory-bound** | Growing memory, GC pauses, OOM errors | Heap snapshots, memory profiler |
+| **I/O-bound** | Slow file reads/writes, disk wait | `iostat`, strace, I/O profiler |
+| **Network-bound** | High latency, slow API calls, timeout errors | Network tab, traceroute, ping |
+| **Database-bound** | Slow queries, connection pool exhaustion, lock contention | EXPLAIN plans, slow query log, connection metrics |
+
+### Step 3: Profile the Hot Path
+
+Once you know the category, profile the specific code path:
+
+**CPU profiling:**
+```javascript
+// Node.js
+const { performance } = require('perf_hooks');
+const start = performance.now();
+expensiveOperation();
+console.log(`Took ${performance.now() - start}ms`);
+```
+
+```python
+# Python
+import cProfile
+cProfile.run('expensive_operation()', sort='cumulative')
+```
+
+**Memory profiling:**
+```javascript
+// Node.js - heap snapshot
+const v8 = require('v8');
+const snapshot = v8.writeHeapSnapshot();
+console.log(`Heap snapshot written to ${snapshot}`);
+```
+
+**Database profiling:**
+```sql
+-- PostgreSQL
+EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
+
+-- MySQL
+EXPLAIN FORMAT=JSON SELECT * FROM users WHERE email = 'test@example.com';
+```
+
+### Step 4: Analyze and Diagnose
+
+**CPU bottlenecks:**
+- Look for O(n²) or worse algorithms on growing datasets
+- Check for synchronous operations blocking the event loop
+- Identify hot functions in flame graphs (widest bars = most time)
+- Check for unnecessary serialization/deserialization
+
+**Memory bottlenecks:**
+- Look for unbounded caches, growing arrays, event listener leaks
+- Check for large object allocations in loops
+- Identify retained references preventing garbage collection
+- Watch for string concatenation in loops (use builders/arrays instead)
+
+**I/O bottlenecks:**
+- Check for sequential reads that could be parallel
+- Look for unbuffered I/O operations
+- Verify streaming is used for large files (not loading entire file into memory)
+- Check for unnecessary file operations (redundant reads, temp files not cleaned)
+
+**Network bottlenecks:**
+- Identify N+1 API call patterns (loop of individual requests instead of batch)
+- Check for missing compression (gzip/brotli)
+- Look for oversized payloads (sending more data than the client needs)
+- Verify connection reuse (keep-alive, connection pooling)
+
+**Database bottlenecks:**
+- Check for missing indexes (full table scans in EXPLAIN output)
+- Identify N+1 query patterns (ORM lazy loading in loops)
+- Look for unbounded queries (missing LIMIT/pagination)
+- Check for lock contention (long-running transactions holding locks)
+
+### Step 5: Recommend Fixes
+
+Prioritize fixes by impact and effort:
+
+| Priority | Criteria | Example |
+|---|---|---|
+| **Quick Win** | High impact, low effort | Add a missing database index |
+| **Planned** | High impact, medium effort | Implement caching layer |
+| **Backlog** | Low impact, low effort | Optimize string formatting |
+| **Evaluate** | High impact, high effort | Redesign data model |
+
+For each recommendation:
+1. **What**: Specific change to make
+2. **Why**: Root cause it addresses
+3. **Expected impact**: Quantified improvement estimate
+4. **Risk**: What could go wrong
+5. **Verification**: How to confirm the fix worked
+
+## Common Optimization Patterns
+
+### Caching
+
+```
+Cache hit rate < 80% → Cache is too small or keys are wrong
+Cache hit rate > 99% → Check if data is stale
+```
+
+**When to cache:**
+- Expensive computations called with same inputs
+- Database queries that rarely change
+- API responses with known freshness windows
+
+**Cache invalidation strategies:**
+- TTL (time-based) — simplest, works when staleness is acceptable
+- Event-based — invalidate on write, ensures freshness
+- Versioned — cache key includes version, new version = new cache
+
+### Database Query Optimization
+
+**Index strategy:**
+```sql
+-- Columns used in WHERE clauses
+CREATE INDEX idx_users_email ON users(email);
+
+-- Composite index for multi-column queries
+CREATE INDEX idx_orders_user_date ON orders(user_id, created_at DESC);
+
+-- Covering index (includes all selected columns)
+CREATE INDEX idx_orders_cover ON orders(user_id, status) INCLUDE (total);
+```
+
+**N+1 elimination:**
+```python
+# BAD: N+1 queries
+for user in users:
+    orders = db.query("SELECT * FROM orders WHERE user_id = ?", user.id)
+
+# GOOD: Single query with JOIN or IN
+orders = db.query("SELECT * FROM orders WHERE user_id IN (?)", user_ids)
+```
+
+### Async / Parallel Processing
+
+```javascript
+// BAD: Sequential
+const a = await fetchA();
+const b = await fetchB();
+const c = await fetchC();
+
+// GOOD: Parallel (when independent)
+const [a, b, c] = await Promise.all([fetchA(), fetchB(), fetchC()]);
+```
+
+### Pagination
+
+```sql
+-- Offset pagination (simple, slow for deep pages)
+SELECT * FROM items ORDER BY id LIMIT 20 OFFSET 1000;
+
+-- Cursor pagination (consistent, fast at any depth)
+SELECT * FROM items WHERE id > :last_seen_id ORDER BY id LIMIT 20;
+```
+
+## Performance Report Template
+
+```markdown
+## Performance Analysis Report
+
+### Summary
+- **Component**: [what was analyzed]
+- **Bottleneck**: [CPU / Memory / I/O / Network / Database]
+- **Impact**: [quantified: "p95 latency is 2.3s, target is 500ms"]
+- **Root cause**: [one sentence]
+
+### Baseline Measurements
+| Metric | Current | Target |
+|--------|---------|--------|
+| p50 latency | 450ms | 200ms |
+| p95 latency | 2.3s | 500ms |
+| Throughput | 50 rps | 200 rps |
+| Error rate | 0.5% | <0.1% |
+
+### Root Cause Analysis
+[Detailed explanation with evidence from profiling]
+
+### Recommendations
+1. **[Quick Win]** Add index on users.email → est. 60% query time reduction
+2. **[Planned]** Implement Redis cache for user profiles → est. 80% reduction in DB load
+3. **[Backlog]** Migrate to cursor pagination → eliminates deep page slowness
+
+### Verification Plan
+[How to measure improvement after each fix]
+```
+
+## Anti-Patterns
+
+### Optimizing Without Measuring
+**Problem**: "I think this loop is slow" → rewrites it → no measured improvement.
+**Fix**: Always measure before and after. Profile first, optimize second.
+
+### Micro-Optimization of Cold Paths
+**Problem**: Optimizing code that runs once during startup.
+**Fix**: Focus on hot paths — code that runs per-request or per-user-action.
+
+### Caching Everything
+**Problem**: Cache layer added everywhere, stale data bugs appear.
+**Fix**: Cache only what's measured as slow. Implement proper invalidation.
+
+### Ignoring Tail Latency
+**Problem**: p50 is fine, but p99 is 10x worse.
+**Fix**: Always measure percentiles. p99 affects 1 in 100 users — that's a lot of users at scale.

package/skills/podcast-generation/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: podcast-generation
+description: Create structured podcast scripts with dialogue, timing, and production notes. Use when generating podcast content, interview scripts, audio storytelling outlines, or multi-speaker dialogue for audio production.
+disable-model-invocation: true
+---
+
+# Podcast Generation
+
+Create professional podcast scripts with structured dialogue, timing estimates, segment planning, and production notes for audio content creation.
+
+## Overview
+
+This skill helps create complete podcast scripts from topic research through final production-ready scripts. It covers single-host, interview, panel discussion, and narrative storytelling formats with proper pacing, transitions, and audience engagement techniques.
+
+## When to Use
+
+- Creating podcast episode scripts from a topic or outline
+- Planning interview questions and conversation flow
+- Writing multi-speaker dialogue for audio content
+- Structuring educational or storytelling audio content
+- Generating show notes, summaries, and timestamps
+
+## When NOT to Use
+
+- **Blog posts or articles** — use the `content-research-writer` skill
+- **Video scripts** — use the `video-generation` skill (different pacing and visual cues)
+- **Actual audio synthesis** — this produces scripts, not audio files
+- **Music composition** — outside scope
+
+## Podcast Formats
+
+### Solo / Monologue
+One host presenting information or telling a story.
+- Duration: 10-30 minutes typical
+- Pacing: Varied — mix explanation, examples, and personal stories
+- Structure: Hook → Intro → 3-4 segments → Recap → CTA
+
+### Interview
+Host asking questions, guest answering.
+- Duration: 20-60 minutes typical
+- Pacing: Follow the guest's energy, go deeper on interesting threads
+- Structure: Intro → Guest intro → 5-8 questions → Rapid fire → Outro
+
+### Panel Discussion
+Multiple speakers discussing a topic.
+- Duration: 30-60 minutes typical
+- Pacing: Moderator keeps flow, each panelist gets equal time
+- Structure: Intro → Topic overview → Discussion rounds → Audience Q&A → Wrap
+
+### Narrative / Storytelling
+Produced content with narration, sound design cues, and story arc.
+- Duration: 15-45 minutes typical
+- Pacing: Slow build, emotional peaks and valleys
+- Structure: Cold open → Act 1 (setup) → Act 2 (conflict) → Act 3 (resolution) → Outro
+
+## Script Creation Process
+
+### Step 1: Research and Outline
+
+Before writing dialogue, define:
+
+1. **Topic**: What is this episode about? (one sentence)
+2. **Audience**: Who is listening? What do they already know?
+3. **Key takeaway**: What should the listener remember? (one sentence)
+4. **Format**: Solo / Interview / Panel / Narrative
+5. **Target duration**: How long?
+6. **Segments**: 3-5 main segments with topics
+
+### Step 2: Write the Script
+
+**Script format:**
+
+```
+[SEGMENT: Introduction — 2 min]
+
+HOST: Welcome to [Show Name]. I'm [Name], and today we're
+diving into [topic]. By the end of this episode, you'll
+understand [key takeaway].
+
+[TRANSITION: Music sting — 3 sec]
+
+[SEGMENT: Background — 5 min]
+
+HOST: Let's start with some context. [Topic] first emerged
+when... [background information]
+
+Here's what's interesting about this: [hook that creates
+curiosity]
+
+[SEGMENT: Deep Dive — 10 min]
+
+HOST: Now let's get into the details...
+```
+
+### Step 3: Pacing and Timing
+
+**Timing estimates:**
+- Average speaking pace: 150 words per minute
+- 10-minute segment ≈ 1,500 words of dialogue
+- Allow 10-15% extra time for pauses, transitions, music
+
+**Pacing rules:**
+- Vary segment length — don't make every segment the same duration
+- Place the most engaging content in the first third (prevent drop-off)
+- Add "micro-breaks" — brief pauses, music stings, or recaps every 5-7 minutes
+- End each segment with a tease for what's coming next
+
+### Step 4: Production Notes
+
+Add cues for audio production:
+
+```
+[SFX: Door opening]
+[MUSIC: Upbeat intro theme — 15 sec, fade under]
+[PAUSE: 2 sec for emphasis]
+[CLIP: Interview excerpt from Episode 12 — 30 sec]
+[MUSIC: Transition sting — 3 sec]
+[SFX: Typing sounds, subtle]
+```
+
+## Script Template
+
+```markdown
+# [Show Name] — Episode [N]: [Title]
+
+## Metadata
+- **Topic**: [one sentence]
+- **Format**: [Solo / Interview / Panel / Narrative]
+- **Target Duration**: [X minutes]
+- **Host(s)**: [names]
+- **Guest(s)**: [names, if applicable]
+
+## Pre-Production Notes
+- [Research sources]
+- [Key statistics to mention]
+- [Stories or anecdotes to include]
+
+---
+
+## Script
+
+### Cold Open [0:00 — 0:30]
+
+HOST: [Attention-grabbing opening line or question]
+
+[MUSIC: Intro theme — 15 sec]
+
+### Introduction [0:30 — 2:00]
+
+HOST: Welcome to [Show Name]...
+
+### Segment 1: [Title] [2:00 — 8:00]
+
+HOST: ...
+
+### Segment 2: [Title] [8:00 — 15:00]
+
+HOST: ...
+
+### Segment 3: [Title] [15:00 — 22:00]
+
+HOST: ...
+
+### Recap & CTA [22:00 — 25:00]
+
+HOST: Let's recap what we covered today...
+
+If you enjoyed this episode, [call to action].
+
+[MUSIC: Outro theme — 15 sec]
+
+---
+
+## Show Notes
+
+### Summary
+[2-3 sentence episode summary]
+
+### Timestamps
+- 0:00 — Introduction
+- 2:00 — [Segment 1 title]
+- 8:00 — [Segment 2 title]
+- 15:00 — [Segment 3 title]
+- 22:00 — Recap
+
+### Resources Mentioned
+- [Link 1]
+- [Link 2]
+
+### Credits
+- Host: [Name]
+- Music: [Source]
+- Production: [Name]
+```
+
+## Interview Question Design
+
+**Question types:**
+- **Opener**: Easy, warm-up question ("Tell us about your background")
+- **Core**: Deep questions about the topic ("Walk us through how you...")
+- **Challenge**: Push for deeper insight ("What would you say to critics who...")
+- **Story**: Elicit narratives ("Can you describe a time when...")
+- **Rapid fire**: Quick, fun questions to change pace
+
+**Good questions:**
+- Open-ended (not yes/no)
+- Specific enough to get concrete answers
+- Build on each other (create a narrative arc)
+- Include follow-up prompts ("And then what happened?")
+
+**Bad questions:**
+- Multiple questions in one ("What do you think about X and also Y?")
+- Leading questions ("Don't you think that X is the best approach?")
+- Questions the audience won't care about
+- Questions easily answered by reading the guest's bio
+
+## Audio Content Best Practices
+
+- **Start strong**: The first 30 seconds determine if someone keeps listening
+- **Use concrete examples**: "One user saved $50K" > "Users save money"
+- **Vary energy levels**: Mix high-energy segments with reflective moments
+- **Signpost transitions**: "Now let's shift to..." helps listeners follow
+- **Repeat key points**: Audio listeners can't re-read — repeat important ideas
+- **End with action**: Tell the listener what to do with what they learned