@mclawnet/agent 0.5.8 → 0.6.1

package/skills/github-deep-research/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: github-deep-research
+description: Conduct deep research on GitHub repositories, issues, pull requests, and open source projects. Use when analyzing repository architecture, investigating issue patterns, evaluating project health, or researching how a library works internally.
+disable-model-invocation: true
+---
+
+# GitHub Deep Research
+
+Systematic research methodology for analyzing GitHub repositories, understanding project internals, investigating issues and PRs, and evaluating open source project health.
+
+## Overview
+
+GitHub deep research goes beyond reading a README. It involves understanding a project's architecture, contribution patterns, issue trends, release cadence, and code quality to make informed decisions about adoption, contribution, or understanding.
+
+## When to Use
+
+- Evaluating whether to adopt an open source library
+- Understanding how a specific feature or API works internally
+- Investigating an issue or bug in a dependency
+- Analyzing contribution patterns and project health
+- Researching how similar projects solve the same problem
+- Preparing to contribute to an open source project
+
+## When NOT to Use
+
+- **General web research** — use the `deep-research` skill for broader topics
+- **Academic papers** — use the `academic-search` skill
+- **Simple API usage questions** — check the project's documentation first
+
+## Research Process
+
+### Phase 1: Repository Overview
+
+Start with the big picture before diving into code.
+
+**Key files to read first:**
+1. `README.md` — project purpose, quick start, key concepts
+2. `CONTRIBUTING.md` — development setup, code standards, PR process
+3. `CHANGELOG.md` or releases page — version history, breaking changes
+4. `package.json` / `Cargo.toml` / `go.mod` — dependencies, scripts
+5. `LICENSE` — usage rights and restrictions
+
+**Repository metrics to check:**
+- Stars and star growth trend (use star-history.com)
+- Open issues vs closed issues ratio
+- PR merge time (average time from open to merge)
+- Last commit date (is the project actively maintained?)
+- Number of contributors (bus factor — how many key contributors?)
+- Release frequency
+
+**Commands:**
+```bash
+# Clone for local analysis
+git clone --depth=50 https://github.com/owner/repo.git
+
+# Contribution statistics
+git shortlog -sn --no-merges | head -20
+
+# Recent activity
+git log --oneline --since="3 months ago" | wc -l
+
+# File change frequency (find hot files)
+git log --pretty=format: --name-only --since="6 months ago" | sort | uniq -c | sort -rn | head -20
+```
+
+### Phase 2: Architecture Analysis
+
+Understand how the project is structured.
+
+**Directory structure:**
+```bash
+# Get a high-level view
+find . -type f -name "*.ts" -o -name "*.py" -o -name "*.go" | head -50
+tree -L 2 --dirsfirst -I 'node_modules|.git|dist|build|__pycache__'
+```
+
+**Entry points:**
+- Where does execution start? (`main`, `index`, `app`)
+- What are the public APIs? (exported functions, HTTP routes)
+- How are plugins/extensions loaded?
+
+**Dependency graph:**
+- What are the core dependencies vs optional ones?
+- Are there circular dependencies between modules?
+- How deeply coupled are the internal packages?
+
+### Phase 3: Issue and PR Investigation
+
+For researching specific problems:
+
+**Finding relevant issues:**
+```bash
+# Search issues via GitHub CLI
+gh issue list --repo owner/repo --search "keyword" --state all --limit 30
+gh issue view 123 --repo owner/repo --comments
+
+# Search PRs
+gh pr list --repo owner/repo --search "keyword" --state all --limit 20
+gh pr view 456 --repo owner/repo
+```
+
+**Issue pattern analysis:**
+- What categories of bugs are most common?
+- Are there recurring issues that keep being reopened?
+- How responsive are maintainers to bug reports?
+- Are there workarounds documented in issue comments?
+
+**PR analysis:**
+- How are features typically implemented? (check merged PRs for patterns)
+- What does a successful PR look like? (structure, tests, docs)
+- What gets rejected? (check closed-but-not-merged PRs)
+
+### Phase 4: Code Deep Dive
+
+For understanding specific internals:
+
+**Trace execution flow:**
+1. Start from the public API entry point
+2. Follow the call chain through the code
+3. Note key abstractions and interfaces
+4. Identify where the actual work happens (often buried under layers)
+
+**Use search effectively:**
+```bash
+# Find where a function is defined
+grep -rn "function handleRequest\|def handle_request\|func HandleRequest" src/
+
+# Find where it's called
+grep -rn "handleRequest\|handle_request\|HandleRequest" src/ --include="*.ts"
+
+# Find related tests
+grep -rn "handleRequest\|handle_request" test/ --include="*.test.*"
+```
+
+**Read tests for behavior specification:**
+Tests often document expected behavior better than comments. Look for:
+- Edge cases the implementation handles
+- Error conditions and expected error types
+- Integration patterns with other modules
+
+### Phase 5: Project Health Evaluation
+
+**Health indicators:**
+
+| Indicator | Healthy | Warning | Concerning |
+|---|---|---|---|
+| Last commit | < 1 month | 1-6 months | > 6 months |
+| Open issues response | < 1 week | 1-4 weeks | > 1 month |
+| PR merge time | < 1 week | 1-4 weeks | > 1 month |
+| Breaking changes | Documented, versioned | Documented | Undocumented |
+| Test coverage | > 70% | 40-70% | < 40% |
+| Dependencies | Up to date | Minor versions behind | Major versions behind |
+| Security advisories | None open | Addressed quickly | Unaddressed |
+
+**Bus factor check:**
+```bash
+# If top 1-2 contributors own >80% of commits, bus factor is low
+git shortlog -sn --no-merges | head -5
+```
+
+## Research Report Template
+
+```markdown
+## GitHub Repository Research: [owner/repo]
+
+### Summary
+- **Purpose**: [what this project does]
+- **Maturity**: [experimental / growing / stable / declining]
+- **Recommendation**: [adopt / evaluate further / avoid]
+
+### Key Metrics
+| Metric | Value |
+|--------|-------|
+| Stars | X |
+| Open Issues | X |
+| Last Release | YYYY-MM-DD |
+| Contributors | X |
+| License | MIT/Apache/etc |
+
+### Architecture
+[Key structural decisions, main modules, dependency flow]
+
+### Strengths
+- [Specific strength with evidence]
+- [Specific strength with evidence]
+
+### Risks
+- [Specific risk with evidence]
+- [Specific risk with evidence]
+
+### Alternatives Considered
+| Project | Pros | Cons |
+|---------|------|------|
+| [Alternative 1] | ... | ... |
+| [Alternative 2] | ... | ... |
+
+### Recommendation
+[Detailed recommendation with reasoning]
+```
+
+## Tips
+
+- Always check the `/discussions` tab — often has architectural context not in issues
+- Read the git blame for critical files — understand why code is written a certain way
+- Check the CI/CD configuration for test and build practices
+- Look at `dependabot.yml` or `renovate.json` for dependency management practices
+- The `SECURITY.md` file reveals how seriously the project takes security

