@mclawnet/agent 0.5.8 → 0.6.1

package/skills/mcp-builder/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: mcp-builder
+description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
+---
+
+# MCP Server Development Guide
+
+Create high-quality MCP servers that enable LLMs to effectively interact with external services and APIs. Quality is measured by how well it enables LLMs to accomplish real-world tasks.
+
+## When to Use
+
+- Building a new MCP server from scratch
+- Integrating an external API or service for LLM access via MCP
+- Designing tool schemas and resource definitions for MCP
+- Evaluating and improving existing MCP server quality
+
+## When NOT to Use
+
+- **Using existing MCP servers** — just configure them in your MCP client settings
+- **General API development** — this is specific to the MCP protocol for LLM tool use
+- **Claude API / SDK integration** — use the `claude-api` skill
+- **Simple shell scripts or automation** — use the `workflow-automation` skill
+
+---
+
+# Process
+
+Creating a high-quality MCP server involves four main phases:
+
+### Phase 1: Deep Research and Planning
+
+#### 1.1 Understand Agent-Centric Design Principles
+
+Before implementing, internalize these principles for designing tools for AI agents:
+
+- **Build for Workflows, Not Just API Endpoints** - Consolidate related operations (e.g., `schedule_event` that both checks availability and creates event). Focus on complete tasks, not individual API calls.
+- **Optimize for Limited Context** - Return high-signal info, not data dumps. Provide "concise" vs "detailed" options. Default to human-readable identifiers over technical codes.
+- **Design Actionable Error Messages** - Guide agents toward correct usage. Suggest next steps: "Try using filter='active_only' to reduce results."
+- **Follow Natural Task Subdivisions** - Tool names should reflect how humans think about tasks. Group related tools with consistent prefixes.
+- **Use Evaluation-Driven Development** - Create realistic evaluation scenarios early. Let agent feedback drive improvements.
+
+#### 1.2 Study MCP Protocol Documentation
+
+Use WebFetch to load: `https://modelcontextprotocol.io/llms-full.txt` -- the complete MCP specification.
+
+#### 1.3 Study SDK Documentation
+
+- **Python SDK**: WebFetch `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
+- **TypeScript SDK**: WebFetch `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
+
+#### 1.4 MCP Best Practices Quick Reference
+
+**Server Naming:**
+- Python: `{service}_mcp` (e.g., `slack_mcp`)
+- Node/TypeScript: `{service}-mcp-server` (e.g., `slack-mcp-server`)
+
+**Tool Naming:**
+- Use snake_case with service prefix: `{service}_{action}_{resource}`
+- Example: `slack_send_message`, `github_create_issue`
+- Be action-oriented, specific, and consistent
+
+**Response Formats:**
+- Support both JSON (programmatic) and Markdown (human-readable)
+- Default to Markdown; use `response_format` parameter for flexibility
+
+**Pagination:**
+- Always respect `limit` parameter; return `has_more`, `next_offset`, `total_count`
+- Default to 20-50 items; never load all results into memory
+
+**Character Limits:**
+- Define CHARACTER_LIMIT constant (typically 25,000)
+- Truncate gracefully with clear messages and filtering guidance
+
+#### 1.5 Study Target API Documentation
+
+Read through ALL available API documentation for the service you are integrating: official API reference, authentication, rate limiting, pagination patterns, error responses, data models.
+
+Use web search and WebFetch as needed to gather comprehensive information.
+
+#### 1.6 Create a Comprehensive Implementation Plan
+
+Based on your research, create a detailed plan covering:
+
+**Tool Selection:** Prioritize the most valuable endpoints that enable common workflows. Consider which tools work together for complex tasks.
+
+**Shared Utilities:** Identify common API request patterns, pagination helpers, filtering/formatting utilities, and error handling strategies.
+
+**Input/Output Design:** Define validation models (Pydantic for Python, Zod for TypeScript), consistent response formats, character limits, and truncation strategies.
+
+**Error Handling Strategy:** Plan graceful failure modes with clear, actionable, LLM-friendly natural language error messages.
+
+---
+
+### Phase 2: Implementation
+
+Now that you have a comprehensive plan, begin implementation following language-specific best practices.
+
+#### 2.1 Set Up Project Structure
+
+**For Python:**
+- Create a single `.py` file or organize into modules if complex
+- Use the MCP Python SDK (`FastMCP`) for tool registration
+- Define Pydantic models for input validation
+
+**For Node/TypeScript:**
+- Set up `package.json` and `tsconfig.json`
+- Use MCP TypeScript SDK with `server.registerTool`
+- Define Zod schemas for input validation
+
+#### 2.2 Implement Core Infrastructure First
+
+Create shared utilities before implementing tools:
+- API request helper functions
+- Error handling utilities
+- Response formatting functions (JSON and Markdown)
+- Pagination helpers
+- Authentication/token management
+
+#### 2.3 Implement Tools Systematically
+
+For each tool in the plan:
+
+**Define Input Schema:**
+- Use Pydantic (Python) or Zod (TypeScript) for validation
+- Include proper constraints (min/max length, regex patterns, ranges)
+- Provide clear, descriptive field descriptions with diverse examples
+
+**Write Comprehensive Docstrings/Descriptions:**
+- One-line summary of what the tool does
+- Detailed explanation of purpose and functionality
+- Explicit parameter types with examples
+- Complete return type schema
+- Usage examples (when to use, when not to use)
+- Error handling documentation with guidance on how to proceed
+
+**Implement Tool Logic:**
+- Use shared utilities to avoid code duplication
+- Follow async/await patterns for all I/O
+- Implement proper error handling
+- Support multiple response formats (JSON and Markdown)
+- Respect pagination parameters; check character limits and truncate
+
+**Add Tool Annotations:**
+- `readOnlyHint`: true for read-only operations
+- `destructiveHint`: false for non-destructive operations
+- `idempotentHint`: true if repeated calls have same effect
+- `openWorldHint`: true if interacting with external systems
+
+#### 2.4 Follow Language-Specific Best Practices
+
+**For Python, ensure:**
+- Using MCP Python SDK (`FastMCP`) with `@mcp.tool` decorator
+- Pydantic v2 models with `model_config`
+- Type hints throughout
+- Async/await for all I/O operations
+- Module-level constants (CHARACTER_LIMIT, API_BASE_URL)
+- Logging to stderr (never stdout, which interferes with stdio transport)
+
+**For Node/TypeScript, ensure:**
+- Using `server.registerTool` properly
+- Zod schemas with `.strict()`
+- TypeScript strict mode enabled
+- No `any` types - use proper types
+- Explicit `Promise<T>` return types
+- Build process configured (`npm run build`)
+
+---
+
+### Phase 3: Review and Refine
+
+After initial implementation:
+
+#### 3.1 Code Quality Review
+
+Review the code for:
+- **DRY Principle**: No duplicated code between tools
+- **Composability**: Shared logic extracted into functions
+- **Consistency**: Similar operations return similar formats
+- **Error Handling**: All external calls have error handling
+- **Type Safety**: Full type coverage (Python type hints, TypeScript types)
+- **Documentation**: Every tool has comprehensive docstrings/descriptions
+
+#### 3.2 Test and Build
+
+**Important:** MCP servers are long-running processes that wait for requests over stdio or HTTP. Running them directly will cause your process to hang indefinitely.
+
+**Safe ways to test:**
+- Use the evaluation harness (Phase 4) - recommended approach
+- Run the server in tmux to keep it outside your main process
+- Use a timeout: `timeout 5s python server.py`
+
+**For Python:**
+- Verify syntax: `python -m py_compile your_server.py`
+- Check imports work correctly by reviewing the file
+
+**For Node/TypeScript:**
+- Run `npm run build` and ensure it completes without errors
+- Verify `dist/index.js` is created
+
+#### 3.3 Quality Checklist
+
+Verify your implementation against these criteria:
+
+**Python Quality Checklist:**
+- [ ] FastMCP server initialized with descriptive name
+- [ ] All tools use `@mcp.tool` decorator with annotations
+- [ ] Pydantic v2 models for all input validation
+- [ ] Type hints on all functions and parameters
+- [ ] Async/await for all I/O operations
+- [ ] CHARACTER_LIMIT constant defined and enforced
+- [ ] Response format parameter (JSON/Markdown) supported
+- [ ] Pagination with `limit`, `offset`, `has_more` metadata
+- [ ] Actionable error messages (not raw exceptions)
+- [ ] No logging to stdout
+
+**TypeScript Quality Checklist:**
+- [ ] Server uses `registerTool` with proper schemas
+- [ ] Zod schemas with `.strict()` for all inputs
+- [ ] TypeScript strict mode, no `any` types
+- [ ] Explicit `Promise<T>` return types
+- [ ] CHARACTER_LIMIT constant defined and enforced
+- [ ] Response format parameter (JSON/Markdown) supported
+- [ ] Pagination with `limit`, `offset`, `has_more` metadata
+- [ ] Actionable error messages
+- [ ] Build succeeds without errors (`npm run build`)
+
+---
+
+### Phase 4: Create Evaluations
+
+After implementing your MCP server, create comprehensive evaluations to test its effectiveness.
+
+#### 4.1 Understand Evaluation Purpose
+
+Evaluations test whether LLMs can effectively use your MCP server to answer realistic, complex questions using only the tools provided.
+
+#### 4.2 Create 10 Evaluation Questions
+
+Follow this process:
+
+1. **Tool Inspection**: List available tools and understand their capabilities
+2. **Content Exploration**: Use READ-ONLY operations to explore available data
+3. **Question Generation**: Create 10 complex, realistic questions
+4. **Answer Verification**: Solve each question yourself to verify answers
+
+#### 4.3 Evaluation Requirements
+
+Each question must be:
+- **Independent**: Not dependent on other questions
+- **Read-only**: Only non-destructive operations required
+- **Complex**: Requiring multiple tool calls and deep exploration
+- **Realistic**: Based on real use cases humans would care about
+- **Verifiable**: Single, clear answer verifiable by string comparison
+- **Stable**: Answer won't change over time (use historical/closed data)
+
+Questions should NOT be solvable with straightforward keyword search. Use synonyms, related concepts, or paraphrases. Require multiple searches and synthesis.
+
+#### 4.4 Output Format
+
+Create an XML file with this structure:
+
+```xml
+<evaluation>
+  <qa_pair>
+    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
+    <answer>3</answer>
+  </qa_pair>
+  <!-- More qa_pairs... -->
+</evaluation>
+```
+
+---
+
+# Reference Resources
+
+## Documentation Library
+
+Load these resources as needed during development:
+
+### Core MCP Documentation (Load First)
+- **MCP Protocol**: Fetch from `https://modelcontextprotocol.io/llms-full.txt`
+
+### SDK Documentation (Load During Phase 1/2)
+- **Python SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
+- **TypeScript SDK**: Fetch from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
+
+### Transport Options
+
+MCP servers support multiple transports:
+
+| Transport | Best For | Clients | Communication |
+|-----------|----------|---------|---------------|
+| **Stdio** | Local/CLI tools | Single | Bidirectional |
+| **HTTP** | Web services | Multiple | Request-Response |
+| **SSE** | Real-time updates | Multiple | Server-Push |
+
+### Security Essentials
+
+- Store API keys in environment variables, never in code
+- Validate all inputs with schema validation (Pydantic/Zod)
+- Sanitize file paths to prevent directory traversal
+- Use HTTPS for all network communication
+- Report tool errors within result objects (set `isError: true`), not as protocol-level errors
+- Don't expose internal errors to clients; provide helpful but not revealing messages

