@jahonn/research-agent-skill 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# Research Agent Skill
+
+Deep research and analysis on any topic. 5 modes: Quick lookup, Deep Dive, Compare, Landscape, Evaluate. Structured reports with source evaluation.
+
+Works with any [Agent Skills](https://agentskills.io) compatible tool: Claude Code, OpenAI Codex, Trae, Cursor, Gemini CLI, and more.
+
+## Problem
+
+You ask your AI "what is X?" and get a generic, unsourced paragraph. You ask "should we use X or Y?" and get "it depends."
+
+**This skill gives you structured, sourced, opinionated research.**
+
+## Modes
+
+| Mode | You Say | Output |
+|------|---------|--------|
+| **Quick** | "What is gstack?" | 1-paragraph summary + 3 key facts |
+| **Deep Dive** | "Research AI coding agents" | Full report in `RESEARCH.md` |
+| **Compare** | "Claude Code vs Cursor vs Codex" | Scored comparison matrix + recommendation |
+| **Landscape** | "What's out there for PM tools?" | Categorized market map |
+| **Evaluate** | "Should we adopt X?" | Decision framework with scoring |
+
+## Install
+
+```bash
+# Via agentskills-cli
+npm install -g @jahonn/agentskills-cli
+agentskills install ./research-agent-skill -t all
+
+# Via ClawHub
+clawhub install research-agent
+```
+
+## Example
+
+**Input:** "Research the AI coding agent landscape and compare the top 5"
+
+**Output:**
+1. Web search across official docs, Reddit, HN, GitHub
+2. Source evaluation (credibility, recency, bias)
+3. Categorized landscape map (direct, adjacent, emerging)
+4. Comparison matrix scored across 5 dimensions
+5. Recommendation: "For solo devs → X, for teams → Y"
+6. All findings sourced with URLs
+
+## Research Quality
+
+- Source hierarchy (official > community > opinion)
+- Bias detection (sponsor, recency, popularity)
+- Cross-reference across multiple sources
+- Confidence scoring per finding
+- "Gaps & caveats" section for what we couldn't verify
+
+## Related
+
+- [PM Agent Skill](https://github.com/jahonn/pm-agent-skill) — uses research as Phase 1
+- [Dev Workflow Skill](https://github.com/jahonn/dev-workflow-skill) — uses research in Think phase
+- [Agent Skills Spec](https://agentskills.io/specification)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: research-agent
+description: Deep research and analysis agent for any topic. Use when the user wants to research a topic, analyze competitors, evaluate technologies, compare tools, investigate trends, do market research, or get a comprehensive analysis of anything. Triggers on phrases like "research", "investigate", "analyze", "compare", "what is", "tell me about", "look into", "deep dive", "competitor analysis", "market research", "technology evaluation", "find alternatives", "landscape analysis", "pros and cons", "should I use". Produces structured research reports with sources.
+---
+
+# Research Agent — Deep Investigation on Any Topic
+
+A structured research workflow that turns a vague question into a comprehensive analysis. 5 research modes, each with a clear output format. Supports web search, source evaluation, and structured reporting.
+
+## Research Modes
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **Quick** | "What is X?" / "Tell me about X" | 1-paragraph summary + 3 key facts |
+| **Deep Dive** | "Research X" / "Deep dive into X" | Full analysis report |
+| **Compare** | "Compare X vs Y" / "X or Y?" | Comparison matrix + recommendation |
+| **Landscape** | "What's out there for X?" / "Alternatives to X" | Market map + positioning |
+| **Evaluate** | "Should we use X?" / "Is X worth it?" | Decision framework with scoring |
+
+## How to Use
+
+### Quick Research (30 seconds)
+```
+"What is gstack?"
+"Tell me about Claude Code skills"
+```
+→ Web search, extract key facts, 1-paragraph summary. No fluff.
+
+### Deep Dive (2-5 minutes)
+```
+"Research the AI coding agent landscape"
+"Deep dive into Agent Skills standard"
+```
+→ Spawn subagent (Sonnet) with the Deep Dive prompt. Searches multiple sources, cross-references, identifies patterns, writes `RESEARCH.md`.
+
+### Compare (1-3 minutes)
+```
+"Claude Code vs Cursor vs Codex"
+"RICE vs Kano vs ICE for prioritization"
+"Notion vs Linear vs Jira"
+```
+→ Side-by-side comparison table with scoring across key dimensions. Includes a recommendation with reasoning.
+
+### Landscape Analysis (3-5 minutes)
+```
+"What open source projects exist for X?"
+"Map the competitive landscape for X"
+"What tools do PMs use for X?"
+```
+→ Categorized map of existing solutions. For each: what it does, what it misses, where the gap is.
+
+### Evaluate (2-3 minutes)
+```
+"Should we build on X or Y?"
+"Is it worth adopting X?"
+"Pros and cons of using X for our case"
+```
+→ Decision matrix scoring across dimensions (cost, effort, risk, fit, longevity). Recommendation with confidence level.
+
+## Phase Details
+
+### Deep Dive Prompt
+
+Spawn a subagent (Sonnet) with this research methodology:
+
+1. **Define the question.** Restate the research question. What specifically are we trying to find out?
+
+2. **Source gathering.** Search for:
+   - Official docs / primary sources (most reliable)
+   - Community discussions (Reddit, HN, Discord — real user opinions)
+   - Technical analysis (blog posts, benchmarks, comparisons)
+   - GitHub metrics (stars, activity, issues, contributors)
+   - Commercial context (funding, team, business model)
+
+3. **Source evaluation.** For each source:
+   - Credibility: official vs community vs opinion
+   - Recency: when was this published/updated?
+   - Bias: does the author have a stake in the outcome?
+
+4. **Pattern extraction.** What themes emerge across sources?
+   - Points of agreement (high confidence)
+   - Points of disagreement (needs further investigation)
+   - Gaps in available information
+
+5. **Structured output.** Write `RESEARCH.md` with:
+   - Executive summary (3-5 sentences)
+   - Key findings (numbered, with sources)
+   - Detailed analysis (organized by theme)
+   - Gaps and caveats (what we couldn't verify)
+   - Recommendation (if applicable)
+   - Sources (with URLs)
+
+### Compare Prompt
+
+For comparing N items across M dimensions:
+
+1. **Define comparison axis.** What dimensions matter for this decision?
+   - Functional: what can it do?
+   - Performance: how fast/reliable?
+   - Cost: pricing model, free tier?
+   - Ecosystem: integrations, community, docs?
+   - Maturity: how battle-tested?
+
+2. **Score each item** (1-5 per dimension):
+   ```
+   | Dimension     | Option A | Option B | Option C |
+   |---------------|----------|----------|----------|
+   | Feature set   | ⭐⭐⭐⭐   | ⭐⭐⭐     | ⭐⭐⭐⭐⭐  |
+   | Ease of use   | ⭐⭐⭐⭐⭐  | ⭐⭐⭐     | ⭐⭐       |
+   ```
+
+3. **Context-specific recommendation.** Not "A is best" but "A is best IF you need X, B if you need Y."
+
+### Landscape Prompt
+
+For mapping a space:
+
+1. **Categorize solutions:**
+   - Direct competitors (same approach, same users)
+   - Adjacent tools (different approach, overlapping use case)
+   - Workarounds (not products, but how people solve it today)
+   - Emerging (new, not proven yet)
+
+2. **For each solution:**
+   - What it does (1 sentence)
+   - What it does well (strength)
+   - What it misses (gap)
+   - Who should use it (ideal user)
+
+3. **Identify the gap.** Where is nobody doing a good job? That's the opportunity.
+
+## Output Files
+
+- `RESEARCH.md` — Deep dive report (full analysis with sources)
+- Comparison results go to stdout (capture in conversation)
+- Landscape maps go to stdout or `LANDSCAPE.md` if long
+
+## Model Selection
+
+| Mode | Model | Why |
+|------|-------|-----|
+| Quick | Haiku | Simple lookup, fast answer |
+| Deep Dive | Sonnet | Needs reasoning, source evaluation |
+| Compare | Sonnet | Needs judgment for scoring |
+| Landscape | Sonnet | Needs categorization and pattern recognition |
+| Evaluate | Sonnet | Needs decision-making framework |
+
+## Tips
+
+- **Be specific.** "Research AI" is too broad. "Research AI coding agents for solo developers" is actionable.
+- **State your goal.** "I need to decide between X and Y" gives the research direction.
+- **Time-box it.** "Give me the top 5, not top 50" keeps it focused.
+- **Ask for sources.** "Show me where you found this" for verification.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jahonn/research-agent-skill",
+  "version": "1.0.0",
+  "description": "Deep research and analysis agent for any topic. 5 modes: Quick, Deep Dive, Compare, Landscape, Evaluate. Structured reports with source evaluation. Works with Claude Code, Codex, Trae, Cursor, Gemini CLI and 20+ AI tools (Agent Skills standard).",
+  "keywords": [
+    "agent-skills",
+    "research",
+    "analysis",
+    "competitor-analysis",
+    "market-research",
+    "comparison",
+    "claude-code",
+    "codex",
+    "trae",
+    "ai-coding"
+  ],
+  "license": "MIT",
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "references/"
+  ]
+}

package/references/methodology.md

@@ -0,0 +1,110 @@
+# Research Agent — Methodology Reference
+
+## Source Hierarchy
+
+Rank sources by reliability:
+
+| Level | Source Type | Confidence | Example |
+|-------|------------|------------|---------|
+| 1 | Official docs / primary source | High | Project README, official API docs |
+| 2 | Code / data | High | GitHub repo, benchmarks, usage stats |
+| 3 | Expert analysis | Medium-High | Technical blog posts, conference talks |
+| 4 | Community discussion | Medium | Reddit, HN, Discord, Stack Overflow |
+| 5 | News / press | Medium-Low | TechCrunch, press releases |
+| 6 | Opinion / speculation | Low | Personal blogs, social media hot takes |
+
+**Rule:** Always cite the highest-level source available. If you only have Level 4-6 sources, flag the finding as "unverified."
+
+## Research Report Template
+
+```markdown
+# Research: [Topic]
+
+**Date:** YYYY-MM-DD
+**Question:** [Original research question]
+**Confidence:** High / Medium / Low
+
+## Executive Summary
+
+[3-5 sentences. What did we find? What's the bottom line?]
+
+## Key Findings
+
+1. **[Finding]** — [1 sentence explanation] (Source: [URL])
+2. **[Finding]** — [1 sentence explanation] (Source: [URL])
+3. **[Finding]** — [1 sentence explanation] (Source: [URL])
+
+## Detailed Analysis
+
+### [Theme 1]
+[Analysis with supporting evidence]
+
+### [Theme 2]
+[Analysis with supporting evidence]
+
+## Gaps & Caveats
+
+- [What we couldn't verify]
+- [What might have changed since source was published]
+- [Author biases in our sources]
+
+## Recommendation
+
+[If applicable. Clear, actionable, with reasoning.]
+
+## Sources
+
+1. [Title](URL) — [credibility level, date]
+2. [Title](URL) — [credibility level, date]
+```
+
+## Comparison Matrix Template
+
+```markdown
+| Dimension | Weight | Option A | Option B | Option C |
+|-----------|--------|----------|----------|----------|
+| [Feature] | 30%    | ⭐⭐⭐⭐   | ⭐⭐⭐     | ⭐⭐⭐⭐⭐  |
+| [Cost]    | 20%    | ⭐⭐       | ⭐⭐⭐⭐   | ⭐⭐⭐     |
+| [Ease]    | 25%    | ⭐⭐⭐⭐⭐  | ⭐⭐⭐     | ⭐⭐       |
+| [Ecosystem]| 25%   | ⭐⭐⭐     | ⭐⭐⭐⭐⭐  | ⭐⭐⭐⭐   |
+| **Total** | 100%   | **3.4**  | **3.7**  | **3.5**  |
+
+**Recommendation:**
+- Choose A if [condition]
+- Choose B if [condition]
+- Choose C if [condition]
+```
+
+## Web Search Strategy
+
+When researching a topic, run these searches in order:
+
+1. **Official:** `"[topic]" site:github.com` or `"[topic]" official docs`
+2. **Community:** `"[topic]" site:reddit.com` or `"[topic]" site:news.ycombinator.com`
+3. **Comparison:** `"[topic]" vs alternatives comparison 2026`
+4. **Critical:** `"[topic]" problems limitations issues`
+5. **Stats:** `"[topic]" stars users adoption metrics`
+
+This gives you: official story → real user opinions → competitive context → honest downsides → market validation.
+
+## Bias Detection
+
+Watch for these biases in sources:
+
+| Bias | Signal | Counter |
+|------|--------|---------|
+| **Sponsor bias** | "In partnership with..." | Find independent reviews |
+| **Recency bias** | "Latest and greatest" | Check if older solutions still work |
+| **Popularity bias** | "Most popular = best" | Best for whom? For what? |
+| **Confirmation bias** | Only positive mentions | Actively search for criticism |
+| **Author bias** | Author works for the company | Weight community sources higher |
+
+## When to Stop Researching
+
+- **Quick mode:** 1-2 sources. Done in 30 seconds.
+- **Deep Dive mode:** 5-10 sources. Stop when themes repeat.
+- **Compare mode:** 1 source per option + 1 independent comparison. Done.
+- **Landscape mode:** Enough to categorize all major players. Usually 10-20 sources.
+- **Evaluate mode:** Enough to score each dimension with confidence. Usually 5-8 sources.
+
+**Diminishing returns rule:** If your last 3 sources didn't change your conclusion, stop.