package/skills/image-generation/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: image-generation
+description: Guide effective AI image generation through prompt engineering, style direction, and iterative refinement. Use when creating images with AI tools, writing image prompts, designing visual assets, or improving generated image quality.
+disable-model-invocation: true
+---
+
+# Image Generation
+
+Craft effective prompts for AI image generation tools, with guidance on style direction, composition, iterative refinement, and common pitfalls.
+
+## Overview
+
+AI image generation quality depends heavily on prompt quality. This skill teaches structured prompt engineering for image generation — how to describe subjects, styles, compositions, lighting, and technical parameters to consistently get results that match your vision.
+
+## When to Use
+
+- Writing prompts for AI image generators (DALL-E, Midjourney, Stable Diffusion, etc.)
+- Creating visual assets for presentations, documentation, or marketing
+- Iterating on generated images to improve quality
+- Translating visual concepts into structured text descriptions
+- Designing consistent visual styles across multiple images
+
+## When NOT to Use
+
+- **Photo editing or manipulation** — use dedicated image editing tools
+- **Data visualization / charts** — use the `chart-visualization` skill
+- **Hand-drawn illustrations** — AI generation produces a different aesthetic
+- **Brand-specific assets with exact specifications** — AI generation lacks pixel-level precision
+
+## Prompt Engineering Framework
+
+### The SCLTA Structure
+
+Effective prompts include five components:
+
+1. **Subject**: What is the main focus? Be specific.
+2. **Context**: Where is it? What's the setting/background?
+3. **Lighting**: How is the scene lit?
+4. **Technique**: What artistic medium or style?
+5. **Attributes**: Quality modifiers, mood, color palette.
+
+**Example:**
+```
+Subject:   A red fox sitting on a moss-covered log
+Context:   In a misty forest at dawn, pine trees in background
+Lighting:  Soft golden hour light filtering through trees
+Technique: Watercolor painting style
+Attributes: Serene mood, muted earth tones, high detail
+```
+
+**Combined prompt:**
+"A red fox sitting on a moss-covered log in a misty forest at dawn, pine trees in the background, soft golden hour light filtering through trees, watercolor painting style, serene mood, muted earth tones, high detail"
+
+### Subject Description
+
+**Be specific, not vague:**
+- Bad: "a person in a room"
+- Good: "a woman in her 30s reading a leather-bound book in a cozy library armchair"
+
+**Include:**
+- What the subject IS (person, animal, object, scene)
+- What the subject is DOING (action, pose, expression)
+- Key distinguishing details (clothing, materials, colors)
+
+### Style and Technique
+
+**Artistic styles:**
+| Style | Effect |
+|---|---|
+| Photorealistic | Looks like a photograph |
+| Digital art | Clean, modern, saturated |
+| Oil painting | Rich textures, visible brushstrokes |
+| Watercolor | Soft edges, translucent colors |
+| Pencil sketch | Line-focused, grayscale or minimal color |
+| Isometric | 3D-like from fixed angle, good for diagrams |
+| Flat design | Minimal, geometric, solid colors |
+| Pixel art | Retro gaming aesthetic |
+| Art Nouveau | Organic curves, decorative borders |
+| Minimalist | Stripped to essentials |
+
+**Photography styles:**
+- Portrait: shallow depth of field, subject isolation
+- Landscape: wide angle, deep depth of field
+- Macro: extreme close-up, fine detail
+- Street: candid, urban, natural lighting
+- Studio: controlled lighting, clean background
+
+### Composition Guidelines
+
+**Camera angle / perspective:**
+- Eye level: neutral, relatable
+- Low angle: makes subject look powerful, imposing
+- High angle: makes subject look small, vulnerable
+- Bird's eye: overview, patterns, scale
+- Close-up: intimacy, detail, emotion
+- Wide shot: context, environment, scale
+
+**Rule of thirds:**
+Specify subject placement: "subject positioned at the left third of the frame"
+
+**Negative space:**
+"Minimalist composition with ample negative space on the right side"
+
+### Lighting
+
+Lighting dramatically affects mood:
+
+| Lighting | Mood |
+|---|---|
+| Golden hour | Warm, nostalgic, romantic |
+| Blue hour | Cool, contemplative, melancholy |
+| Hard noon sun | Harsh, dramatic, high contrast |
+| Overcast | Soft, even, neutral |
+| Backlighting | Silhouettes, halos, ethereal |
+| Candlelight | Intimate, warm, low-key |
+| Neon | Urban, cyberpunk, vibrant |
+| Studio ring light | Clean, beauty, even illumination |
+
+## Iterative Refinement
+
+### Strategy
+
+1. **Start broad**: Generate with your full prompt
+2. **Evaluate**: What's right and what's wrong?
+3. **Adjust one variable**: Change one aspect at a time
+4. **Compare**: Side-by-side with previous version
+5. **Repeat**: Until satisfied
+
+### Common Adjustments
+
+| Problem | Adjustment |
+|---|---|
+| Too busy / cluttered | Add "minimalist", "clean composition", "simple background" |
+| Wrong style | Be more explicit about the medium/technique |
+| Colors too saturated | Add "muted colors", "pastel palette", "desaturated" |
+| Not enough detail | Add "highly detailed", "intricate", "fine detail" |
+| Wrong mood | Adjust lighting and color palette descriptions |
+| Subject too small | Add "close-up", "portrait framing", "subject fills frame" |
+| Unwanted elements | Use negative prompts: "no text", "no watermark" |
+
+### Negative Prompts
+
+Specify what you DON'T want:
+```
+Negative: blurry, low quality, watermark, text, deformed hands,
+extra fingers, cartoon (when wanting realism)
+```
+
+## Use Case Recipes
+
+### Blog Header Image
+```
+A modern workspace with a laptop showing code on screen,
+cup of coffee beside it, soft morning light from a window,
+clean minimalist style, shallow depth of field focusing on
+the laptop, warm neutral color palette, photorealistic
+```
+
+### Icon / Logo Concept
+```
+Simple flat design icon of a shield with a lightning bolt,
+solid color on white background, vector art style, clean lines,
+no gradients, suitable for dark and light backgrounds
+```
+
+### Presentation Background
+```
+Abstract geometric pattern, subtle blue and purple gradient,
+clean modern design, low contrast for text readability,
+corporate professional aesthetic, 16:9 aspect ratio
+```
+
+### Technical Diagram Style
+```
+Isometric illustration of a server architecture,
+clean flat design, labeled components, soft color palette
+with blue primary and gray secondary, white background,
+infographic style with minimal detail
+```
+
+## Quality Checklist
+
+Before finalizing a generated image:
+
+- [ ] Subject is clear and correctly positioned
+- [ ] Style matches the intended use case
+- [ ] No unwanted artifacts (extra fingers, text glitches, weird edges)
+- [ ] Colors and mood match the project's visual language
+- [ ] Resolution is sufficient for intended display size
+- [ ] Image doesn't closely replicate any copyrighted work
+- [ ] Text in images (if any) is legible and correctly spelled
+
+## Common Pitfalls
+
+### Overloaded Prompts
+**Problem**: 200-word prompt with conflicting instructions.
+**Fix**: Keep prompts focused. One subject, one style, one mood.
+
+### Vague Descriptions
+**Problem**: "A nice picture of nature" → generic, uninspired result.
+**Fix**: Be specific about every element you care about.
+
+### Ignoring Aspect Ratio
+**Problem**: Generating square images for a widescreen banner.
+**Fix**: Specify aspect ratio ("16:9", "portrait 2:3", "square 1:1").
+
+### Text in Images
+**Problem**: AI struggles with readable text — generates misspelled or garbled letters.
+**Fix**: Add text in post-production using a design tool, not in the prompt.

