research-first · zaxbyhub, claude — Claude Code skill: research before planning
The research-first skill checks current documentation and discussions before tracing code when an issue depends on an external framework, tool, or platform. For repo-local questions, it searches the repository instead.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a claude-codeWhat research-first does
Use the skill to investigate a bug, plan a fix, or examine technical debt. When a question depends on an outside framework, dependency, or platform behavior, it checks official documentation, newer releases, and discussions across separate sources first. It returns findings with URLs before beginning code tracing.
For questions about a repository’s own conventions or structure, it skips web research and reads AGENTS.md, docs/, and the source. It then follows each issue through the code and marks conclusions that lack enough evidence. The skill runs in a separate Explore context and cannot start sub-agents. If WebSearch or WebFetch cannot be used, it proceeds by tracing code, so external behavior cannot be checked online.
What it helps with
- check whether a dependency bug was fixed in a newer release
- find current guidance before planning a code change
- trace a failure through the relevant source code
- mark conclusions that still lack supporting evidence
Example prompts for the agent
- Investigate why this integration with an external framework behaves unexpectedly, starting with current documentation.
- Review technical debt in this repository using its project rules and trace the related code paths.
- Check whether a newer dependency release fixes this issue, then trace its cause through the source.
How to install research-first
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a claude-code2Manually: put the files in place
~/.claude/skills/research-first/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/research-first/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a codex2Manually: put the files in place
.agents/skills/research-first/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a cursor2Manually: put the files in place
.cursor/skills/research-first/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .claude/skills/research-first2Manually: put the files in place
.github/skills/research-first/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .claude/skills/research-firstManually: put the files in place
.devin/skills/research-first/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about research-first
How do I install research-first in Claude Code?
Run npx skills add ZaxbyHub/opencode-swarm --skill research-first -a claude-code, then use ~/.claude/skills/research-first/SKILL.md.
What does research-first do?
For issues involving external technology, it checks current documentation and discussions before tracing the code. For repository-specific questions, it looks directly at the project files.
What happens if web search is unavailable?
The skill reports the limitation and continues by tracing the code. It cannot verify current external behavior online in that case.
Source text
SKILL.md · MIT
--- name: research-first description: > Apply when planning fixes, investigating tech debt, architecting solutions, or diagnosing unknown issues that may involve external frameworks, dependencies, or platform behavior. Search online for current documentation and state-of-the-art approaches before tracing through code. context: fork agent: Explore metadata: audience: swarm-plugin --- ## Research Before Planning Protocol This skill body runs in an isolated Explore context: it has no conversation history and cannot spawn further sub-agents. Work from the task statement it receives, run searches and reads directly, and return a compact findings report. Scope guard — research the outside world only when the problem involves it: - If the question involves external frameworks, dependencies, platform or toolchain behavior, or a suspected upstream bug: research online first. - If the question is purely repo-local (project conventions, invariants, existing code structure), skip web research; the answer lives in the repository (AGENTS.md, docs/, and the source itself). - If WebSearch/WebFetch are unavailable in this environment, state that explicitly and proceed with code tracing rather than stalling. When researching: 1. Search current official documentation to confirm the behavior is NOT intended and NOT already fixed in a newer release 2. Search for state-of-the-art solutions, known community workarounds, and recent discussion of this problem type 3. Run multiple searches across distinct sources (official docs, issue trackers, release notes) rather than trusting the first hit 4. Report all findings — with URLs — before any code tracing begins Then trace each problem end-to-end through the actual source code. Do not stop until ≥95% confident in the root cause for every issue being investigated, and mark anything below that threshold as UNVERIFIED with what evidence is missing.
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm
Similar skills
All skills for Code review and refactoring →research-first by other authors comes first.