Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/research-first/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/research-first/

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.

research-first ZaxbyHub research-first forces agents to verify repo facts and external sources before planning or writing code. CX Codex +1 ★ 539repo stars research microsoft research runs a five-iteration investigation of one topic in your codebase, tracing real code paths and citing a source for every claim. CX Codex +1 ★ 3,232repo stars principle-redesign-from-first-principles backnotprop principle-redesign-from-first-principles — a skill that makes the agent rebuild an existing design as if the new requirement had been there from day one. Use it when a change ripples through types, docs, and examples. CX Codex +1 10,200installs thinking-first-principles tjboudreaux thinking-first-principles — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that separates real constraints from inherited convention and rebuilds from primitives. CX Codex +1 844installs edge-ai-tasks official Awesome Copilot Community edge-ai-tasks is a GitHub Copilot plugin that researches projects and plans implementation work. It targets large codebases and intermediate to expert users. ★ 41,430repo stars open-source-librarian jarrodwatts The open-source-librarian subagent investigates open-source libraries and codebases, tracing implementations and linking to exact GitHub lines. Use it for source-level and change-history questions. CX Codex ★ 1,064repo stars codex-first steipete codex-first routes tasks between Claude and Codex workers. Claude handles specifications and judgment while Codex runs implementations and automated reviews. CX Codex +1 288installs

From the same set121

The whole set →
update-or-delete-tests-that-assert-intentionally-removed-behavio update-or-delete-tests-that-assert-intentionally-removed-behavio is a Claude Code skill for revising or removing tests of deliberately removed behavior. It applies to code changes that retire a code path. CX Codex +1 ★ 539repo stars use-internals-di-seam-pattern-for-test-injectable-functions use-internals-di-seam-pattern-for-test-injectable-functions is a Claude Code skill that uses _internals as a DI seam and checks mock isolation in combined Bun test runs. CX Codex +1 ★ 539repo stars worktree-retry-cleanup worktree-retry-cleanup is a Claude Code skill that cleans up a swarm worktree lane before a task is dispatched again. CX Codex +1 ★ 539repo stars swarm Enables a rigorous swarm-style posture with parallel searches, visible plan updates, and dual review gates for code changes. CX Codex +1 ★ 539repo stars swarm-pr-subscribe swarm-pr-subscribe monitors open pull requests, triages incoming review comments or CI failures, and applies safe fixes until merge. CX Codex +1 ★ 539repo stars swarm-ci-monitor The swarm-ci-monitor skill monitors CI for an approved, reviewed PR, investigates failures, and works through fixes until checks pass. It can then merge the PR after a final review of its state. CX Codex +1 ★ 539repo stars commit-pr commit-pr — a checklist the agent must clear before it commits, pushes or opens a PR. Built for the case where an AI agent publishes the branch, not a person. CX Codex +1 ★ 539repo stars skill-edit-validation skill-edit-validation sweeps test suites for stale assertions after modifying skill markdown files, preventing unexpected CI breaks. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open