package/skills/lead-research-assistant/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: lead-research-assistant
+description: Identify and qualify high-quality business leads by analyzing your product, searching for target companies, and providing actionable contact strategies. Use when building prospect lists, researching potential customers, or preparing sales outreach campaigns.
+disable-model-invocation: true
+---
+
+# Lead Research Assistant
+
+This skill helps you identify and qualify potential leads for your business by analyzing your product/service, understanding your ideal customer profile, and providing actionable outreach strategies.
+
+## When to Use This Skill
+
+- Finding potential customers or clients for your product/service
+- Building a list of companies to reach out to for partnerships
+- Identifying target accounts for sales outreach
+- Researching companies that match your ideal customer profile
+- Preparing for business development activities
+
+## When NOT to Use
+
+- **General company research** — use the `deep-research` skill
+- **Academic or technical research** — use the `academic-search` skill
+- **Market analysis reports** — use the `consulting-analysis` skill
+- **Content writing for marketing** — use the `content-research-writer` skill
+
+## What This Skill Does
+
+1. **Understands Your Business**: Analyzes your product/service, value proposition, and target market
+2. **Identifies Target Companies**: Finds companies that match your ideal customer profile based on:
+   - Industry and sector
+   - Company size and location
+   - Technology stack and tools they use
+   - Growth stage and funding
+   - Pain points your product solves
+3. **Prioritizes Leads**: Ranks companies based on fit score and relevance
+4. **Provides Contact Strategies**: Suggests how to approach each lead with personalized messaging
+5. **Enriches Data**: Gathers relevant information about decision-makers and company context
+
+## How to Use
+
+### Basic Usage
+
+Simply describe your product/service and what you're looking for:
+
+```
+I'm building [product description]. Find me 10 companies in [location/industry] 
+that would be good leads for this.
+```
+
+### With Your Codebase
+
+For even better results, run this from your product's source code directory:
+
+```
+Look at what I'm building in this repository and identify the top 10 companies 
+in [location/industry] that would benefit from this product.
+```
+
+### Advanced Usage
+
+For more targeted research:
+
+```
+My product: [description]
+Ideal customer profile:
+- Industry: [industry]
+- Company size: [size range]
+- Location: [location]
+- Current pain points: [pain points]
+- Technologies they use: [tech stack]
+
+Find me 20 qualified leads with contact strategies for each.
+```
+
+## Instructions
+
+When a user requests lead research:
+
+1. **Understand the Product/Service**
+   - If in a code directory, analyze the codebase to understand the product
+   - Ask clarifying questions about the value proposition
+   - Identify key features and benefits
+   - Understand what problems it solves
+
+2. **Define Ideal Customer Profile**
+   - Determine target industries and sectors
+   - Identify company size ranges
+   - Consider geographic preferences
+   - Understand relevant pain points
+   - Note any technology requirements
+
+3. **Research and Identify Leads**
+   - Search for companies matching the criteria
+   - Look for signals of need (job postings, tech stack, recent news)
+   - Consider growth indicators (funding, expansion, hiring)
+   - Identify companies with complementary products/services
+   - Check for budget indicators
+
+4. **Prioritize and Score**
+   - Create a fit score (1-10) for each lead
+   - Consider factors like:
+     - Alignment with ICP
+     - Signals of immediate need
+     - Budget availability
+     - Competitive landscape
+     - Timing indicators
+
+5. **Provide Actionable Output**
+   
+   For each lead, provide:
+   - **Company Name** and website
+   - **Why They're a Good Fit**: Specific reasons based on their business
+   - **Priority Score**: 1-10 with explanation
+   - **Decision Maker**: Role/title to target (e.g., "VP of Engineering")
+   - **Contact Strategy**: Personalized approach suggestions
+   - **Value Proposition**: How your product solves their specific problem
+   - **Conversation Starters**: Specific points to mention in outreach
+   - **LinkedIn URL**: If available, for easy connection
+
+6. **Format the Output**
+
+   Present results in a clear, scannable format:
+
+   ```markdown
+   # Lead Research Results
+   
+   ## Summary
+   - Total leads found: [X]
+   - High priority (8-10): [X]
+   - Medium priority (5-7): [X]
+   - Average fit score: [X]
+   
+   ---
+   
+   ## Lead 1: [Company Name]
+   
+   **Website**: [URL]
+   **Priority Score**: [X/10]
+   **Industry**: [Industry]
+   **Size**: [Employee count/revenue range]
+   
+   **Why They're a Good Fit**:
+   [2-3 specific reasons based on their business]
+   
+   **Target Decision Maker**: [Role/Title]
+   **LinkedIn**: [URL if available]
+   
+   **Value Proposition for Them**:
+   [Specific benefit for this company]
+   
+   **Outreach Strategy**:
+   [Personalized approach - mention specific pain points, recent company news, or relevant context]
+   
+   **Conversation Starters**:
+   - [Specific point 1]
+   - [Specific point 2]
+   
+   ---
+   
+   [Repeat for each lead]
+   ```
+
+7. **Offer Next Steps**
+   - Suggest saving results to a CSV for CRM import
+   - Offer to draft personalized outreach messages
+   - Recommend prioritization based on timing
+   - Suggest follow-up research for top leads
+
+## Examples
+
+### Example 1: From Lenny's Newsletter
+
+**User**: "I'm building a tool that masks sensitive data in AI coding assistant queries. Find potential leads."
+
+**Output**: Creates a prioritized list of companies that:
+- Use AI coding assistants (Copilot, Cursor, etc.)
+- Handle sensitive data (fintech, healthcare, legal)
+- Have evidence in their GitHub repos of using coding agents
+- May have accidentally exposed sensitive data in code
+- Includes LinkedIn URLs of relevant decision-makers
+
+### Example 2: Local Business
+
+**User**: "I run a consulting practice for remote team productivity. Find me 10 companies in the Bay Area that recently went remote."
+
+**Output**: Identifies companies that:
+- Recently posted remote job listings
+- Announced remote-first policies
+- Are hiring distributed teams
+- Show signs of remote work challenges
+- Provides personalized outreach strategies for each
+
+## Tips for Best Results
+
+- **Be specific** about your product and its unique value
+- **Run from your codebase** if applicable for automatic context
+- **Provide context** about your ideal customer profile
+- **Specify constraints** like industry, location, or company size
+- **Request follow-up** research on promising leads for deeper insights
+
+## Related Use Cases
+
+- Drafting personalized outreach emails after identifying leads
+- Building a CRM-ready CSV of qualified prospects
+- Researching specific companies in detail
+- Analyzing competitor customer bases
+- Identifying partnership opportunities