About research-step
A workflow-routing skill for managing research as a beads epic with typed sub-issues and schema-defined outputs. It guides agents from exploring a research mission through planning, task execution, and summary updates, with each workflow read from its instructions file.
Key features
- 01Routes requests to named workflows
- 02Drafts and refines research missions
- 03Plans typed tasks in a beads graph
- 04Executes ready tasks and chains workflows
- 05Regenerates a human-readable summary
Use cases
- 01Explore a research question before planning
- 02Initialize and plan a research task graph
- 03Run a ready research task
- 04Refresh the session summary from beads
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/research-stepin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
assets/schemas.yamlscripts/epic-root.shsummary-check.shvalidate-output.shwrite-meta.shworkflows/brainstorm.mdexecute.mdinit.mdplan.mdupdate-summary.mdDetails
From the project READMEResearch Step
Models a research session as a beads epic. Each unit of work is a typed sub-issue whose metadata.research_step.output matches a JSON schema in assets/schemas.yaml.
This skill is a router. Inspect the working directory and the user's request, pick one workflow, then read its .md file in workflows/ and follow it. Do not execute a workflow from memory — always open the file first.
Setup
There are no hard preconditions. If mission.md does not exist, the brainstorm workflow will help the user draft one.
Installing bd and jq, running bd init, and verifying scripts/summary-check.sh works are the responsibility of the init workflow. Once init has run, subsequent workflows assume the environment is ready.
Files
| Path | Role |
|---|---|
mission.md | Input. The research task. |
.beads/ | Source of truth for state. |
summary.md | Derived view of the session, regenerated by update-summary. Beads is the source of truth; this file is just a digest for humans and for brainstorm. Frontmatter beads_snapshot records the state it was rendered from. |
background_knowledge.txt | Optional. Long-form context referenced from issue metadata via summary_path. |
Workflows
| Name | Purpose | Detailed instructions |
|---|---|---|
| brainstorm | Default. Conversational exploration of current state; drafts/refines mission.md; hands off to other workflows when the user is ready to act. | workflows/brainstorm.md |
| init | Set up the environment: install bd/jq, run bd init, verify scripts/summary-check.sh. Hands off to plan. | workflows/init.md |
| plan | Create or extend the graph. Bootstraps the epic + initial frontier from mission.md, or replans downstream tasks after a closed task. | workflows/plan.md |
| execute | Run one ready task end-to-end. Hands off to plan when the closed task type unlocks new structure; otherwise to update-summary. | workflows/execute.md |
| update-summary | Regenerate summary.md from beads. Idempotent — no-op when scripts/summary-check.sh reports status: fresh. | workflows/update-summary.md |
Task-type schemas live in assets/schemas.yaml.
Routing
1. Honor explicit requests
If the user named a workflow ("init the research", "refresh the summary", "run the next step", "execute task bd-xyz"), dispatch to that workflow.
2. Otherwise → brainstorm
If the user did not name a workflow, run brainstorm. It inspects the working directory, answers the user's question, drafts or refines mission.md when appropriate, and hands off to init / plan / execute / update-summary once the user is ready to act.
3. Chaining
- init → always run plan afterwards (which then chains to update-summary).
- plan → always run update-summary afterwards so the digest reflects the new graph.
- execute → if the closed task type is
literature_review,hypothesis,analysis, orsynthesis, chain to plan (which chains to update-summary); otherwise chain directly to update-summary. - update-summary and brainstorm → never chain.
Boundaries
This skill does not validate output quality or cache results. mission.md is written only by brainstorm and only with user confirmation. bd init is run by init. Each workflow's .md file states its own scope.