morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 07:47:29 +00:00

[GH-ISSUE #1459] fix(skills): make reverse-engineer-anything discoverable from the repository root #498

New issue

Closed

opened 2026-10-15 18:25:35 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:25:35 +00:00

Owner

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

Problem

The documented command fails with the latest published Vercel Skills CLI:

npx skills@1.7.2 add https://github.com/morluto/rea --skill reverse-engineer-anything

It discovers only REA's internal contributor skill, rea-tool-design, and cannot find the public reverse-engineer-anything skill. The non-interactive reproduction exits 1 before installing anything.

Verified on 2026-10-10. npm's latest dist-tag is 1.7.2, published 2026-10-09; this is also the latest GitHub release. REA's current main inspected for the report is c89c8f53187aac02e87f0ca11e3dd120b8c7efef; the local source snapshot is 817efaca9aafc4a72884773ff8b93a32cb6e3350. Host: macOS arm64, Node 25.1.0 / npm 11.8.0 for the external Skills CLI probes. REA runtime/build checks were not run with that toolchain.

Reproduction and observed result

Run from a disposable directory/home, with agent config overrides unset or isolated:

npx --yes skills@1.7.2 add https://github.com/morluto/rea \
  --skill reverse-engineer-anything --agent codex --yes

Found 1 skill
No matching skills found for: reverse-engineer-anything
Available skills:
  - rea-tool-design
exit: 1

--list misleadingly exits 0 and lists only rea-tool-design; it does not establish that the named public skill can be installed.

This breaks the installation guide's skill-only command. The README also links to the public skill's skills.sh page.

Root cause

REA stores authored instructions and five reference files under skill-src/reverse-engineer-anything/. The conventional skills/ directory is an ignored generated output, absent from a clean GitHub checkout. Separately, .agents/skills/rea-tool-design/ contains the contributor skill.

In Skills v1.7.2 discovery, discoverSkills() searches conventional containers including skills/ and .agents/skills/. skill-src/ is not one of those containers. The repository root is searched only one level down in this pass. Recursive fallback runs only when no skills were found, or --full-depth is supplied. Finding rea-tool-design suppresses that fallback, so filtering for the public skill later fails.

This is an interaction between REA's source layout and upstream discovery behavior; it is not evidence that Skills cannot install multi-file bundles or that MCP registration failed.

Verified alternatives

The following probes used the actual installed skills@1.7.2 CLI in disposable homes/workspaces. Layout variants used temporary copies of the current authored public and contributor bundles; they are not changes to REA main.

Input / layout	Result
GitHub repository root, current layout	Exit 1; only `rea-tool-design` found
Explicit GitHub URL to `skill-src/reverse-engineer-anything`	Exit 0; full bundle installed
Current layout with `--full-depth`	Exit 0; full bundle installed
Current layout without the contributor skill, in a temporary copy	Exit 0; recursive fallback finds the public skill
Authored public skill moved to `.agents/skills/reverse-engineer-anything/`	Exit 0; both skills discovered; selected public bundle installed byte-for-byte
Authored public skill moved to conventional `skills/`	Exit 0; full bundle installed
Explicit `.claude-plugin/plugin.json` skill path	Exit 0; full bundle installed

Every successful public-skill installation contained SKILL.md and all five references/*.md files. The explicit GitHub source URL also installed successfully for Codex, Pi, Qwen Code, Hermes Agent, and MiniMax Code together: one canonical copy, with agent-specific links where the Skills CLI uses them. These probes verify installation layout and bytes, not live harness discovery or REA tool calls.

Recommended fix: make `.agents/skills/` the authored source

Move the authored bundle from skill-src/reverse-engineer-anything/ to .agents/skills/reverse-engineer-anything/, keeping the existing .agents/skills/rea-tool-design/ beside it. Keep skills/reverse-engineer-anything/ as the ignored generated npm bundle.

This makes the unchanged repository-root install command discover the public skill, preserves one authored copy, and avoids changing runtime/package resource paths or inventing a plugin solely to fix discovery. Do not duplicate the skill text, commit generated output, delete the useful contributor skill, or make correctness depend on fallback search finding no other skills.

Update the source path in:

scripts/generate-skill-metadata.mjs and scripts/generate-package-metadata.mjs.
tests/boundary/filesystem/generatedSkill.test.ts and the source fixture in dependencyInstall.test.ts.
turbo.json metadata, skill-generation, and documentation task inputs; remove superseded skill-src/** inputs.
AGENTS.md, CONTRIBUTING.md, the PR template, and the installation guide's source link.
The authored-source exclusion in scripts/verify-package-pack.mjs: reject the new source location rather than checking only obsolete package/skill-src/.

Remove the empty skill-src/ representation after updating all consumers. Preserve the generator's existing semantics: source instructions stay authored; npm output adds tool_count, pins rea-agents@latest to the shipped version, preserves the complete reference inventory, and removes obsolete generated references. Runtime setup, doctor, uninstall, prepack, and conformance digest consumers can continue using the existing generated skills/ path.

Acceptance and verification

A clean Git snapshot, without dist/, ignored skills/, or prior installed skills, supports the exact repository-root command with Skills 1.7.2. Keep the contributor skill present in this check.
--list includes reverse-engineer-anything; explicit selection installs exactly that skill and all five references. Verify relative links and source byte integrity.
Verify an agent using the shared location and one requiring its own destination; include a repeated install and an existing unrelated skill control.
Generation remains deterministic and does not modify authored files. Existing generated-skill inventory/pinning tests still pass.
With REA's pinned toolchain, run relevant focused tests, npm run check:fast, npm run docs:check, npm run verify:package, and npm pack --dry-run. Check the packed bundle still has shipped metadata/version pins and excludes authored/contributor skill sources.
Add a public-consumer discovery check over a clean source snapshot; the existing generator and npm packaging checks do not exercise this GitHub-install path. Keep online/npm probes in an appropriate distribution verification lane rather than making ordinary local tests depend on network access.

Immediate workaround while the root layout remains unchanged:

npx skills@1.7.2 add \
  https://github.com/morluto/rea/tree/main/skill-src/reverse-engineer-anything \
  --skill reverse-engineer-anything

Installing a skill supplies instructions; it does not register the REA MCP server. Keep that existing distinction explicit. This is separate from the removed rea skills add helper in #660/#661 and from the official Codex plugin request in #1269.

Originally created by @morluto on GitHub (Oct 10, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/1459 ## Problem The documented command fails with the latest published Vercel Skills CLI: ```sh npx skills@1.7.2 add https://github.com/morluto/rea --skill reverse-engineer-anything ``` It discovers only REA's internal contributor skill, `rea-tool-design`, and cannot find the public `reverse-engineer-anything` skill. The non-interactive reproduction exits 1 before installing anything. Verified on 2026-10-10. npm's `latest` dist-tag is **1.7.2**, published 2026-10-09; this is also the [latest GitHub release](https://github.com/vercel-labs/skills/releases/tag/v1.7.2). REA's current main inspected for the report is `c89c8f53187aac02e87f0ca11e3dd120b8c7efef`; the local source snapshot is `817efaca9aafc4a72884773ff8b93a32cb6e3350`. Host: macOS arm64, Node 25.1.0 / npm 11.8.0 for the external Skills CLI probes. REA runtime/build checks were not run with that toolchain. ## Reproduction and observed result Run from a disposable directory/home, with agent config overrides unset or isolated: ```sh npx --yes skills@1.7.2 add https://github.com/morluto/rea \ --skill reverse-engineer-anything --agent codex --yes ``` ```text Found 1 skill No matching skills found for: reverse-engineer-anything Available skills: - rea-tool-design exit: 1 ``` `--list` misleadingly exits 0 and lists only `rea-tool-design`; it does not establish that the named public skill can be installed. This breaks [the installation guide's skill-only command](https://github.com/morluto/rea/blob/c89c8f53187aac02e87f0ca11e3dd120b8c7efef/docs/installation.md#skill-only-installation). The README also links to the public skill's skills.sh page. ## Root cause REA stores authored instructions and five reference files under `skill-src/reverse-engineer-anything/`. The conventional `skills/` directory is an ignored generated output, absent from a clean GitHub checkout. Separately, `.agents/skills/rea-tool-design/` contains the contributor skill. In [Skills v1.7.2 discovery](https://github.com/vercel-labs/skills/blob/671e8c320810d36fed80fac5f1a2c1bf7e82d812/src/skills.ts), `discoverSkills()` searches conventional containers including `skills/` and `.agents/skills/`. `skill-src/` is not one of those containers. The repository root is searched only one level down in this pass. Recursive fallback runs only when no skills were found, or `--full-depth` is supplied. Finding `rea-tool-design` suppresses that fallback, so filtering for the public skill later fails. This is an interaction between REA's source layout and upstream discovery behavior; it is not evidence that Skills cannot install multi-file bundles or that MCP registration failed. ## Verified alternatives The following probes used the actual installed `skills@1.7.2` CLI in disposable homes/workspaces. Layout variants used temporary copies of the current authored public and contributor bundles; they are not changes to REA main. | Input / layout | Result | | --- | --- | | GitHub repository root, current layout | Exit 1; only `rea-tool-design` found | | Explicit GitHub URL to `skill-src/reverse-engineer-anything` | Exit 0; full bundle installed | | Current layout with `--full-depth` | Exit 0; full bundle installed | | Current layout without the contributor skill, in a temporary copy | Exit 0; recursive fallback finds the public skill | | Authored public skill moved to `.agents/skills/reverse-engineer-anything/` | Exit 0; both skills discovered; selected public bundle installed byte-for-byte | | Authored public skill moved to conventional `skills/` | Exit 0; full bundle installed | | Explicit `.claude-plugin/plugin.json` skill path | Exit 0; full bundle installed | Every successful public-skill installation contained `SKILL.md` and all five `references/*.md` files. The explicit GitHub source URL also installed successfully for Codex, Pi, Qwen Code, Hermes Agent, and MiniMax Code together: one canonical copy, with agent-specific links where the Skills CLI uses them. These probes verify installation layout and bytes, not live harness discovery or REA tool calls. ## Recommended fix: make `.agents/skills/` the authored source Move the authored bundle from `skill-src/reverse-engineer-anything/` to `.agents/skills/reverse-engineer-anything/`, keeping the existing `.agents/skills/rea-tool-design/` beside it. Keep `skills/reverse-engineer-anything/` as the ignored generated npm bundle. This makes the unchanged repository-root install command discover the public skill, preserves one authored copy, and avoids changing runtime/package resource paths or inventing a plugin solely to fix discovery. Do not duplicate the skill text, commit generated output, delete the useful contributor skill, or make correctness depend on fallback search finding no other skills. Update the source path in: - `scripts/generate-skill-metadata.mjs` and `scripts/generate-package-metadata.mjs`. - `tests/boundary/filesystem/generatedSkill.test.ts` and the source fixture in `dependencyInstall.test.ts`. - `turbo.json` metadata, skill-generation, and documentation task inputs; remove superseded `skill-src/**` inputs. - `AGENTS.md`, `CONTRIBUTING.md`, the PR template, and the installation guide's source link. - The authored-source exclusion in `scripts/verify-package-pack.mjs`: reject the new source location rather than checking only obsolete `package/skill-src/`. Remove the empty `skill-src/` representation after updating all consumers. Preserve the generator's existing semantics: source instructions stay authored; npm output adds `tool_count`, pins `rea-agents@latest` to the shipped version, preserves the complete reference inventory, and removes obsolete generated references. Runtime setup, doctor, uninstall, prepack, and conformance digest consumers can continue using the existing generated `skills/` path. ## Acceptance and verification - A clean Git snapshot, without `dist/`, ignored `skills/`, or prior installed skills, supports the exact repository-root command with Skills 1.7.2. Keep the contributor skill present in this check. - `--list` includes `reverse-engineer-anything`; explicit selection installs exactly that skill and all five references. Verify relative links and source byte integrity. - Verify an agent using the shared location and one requiring its own destination; include a repeated install and an existing unrelated skill control. - Generation remains deterministic and does not modify authored files. Existing generated-skill inventory/pinning tests still pass. - With REA's pinned toolchain, run relevant focused tests, `npm run check:fast`, `npm run docs:check`, `npm run verify:package`, and `npm pack --dry-run`. Check the packed bundle still has shipped metadata/version pins and excludes authored/contributor skill sources. - Add a public-consumer discovery check over a clean source snapshot; the existing generator and npm packaging checks do not exercise this GitHub-install path. Keep online/npm probes in an appropriate distribution verification lane rather than making ordinary local tests depend on network access. Immediate workaround while the root layout remains unchanged: ```sh npx skills@1.7.2 add \ https://github.com/morluto/rea/tree/main/skill-src/reverse-engineer-anything \ --skill reverse-engineer-anything ``` Installing a skill supplies instructions; it does not register the REA MCP server. Keep that existing distinction explicit. This is separate from the removed `rea skills add` helper in #660/#661 and from the official Codex plugin request in #1269.

bsakaguchi

2026-10-15 18:25:35 +00:00

closed this issue
added the
bug
label

bsakaguchi referenced this issue

2026-10-16 21:13:29 +00:00

[PR #498] [MERGED] test: replace implementation lock-in with behavioural assertions #2027

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#498

No description provided.

Rows
Columns