# Research Patterns

> Reference conventions for how yellow-research derives slugs, formats reports, and saves output under docs/research/. Use when authoring or modifying yellow-research commands or agents that write research output.

- Skill: `kinginyellows/research-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kinginyellows/research-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinginyellows/research-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: kinginyellows (https://skillmd.com/u/kinginyellows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kinginyellows/research-patterns

---


# Research Patterns

## What It Does

Reference conventions for how yellow-research derives slugs, formats reports,
and saves output under `docs/research/`.

## When to Use

Use when authoring or modifying yellow-research commands or agents that write
research output.

## Usage

Reference the sections below as preloaded context — this skill documents
conventions; it is not an executable workflow.

## Slug Naming

Convert the research topic to a slug for the output filename:

- Characters: `[a-z0-9-]` only — lowercase, hyphens, no spaces or special chars
- Max length: 40 characters
- Examples:
  - "React Server Components 2026" → `react-server-components-2026`
  - "How does EXA neural search work?" → `exa-neural-search`
  - "Competitor analysis: Notion vs Linear" → `notion-vs-linear-competitor`
- Collision handling: if `docs/research/<slug>.md` exists, append `-2`, `-3`

## Output Location

All deep research saves to: `docs/research/<slug>.md`

Create the directory if it doesn't exist:

```bash
mkdir -p docs/research
```

## Output Format

```markdown
# <Topic Title>

**Date:** YYYY-MM-DD
**Sources:** Perplexity, EXA, Tavily (list which were used)

## Summary

[2-3 sentence executive summary]

## Key Findings

### <Subtopic 1>

[Findings with source citations]

### <Subtopic 2>

[Findings with source citations]

## Sources

- [Source Title](URL) — brief note on what was found here
```

## Source Selection Guide

| Query Type                     | Primary Source                   | Secondary                    |
| ------------------------------ | -------------------------------- | ---------------------------- |
| Library / framework docs       | Context7 (user-level MCP)        | EXA `get_code_context_exa`   |
| Code examples, GitHub patterns | EXA `get_code_context_exa`       | GitHub grep                  |
| Keyword-tight general web      | Ceramic `ceramic_search`         | EXA `web_search_exa`         |
| Recent news, current events    | Perplexity `perplexity_search`   | Tavily `tavily_search`       |
| Competitive / company research | EXA `company_research_exa`       | Perplexity                   |
| Deep technical report          | Perplexity `perplexity_research` | Tavily `tavily_research`     |
| AST / structural code patterns | ast-grep `find_code`             | ast-grep `find_code_by_rule` |
| Long-horizon async report      | Parallel `createDeepResearch`    | EXA `deep_researcher_start`  |
| Specific URL content           | EXA `crawling_exa`               | Tavily `tavily_extract`      |

**Ceramic note:** Ceramic is a **lexical** search engine (English only,
1–50-word keyword queries). Before sending a topic to `ceramic_search`,
rewrite it into a concise keyword-form query — drop "how do I", "what is",
filler words; keep proper nouns, technical terms, version numbers. See
`https://docs.ceramic.ai/api/search/best-practices.md`. The Ceramic MCP at
`https://mcp.ceramic.ai/mcp` authenticates via OAuth 2.1 (browser flow on
first use) — same UX as Parallel Task, no API key in plugin.json.

## When to Compound Findings

After `/research:deep`, run `/compound` if the findings include:

- A novel architectural pattern worth sharing with the team
- A critical gotcha or anti-pattern discovered
- An institutional decision that will recur (e.g., "we use X instead of Y
  because...")
- A bug root cause that took significant investigation

Routine informational research does not need to be compounded.

## Graceful Degradation

If an MCP server is unavailable (key not set, connection error, rate limit):

- Log a brief note: "Skipping [source] — unavailable"
- Continue with remaining sources
- Never fail completely if at least 1 source is available
- If all sources fail, surface the error clearly

## API Key Setup

As of v2.0.0, EXA / Tavily / Perplexity API keys are stored in `userConfig`
(system keychain). `plugin.json` reads `${user_config.<key>}`; shell env
vars are no longer wired into the MCP processes. Perplexity hard-fails at
startup without a valid userConfig value (tools disappear entirely); EXA
and Tavily start but tool calls error at invocation.

To configure (one-time, no restart needed):

```text
/plugin disable yellow-research
/plugin enable yellow-research
```

Claude Code prompts for each key. Answer the ones you want; dismiss the
rest. Stored in OS keychain (or `~/.claude/.credentials.json` at 0600 on
minimal Linux).

Get keys from:

- EXA: https://exa.ai/
- Tavily: https://tavily.com/
- Perplexity: https://www.perplexity.ai/settings/api

The **Parallel Task** and **Ceramic** servers use OAuth (no API key
needed). Claude Code handles authentication automatically — you'll be
prompted to authorize on first use of each.

`CERAMIC_API_KEY` is the one remaining shell-env var. It is optional and
powers only the `/research:setup` REST live-probe (the Ceramic MCP uses
OAuth). Get a REST key at https://platform.ceramic.ai/keys if you want
that probe to run.

```sh
# Optional, REST live-probe only
export CERAMIC_API_KEY="your-key-here"
```

Power users who want a fully shell-env-driven setup can wrap each MCP in a
per-MCP launcher script (see `plugins/yellow-morph/bin/start-morph.sh`).
The plugin no longer reads `*_API_KEY` from shell env directly.

## MCP Tool Name Verification

After installing yellow-research, always verify actual tool names before writing
agent code or troubleshooting:

```text
ToolSearch keyword: "exa"
Tool name: mcp__plugin_yellow-research_exa__...

ToolSearch keyword: "tavily"
Tool name: mcp__plugin_yellow-research_tavily__...

ToolSearch keyword: "perplexity"
Tool name: mcp__plugin_yellow-research_perplexity__...

ToolSearch keyword: "parallel"
Tool name: mcp__plugin_yellow-research_parallel__...

ToolSearch keyword: "ceramic_search"
Tool name: mcp__plugin_yellow-research_ceramic__ceramic_search

ToolSearch keyword: "ast-grep__find_code"
Tool name: mcp__plugin_yellow-research_ast-grep__find_code

ToolSearch keyword: "ast-grep__find_code_by_rule"
Tool name: mcp__plugin_yellow-research_ast-grep__find_code_by_rule

ToolSearch keyword: "ast-grep__dump_syntax_tree"
Tool name: mcp__plugin_yellow-research_ast-grep__dump_syntax_tree

ToolSearch keyword: "ast-grep__test_match_code_rule"
Tool name: mcp__plugin_yellow-research_ast-grep__test_match_code_rule
```

Naming convention: `mcp__plugin_yellow-research_<server>__<tool>`.

Or run `/mcp` in Claude Code to see all registered tools.

**Never trust LLM-generated tool names** — they may be fictitious. Empirical
verification is required. If names differ from what's in agents/commands, update
the `allowed-tools` lists and any MCP tool references in agent bodies.