Research Topic

You are the engineering-manager. Investigate a topic and produce a reusable reference document that agents can consult during future work.

When to Use

• •An agent encounters an unfamiliar API, framework, or pattern
• •A skill needs companion documentation that doesn't exist yet
• •The team needs a decision-support reference (comparison, lookup table, runbook)
• •A recurring question keeps coming up across sessions

Step 1: Scope the Research

1. •Parse $ARGUMENTS to identify the topic
2. •Determine the research type:
   • •API/SDK reference — document endpoints, methods, configuration
   • •Pattern library — collect examples of a coding pattern
   • •Decision guide — compare options with trade-offs
   • •Troubleshooting runbook — symptoms, causes, fixes
   • •Integration guide — how to connect two systems
3. •Check if a reference already exists:
   bash

   find .claude/skills/ -name "*reference*" -o -name "*$TOPIC*" 2>/dev/null
   

4. •If existing reference found → offer to update it instead of creating a new one

Step 2: Gather Information

Use multiple sources, prioritizing reliability:

1. •Codebase exploration — Grep/Glob for existing usage patterns
2. •Official documentation — WebFetch from official docs sites
3. •Web search — WebSearch for recent articles, guides, Stack Overflow answers
4. •Existing skills — Read related skills for established patterns

For each source consulted, record:

• •URL or file path
• •Key finding (1-2 sentences)
• •Reliability assessment (official docs > blog posts > forum answers)

Step 3: Write the Reference Document

Use the template structure from .claude/skills/_templates/reference.md.template.

Create the file at .claude/skills/<skill-name>/reference.md if it supports an existing skill, or .claude/skills/<topic>/reference.md for standalone references.

The reference must include:

1. •Overview — what this reference covers, which skills/agents use it
2. •Core content — organized into logical sections with tables and code blocks
3. •Quick Reference — condensed lookup table for fast agent access
4. •Troubleshooting — common issues and fixes (if applicable)
5. •Sources — URLs and file paths consulted during research

Quality Criteria

• •Each section is self-contained (agents can read one section without the whole doc)
• •Tables preferred over prose for structured data
• •Code examples are copy-pasteable
• •No speculation — only documented, verified information
• •Dated so agents know when to re-research

Step 4: Register the Reference

1. •If the reference supports an existing skill, add it to that skill's directory
2. •If it's a standalone reference, link it from the relevant agent definition(s):
   • •Read the agent .md file
   • •Add to the agent's reference/context section
3. •Commit the reference:
   bash

   git add .claude/skills/<path>/reference.md
   git commit --no-gpg-sign -m "research: Add <topic> reference document"
   

Step 5: Summary

Research complete: <topic>
  - Reference: .claude/skills/<path>/reference.md
  - Sections: N
  - Sources: N consulted
  - Used by: <skill or agent list>

Inputs

Outputs

Error Handling