[GH-ISSUE #737] docs: clarify skill bootstrap when REA MCP is not configured #328

New issue

Closed

opened 2026-10-15 18:23:56 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:23:56 +00:00

Owner

Originally created by @morluto on GitHub (Oct 6, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/737

Originally assigned to: @N0zoM1z0 on GitHub.

Problem

A user can install REA's reverse-engineer-anything skill through skills.sh without registering REA's MCP server:

npx skills add morluto/rea --skill reverse-engineer-anything

The skill starts by routing targets to MCP tools that may not exist in that agent session. Its existing Readiness and setup section appears later and provides doctor, conditional setup, approval, restart, and a general CLI fallback. It does not make the fresh-install path explicit enough: skill installation supplies instructions, but does not install/configure the complete REA environment or make MCP tools available.

Documentation location

skills/reverse-engineer-anything/SKILL.md, especially Route the target first and Readiness and setup.
docs/installation.md for existing client selection, planning, and approval behavior.

Expected content

Put a short conditional readiness/bootstrap section before target routing. Proceed directly when REA tools are available; do not run diagnostics before every investigation.
Explain that installing the skill alone does not register the MCP server.
When REA tools are absent, run npx -y rea-agents@latest doctor and distinguish missing registration, broken/stale configuration, provider problems, and an agent session needing restart/reconnection.
For missing or broken registration, prepare a scoped setup plan for the current supported agent using explicit client selection and the existing read-only planning workflow. Show the exact proposed changes and obtain approval before applying configuration changes or installing Hopper.
Preserve bring-your-own Ghidra and the existing restriction against installing unrelated dependencies.
After approved setup, explain how to restart/reconnect, verify REA tools are available, and resume the original investigation.
Provide a concrete CLI fallback for a task that can proceed while MCP is unavailable, with the same evidence requirements.

Supporting evidence

Discovery was verified with:

npx --yes skills add morluto/rea --list

It found one skill, reverse-engineer-anything. This verifies discovery, not a fresh-install MCP workflow.

Relevant examples from leading skills on skills.sh:

agent-browser places the install command near the top and loads version-matched instructions from its installed CLI.
hyperframes-cli states prerequisites upfront, uses npx, and documents how to interpret doctor --json.
setup-matt-pocock-skills uses an inspect → present → confirm → write setup workflow.

These are reference patterns; REA should retain its existing scoped, plan-first setup behavior.

Validation

Exercise representative agent tasks with the skill installed but MCP absent, registration present but the session needing restart, and MCP already working. Verify the agent chooses the appropriate diagnosis/setup/reconnect path, requests approval only for actual setup changes, and resumes the investigation without inventing MCP tool availability. Do not substitute schema or discovery checks for this usability validation.

README follow-up after setup guidance lands

Once the skill bootstrap / rea setup guidance described above is implemented and committed in the repository, add the skills.sh installation route to README.md:

npx skills add morluto/rea --skill reverse-engineer-anything

Explain alongside the command that this installs the agent skill instructions, and link to the in-repo setup guidance for configuring REA's MCP server and required providers. Include the relationship to npx rea-agents setup, the need to restart/reconnect after MCP registration, and the existing plan/approval behavior. Keep the guided setup quick start available.

This README addition is part of this issue, sequenced after the setup guidance is in the repo so readers can follow a complete working path. Check both install routes and update relevant translated READMEs under the repository's documentation conventions.

Originally created by @morluto on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/737 Originally assigned to: @N0zoM1z0 on GitHub. ## Problem A user can install REA's `reverse-engineer-anything` skill through skills.sh without registering REA's MCP server: ```bash npx skills add morluto/rea --skill reverse-engineer-anything ``` The skill starts by routing targets to MCP tools that may not exist in that agent session. Its existing **Readiness and setup** section appears later and provides `doctor`, conditional `setup`, approval, restart, and a general CLI fallback. It does not make the fresh-install path explicit enough: skill installation supplies instructions, but does not install/configure the complete REA environment or make MCP tools available. ## Documentation location - [skills/reverse-engineer-anything/SKILL.md](https://github.com/morluto/rea/blob/main/skills/reverse-engineer-anything/SKILL.md), especially **Route the target first** and **Readiness and setup**. - [docs/installation.md](https://github.com/morluto/rea/blob/main/docs/installation.md) for existing client selection, planning, and approval behavior. ## Expected content - Put a short conditional readiness/bootstrap section before target routing. Proceed directly when REA tools are available; do not run diagnostics before every investigation. - Explain that installing the skill alone does not register the MCP server. - When REA tools are absent, run `npx -y rea-agents@latest doctor` and distinguish missing registration, broken/stale configuration, provider problems, and an agent session needing restart/reconnection. - For missing or broken registration, prepare a scoped setup plan for the current supported agent using explicit client selection and the existing read-only planning workflow. Show the exact proposed changes and obtain approval before applying configuration changes or installing Hopper. - Preserve bring-your-own Ghidra and the existing restriction against installing unrelated dependencies. - After approved setup, explain how to restart/reconnect, verify REA tools are available, and resume the original investigation. - Provide a concrete CLI fallback for a task that can proceed while MCP is unavailable, with the same evidence requirements. ## Supporting evidence Discovery was verified with: ```bash npx --yes skills add morluto/rea --list ``` It found one skill, `reverse-engineer-anything`. This verifies discovery, not a fresh-install MCP workflow. Relevant examples from leading skills on skills.sh: - [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) places the install command near the top and loads version-matched instructions from its installed CLI. - [hyperframes-cli](https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-cli/SKILL.md) states prerequisites upfront, uses `npx`, and documents how to interpret `doctor --json`. - [setup-matt-pocock-skills](https://skills.sh/mattpocock/skills/setup-matt-pocock-skills) uses an inspect → present → confirm → write setup workflow. These are reference patterns; REA should retain its existing scoped, plan-first setup behavior. ## Validation Exercise representative agent tasks with the skill installed but MCP absent, registration present but the session needing restart, and MCP already working. Verify the agent chooses the appropriate diagnosis/setup/reconnect path, requests approval only for actual setup changes, and resumes the investigation without inventing MCP tool availability. Do not substitute schema or discovery checks for this usability validation. ## README follow-up after setup guidance lands Once the skill bootstrap / `rea setup` guidance described above is implemented and committed in the repository, add the skills.sh installation route to `README.md`: ```bash npx skills add morluto/rea --skill reverse-engineer-anything ``` Explain alongside the command that this installs the agent skill instructions, and link to the in-repo setup guidance for configuring REA's MCP server and required providers. Include the relationship to `npx rea-agents setup`, the need to restart/reconnect after MCP registration, and the existing plan/approval behavior. Keep the guided setup quick start available. This README addition is part of this issue, sequenced after the setup guidance is in the repo so readers can follow a complete working path. Check both install routes and update relevant translated READMEs under the repository's documentation conventions.

bsakaguchi

2026-10-15 18:23:56 +00:00

closed this issue
added the
triage

documentation
labels

bsakaguchi commented

2026-10-15 18:23:57 +00:00

Author

Owner

@morluto commented on GitHub (Oct 6, 2026):

@N0zoM1z0 To clarify the expected outcome: an agent with only the REA skill installed should know how to get REA working when its MCP tools are unavailable. The skill should guide diagnosis, prepare setup for the current agent, present the proposed changes for approval, explain restart/reconnection, verify tool availability, and resume the original investigation.

The issue includes reference patterns from leading skills:

agent-browser: upfront installation and version-matched instructions.
hyperframes-cli: explicit prerequisites and diagnostic commands.
setup-matt-pocock-skills: inspect, present, confirm, then configure.

Once the setup guidance is implemented and committed, also add npx skills add morluto/rea --skill reverse-engineer-anything to the README, explaining its relationship to npx rea-agents setup and linking to the setup/reconnect instructions. This README follow-up is part of the issue.

@morluto commented on GitHub (Oct 6, 2026): @N0zoM1z0 To clarify the expected outcome: an agent with only the REA skill installed should know how to get REA working when its MCP tools are unavailable. The skill should guide diagnosis, prepare setup for the current agent, present the proposed changes for approval, explain restart/reconnection, verify tool availability, and resume the original investigation. The issue includes reference patterns from leading skills: - [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md): upfront installation and version-matched instructions. - [hyperframes-cli](https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-cli/SKILL.md): explicit prerequisites and diagnostic commands. - [setup-matt-pocock-skills](https://skills.sh/mattpocock/skills/setup-matt-pocock-skills): inspect, present, confirm, then configure. Once the setup guidance is implemented and committed, also add `npx skills add morluto/rea --skill reverse-engineer-anything` to the README, explaining its relationship to `npx rea-agents setup` and linking to the setup/reconnect instructions. This README follow-up is part of the issue.

bsakaguchi referenced this issue

2026-10-16 21:05:48 +00:00

[GH-ISSUE #3796] [Tracker] Open feature requests by area (October 2026) #1471

bsakaguchi referenced this issue

2026-10-16 21:05:50 +00:00

[GH-ISSUE #3796] [Tracker] Open feature requests by area (October 2026) #1471