Skill: mrcalifornian/clawie-research (version 1.0.0)

--- name: research-agent description: "Deep research on any topic with structured report generation. Use when: (1) user asks for research, analysis, or investigation, (2) need competitive analysis, market research, or technology landscape, (3) user wants a comprehensive report on a topic. Outputs structured markdown reports with citations, key findings, and actionable insights." --- # Research Agent Conduct deep research and generate structured reports. ## Workflow ### 1. Scope Definition - Clarify the research question - Identify key aspects to investigate - Set boundaries (time, depth, focus areas) ### 2. Multi-Source Research Gather data from diverse sources: ```bash # Web search (DuckDuckGo) curl -s "https://api.duckduckgo.com/?q=QUERY&format=json" | jq '.RelatedTopics[:5]' # GitHub (repos, stars, activity) gh search repos "TOPIC" --limit 20 --json name,description,stargazersCount,url # News/Tech (Hacker News, TechCrunch) curl -s "https://hacker-news.firebaseio.com/v0/topstories.json" | jq '.[:10]' # NPM packages npm search PACKAGE --json 2>/dev/null | jq '.[0:5]' ``` ### 3. Analysis & Synthesis - Cross-reference findings across sources - Identify patterns, trends, gaps - Extract key statistics and quotes - Note contradictions or debates ### 4. Report Generation Use the standard report structure from `references/report-template.md`. ## Report Structure Every research report follows this format: ```markdown # [Topic] Research Report **Date:** YYYY-MM-DD **Researcher:** Clawie (AI Research Agent) **Sources:** X sources analyzed --- ## Executive Summary [2-3 paragraph overview with key findings] ## Key Findings ### Finding 1: [Title] [Evidence, data, sources] ### Finding 2: [Title] [Evidence, data, sources] ## Market/Technology Landscape [Competitors, alternatives, ecosystem] ## Trends & Predictions [Where things are heading] ## Gaps & Opportunities [What's missing, underserved areas] ## Recommendations [Actionable next steps] ## Sources [Numbered list of all sources with URLs] ## Methodology [Brief note on research approach] ``` ## Quality Standards - **Minimum sources:** 20+ for comprehensive reports - **Citations:** Every claim backed by source - **Objectivity:** Present multiple perspectives - **Actionability:** End with clear recommendations ## Quick Commands ```bash # Check trending GitHub repos for a topic gh search repos "ai agent" --sort stars --limit 30 --json name,description,stargazersCount,url,updatedAt # Get recent articles from a domain curl -sL "https://DOMAIN.com/feed" | grep -oP '<title>.*</title>' | head -20 # Check npm package popularity npm view PACKAGE version time.created time.modified ``` ## Tips - Start broad, then narrow down - Verify claims across multiple sources - Prioritize primary sources (official docs, papers) over secondary (blogs, news) - Note publication dates for recency - Flag uncertain or unverified information

path: scripts/research.py
content: #!/usr/bin/env python3
"""
Research helper script for the research-agent skill.
Provides utilities for gathering and analyzing research data.
"""

import json
import subprocess
import sys
from datetime import datetime

def github_search(topic: str, limit: int = 20) -> list:
    """Search GitHub repos for a topic."""
    try:
        result = subprocess.run(
            ["gh", "search", "repos", topic, "--limit", str(limit),
             "--json", "name,description,stargazersCount,url,updatedAt,language"],
            capture_output=True, text=True, check=True
        )
        return json.loads(result.stdout)
    except Exception as e:
        print(f"GitHub search failed: {e}", file=sys.stderr)
        return []

def npm_search(package: str, limit: int = 5) -> list:
    """Search NPM for packages."""
    try:
        result = subprocess.run(
            ["npm", "search", package, "--json"],
            capture_output=True, text=True
        )
        if result.returncode == 0:
            packages = json.loads(result.stdout)
            return packages[:limit]
    except Exception as e:
        print(f"NPM search failed: {e}", file=sys.stderr)
    return []

def generate_report_metadata(topic: str, sources_count: int) -> dict:
    """Generate metadata for a research report."""
    return {
        "topic": topic,
        "date": datetime.now().strftime("%Y-%m-%d"),
        "researcher": "Clawie (AI Research Agent)",
        "sources_analyzed": sources_count,
        "generated_at": datetime.now().isoformat()
    }

def main():
    if len(sys.argv) < 2:
        print("Usage: research.py <command> [args]")
        print("Commands:")
        print("  github <topic> [limit]  - Search GitHub repos")
        print("  npm <package> [limit]   - Search NPM packages")
        print("  meta <topic> <sources>  - Generate report metadata")
        sys.exit(1)

    command = sys.argv[1]

    if command == "github":
        topic = sys.argv[2] if len(sys.argv) > 2 else ""
        limit = int(sys.argv[3]) if len(sys.argv) > 3 else 20
        results = github_search(topic, limit)
        print(json.dumps(results, indent=2))

    elif command == "npm":
        package = sys.argv[2] if len(sys.argv) > 2 else ""
        limit = int(sys.argv[3]) if len(sys.argv) > 3 else 5
        results = npm_search(package, limit)
        print(json.dumps(results, indent=2))

    elif command == "meta":
        topic = sys.argv[2] if len(sys.argv) > 2 else "Unknown"
        sources = int(sys.argv[3]) if len(sys.argv) > 3 else 0
        metadata = generate_report_metadata(topic, sources)
        print(json.dumps(metadata, indent=2))

    else:
        print(f"Unknown command: {command}")
        sys.exit(1)

if __name__ == "__main__":
    main()

path: references/report-template.md
content: # Research Report Template

Use this structure for all research reports.

---

# [TOPIC] - Research Report

**Date:** YYYY-MM-DD
**Researcher:** Clawie (AI Research Agent)
**Sources Analyzed:** X

---

## Executive Summary

[2-3 paragraphs summarizing the most important findings. Write this LAST after completing research. Include:
- What was researched
- Top 3-5 key findings
- Main recommendation or insight]

---

## Key Findings

### 1. [Finding Title]

**Summary:** [One sentence summary]

**Details:**
- Point 1 with data
- Point 2 with data
- Point 3 with data

**Source:** [Citation]

---

### 2. [Finding Title]

[Same structure as above]

---

### 3. [Finding Title]

[Same structure as above]

---

## Landscape Overview

### Market Leaders / Key Players

| Name | Description | Key Metrics |
|------|-------------|-------------|
| Item 1 | Brief description | Stars/users/funding |
| Item 2 | Brief description | Stars/users/funding |

### Technology Stack

[If applicable, describe the technical landscape]

---

## Trends & Patterns

### Trend 1: [Name]
- Evidence
- Implications

### Trend 2: [Name]
- Evidence
- Implications

---

## Gaps & Opportunities

### Underserved Areas
1. [Gap 1]
2. [Gap 2]

### Emerging Opportunities
1. [Opportunity 1]
2. [Opportunity 2]

---

## Recommendations

### Immediate Actions
1. [Action 1]
2. [Action 2]

### Strategic Considerations
1. [Consideration 1]
2. [Consideration 2]

---

## Sources

1. [Source Title](URL) - Brief description
2. [Source Title](URL) - Brief description
3. [Source Title](URL) - Brief description
...

---

## Methodology

[Brief description of research approach:
- Sources queried
- Time period covered
- Any limitations or biases to note]

---

## Appendix

[Optional: Additional data, raw findings, or detailed tables that don't fit in main report]

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)