package/skills/meeting-insights-analyzer/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: meeting-insights-analyzer
+description: Analyze meeting transcripts to uncover communication patterns, behavioral insights, and actionable feedback on speaking habits. Use when reviewing meeting performance, coaching communication skills, or preparing for feedback sessions.
+disable-model-invocation: true
+---
+
+# Meeting Insights Analyzer
+
+This skill transforms your meeting transcripts into actionable insights about your communication patterns, helping you become a more effective communicator and leader.
+
+## When to Use This Skill
+
+- Analyzing your communication patterns across multiple meetings
+- Getting feedback on your leadership and facilitation style
+- Identifying when you avoid difficult conversations
+- Understanding your speaking habits and filler words
+- Tracking improvement in communication skills over time
+- Preparing for performance reviews with concrete examples
+- Coaching team members on their communication style
+
+## When NOT to Use
+
+- **Meeting summarization only** — if you just need a summary without behavioral analysis, a general prompt suffices
+- **Audio transcription** — this skill analyzes text transcripts, not raw audio
+- **Project status tracking** — use project management tools instead
+- **Written communication review** — this is focused on verbal/meeting patterns
+
+## What This Skill Does
+
+1. **Pattern Recognition**: Identifies recurring behaviors across meetings like:
+   - Conflict avoidance or indirect communication
+   - Speaking ratios and turn-taking
+   - Question-asking vs. statement-making patterns
+   - Active listening indicators
+   - Decision-making approaches
+
+2. **Communication Analysis**: Evaluates communication effectiveness:
+   - Clarity and directness
+   - Use of filler words and hedging language
+   - Tone and sentiment patterns
+   - Meeting control and facilitation
+
+3. **Actionable Feedback**: Provides specific, timestamped examples with:
+   - What happened
+   - Why it matters
+   - How to improve
+
+4. **Trend Tracking**: Compares patterns over time when analyzing multiple meetings
+
+## How to Use
+
+### Basic Setup
+
+1. Download your meeting transcripts to a folder (e.g., `~/meetings/`)
+2. Navigate to that folder in Claude Code
+3. Ask for the analysis you want
+
+### Quick Start Examples
+
+```
+Analyze all meetings in this folder and tell me when I avoided conflict.
+```
+
+```
+Look at my meetings from the past month and identify my communication patterns.
+```
+
+```
+Compare my facilitation style between these two meeting folders.
+```
+
+### Advanced Analysis
+
+```
+Analyze all transcripts in this folder and:
+1. Identify when I interrupted others
+2. Calculate my speaking ratio
+3. Find moments I avoided giving direct feedback
+4. Track my use of filler words
+5. Show examples of good active listening
+```
+
+## Instructions
+
+When a user requests meeting analysis:
+
+1. **Discover Available Data**
+   - Scan the folder for transcript files (.txt, .md, .vtt, .srt, .docx)
+   - Check if files contain speaker labels and timestamps
+   - Confirm the date range of meetings
+   - Identify the user's name/identifier in transcripts
+
+2. **Clarify Analysis Goals**
+   
+   If not specified, ask what they want to learn:
+   - Specific behaviors (conflict avoidance, interruptions, filler words)
+   - Communication effectiveness (clarity, directness, listening)
+   - Meeting facilitation skills
+   - Speaking patterns and ratios
+   - Growth areas for improvement
+   
+3. **Analyze Patterns**
+
+   For each requested insight:
+   
+   **Conflict Avoidance**:
+   - Look for hedging language ("maybe", "kind of", "I think")
+   - Indirect phrasing instead of direct requests
+   - Changing subject when tension arises
+   - Agreeing without commitment ("yeah, but...")
+   - Not addressing obvious problems
+   
+   **Speaking Ratios**:
+   - Calculate percentage of meeting spent speaking
+   - Count interruptions (by and of the user)
+   - Measure average speaking turn length
+   - Track question vs. statement ratios
+   
+   **Filler Words**:
+   - Count "um", "uh", "like", "you know", "actually", etc.
+   - Note frequency per minute or per speaking turn
+   - Identify situations where they increase (nervous, uncertain)
+   
+   **Active Listening**:
+   - Questions that reference others' previous points
+   - Paraphrasing or summarizing others' ideas
+   - Building on others' contributions
+   - Asking clarifying questions
+   
+   **Leadership & Facilitation**:
+   - Decision-making approach (directive vs. collaborative)
+   - How disagreements are handled
+   - Inclusion of quieter participants
+   - Time management and agenda control
+   - Follow-up and action item clarity
+
+4. **Provide Specific Examples**
+
+   For each pattern found, include:
+   
+   ```markdown
+   ### [Pattern Name]
+   
+   **Finding**: [One-sentence summary of the pattern]
+   
+   **Frequency**: [X times across Y meetings]
+   
+   **Examples**:
+   
+   1. **[Meeting Name/Date]** - [Timestamp]
+      
+      **What Happened**:
+      > [Actual quote from transcript]
+      
+      **Why This Matters**:
+      [Explanation of the impact or missed opportunity]
+      
+      **Better Approach**:
+      [Specific alternative phrasing or behavior]
+   
+   [Repeat for 2-3 strongest examples]
+   ```
+
+5. **Synthesize Insights**
+
+   After analyzing all patterns, provide:
+   
+   ```markdown
+   # Meeting Insights Summary
+   
+   **Analysis Period**: [Date range]
+   **Meetings Analyzed**: [X meetings]
+   **Total Duration**: [X hours]
+   
+   ## Key Patterns Identified
+   
+   ### 1. [Primary Pattern]
+   - **Observed**: [What you saw]
+   - **Impact**: [Why it matters]
+   - **Recommendation**: [How to improve]
+   
+   ### 2. [Second Pattern]
+   [Same structure]
+   
+   ## Communication Strengths
+   
+   1. [Strength 1 with example]
+   2. [Strength 2 with example]
+   3. [Strength 3 with example]
+   
+   ## Growth Opportunities
+   
+   1. **[Area 1]**: [Specific, actionable advice]
+   2. **[Area 2]**: [Specific, actionable advice]
+   3. **[Area 3]**: [Specific, actionable advice]
+   
+   ## Speaking Statistics
+   
+   - Average speaking time: [X% of meeting]
+   - Questions asked: [X per meeting average]
+   - Filler words: [X per minute]
+   - Interruptions: [X given / Y received per meeting]
+   
+   ## Next Steps
+   
+   [3-5 concrete actions to improve communication]
+   ```
+
+6. **Offer Follow-Up Options**
+   - Track these same metrics in future meetings
+   - Deep dive into specific meetings or patterns
+   - Compare to industry benchmarks
+   - Create a personal communication development plan
+   - Generate a summary for performance reviews
+
+## Examples
+
+### Example 1: Conflict Avoidance Analysis (Inspired by Dan Shipper)
+
+**User**: "I download all of my meeting recordings and put them in a folder. Tell me all the times I've subtly avoided conflict."
+
+**Output**: 
+```markdown
+# Conflict Avoidance Patterns
+
+Found 23 instances across 15 meetings where you used indirect 
+communication or avoided addressing tensions directly.
+
+## Pattern: Hedging on Critical Feedback
+
+**Frequency**: 8 times across 7 meetings
+
+**Example 1: 1:1 with Sarah** - 00:14:32
+
+**What Happened**:
+> "So, I was thinking... maybe we could, like, potentially 
+> consider looking at the timeline again? I mean, if you 
+> think that makes sense. But whatever you think is best!"
+
+**Why This Matters**:
+You needed to address that Sarah's project was behind schedule, 
+but the hedging language ("maybe", "potentially", "if you think") 
+and the deflection at the end ("whatever you think") made it easy 
+for her to miss the urgency.
+
+**Better Approach**:
+"Sarah, the project is two weeks behind schedule. We need to 
+discuss what's blocking progress and create a new timeline 
+today."
+
+[Additional examples...]
+
+## Recommendations
+
+1. **Name the issue directly** in the first sentence
+2. **Remove hedging words** like "maybe," "kind of," "sort of"
+3. **Ask specific questions** instead of hinting
+4. **Schedule difficult conversations** instead of raising them casually
+```
+
+### Example 2: Leadership Facilitation
+
+**User**: "Analyze my team meetings and tell me about my facilitation style."
+
+**Output**: Provides insights on:
+- How much you speak vs. team members (60% vs. 40%)
+- Whether you ask questions or make statements (3:1 ratio)
+- How you handle disagreements (tendency to resolve too quickly)
+- Who speaks least and whether you draw them in
+- Examples of good and missed facilitation moments
+
+### Example 3: Personal Development Tracking
+
+**User**: "Compare my meetings from Q1 vs. Q2 to see if I've improved my listening skills."
+
+**Output**: Creates a comparative analysis showing:
+- Decrease in interruptions (8 per meeting → 3 per meeting)
+- Increase in clarifying questions (2 → 7 per meeting)
+- Improvement in building on others' ideas
+- Specific examples showing the difference
+- Remaining areas for growth
+
+## Setup Tips
+
+### Getting Meeting Transcripts
+
+**From Granola** (free with Lenny's newsletter subscription):
+- Granola auto-transcribes your meetings
+- Export transcripts to a folder: [Instructions on how]
+- Point Claude Code to that folder
+
+**From Zoom**:
+- Enable cloud recording with transcription
+- Download VTT or SRT files after meetings
+- Store in a dedicated folder
+
+**From Google Meet**:
+- Use Google Docs auto-transcription
+- Save transcript docs to a folder
+- Download as .txt files or give Claude Code access
+
+**From Fireflies.ai, Otter.ai, etc.**:
+- Export transcripts in bulk
+- Store in a local folder
+- Run analysis on the folder
+
+### Best Practices
+
+1. **Consistent naming**: Use `YYYY-MM-DD - Meeting Name.txt` format
+2. **Regular analysis**: Review monthly or quarterly for trends
+3. **Specific queries**: Ask about one behavior at a time for depth
+4. **Privacy**: Keep sensitive meeting data local
+5. **Action-oriented**: Focus on one improvement area at a time
+
+## Common Analysis Requests
+
+- "When do I avoid difficult conversations?"
+- "How often do I interrupt others?"
+- "What's my speaking vs. listening ratio?"
+- "Do I ask good questions?"
+- "How do I handle disagreement?"
+- "Am I inclusive of all voices?"
+- "Do I use too many filler words?"
+- "How clear are my action items?"
+- "Do I stay on agenda or get sidetracked?"
+- "How has my communication changed over time?"
+
+## Related Use Cases
+
+- Creating a personal development plan from insights
+- Preparing performance review materials with examples
+- Coaching direct reports on their communication
+- Analyzing customer calls for sales or support patterns
+- Studying negotiation tactics and outcomes
+