docs(skills): Bundle protocol setup guides into data-client-setup

[ntucker]

Requested by Nathaniel · project thread

Stacked on #4170.

Motivation

/data-client-setup handed off to three other skills (data-client-rest-setup, data-client-graphql-setup, data-client-endpoint-setup). Installing only the setup skill left an agent with nothing to follow after the provider was in place.

Solution

data-client-setup is now one entry point that carries the protocol setup guides itself. The standalone protocol skills stay, and yarn build:skills keeps the bundled copies in sync.

 ### REST APIs
-Apply skill **"data-client-rest-setup"** which will:
+Follow [references/data-client-rest-setup.md](references/data-client-rest-setup.md), which will:

• references.json takes a skills list. Each bundled skill's SKILL.md body (front matter stripped) becomes references/<skill>.md. Its references and scripts are copied under references/<skill>/, keeping their layout, and its relative links are rewritten to point there. The REST guide's axios codemod (scripts/axios-to-rest.js) comes along, so <skill-root>/scripts/... still resolves.
• Generated references come from their sources, not from what's on disk, so a bundle can't copy a stale reference. Hand-written files get the generated header (<!-- --> for markdown, // for scripts).
• Drift check: yarn build:skills --check now also fails when a bundled copy differs from its skill.
• Edit hook also regenerates after an edit to any skill another skill bundles.

Open questions

#4153 adds an "Install the Skills This Project Needs" table to data-client-setup/SKILL.md. Whichever of the two PRs merges second should drop the *-setup rows and keep the usage skills.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SfViJqNPeWjfhvq9wLhPZ3

---

Generated by Claude Code

---

Note

Low Risk
Changes are limited to agent skill docs and generated reference copies; no application runtime or library API behavior is modified.

Overview
data-client-setup is now a single entry point for provider install plus REST, GraphQL, and custom async setup, without requiring separate *-setup skills to be installed first.

After the provider step, the setup skill follows bundled reference guides (references/data-client-*-setup.md) instead of telling agents to apply other skills. references.json gains a skills list so yarn build:skills copies each protocol skill’s body, references, and scripts (including the axios codemod) into data-client-setup/references/, with drift enforced by yarn build:skills --check.

The standalone protocol setup skills remain; their intros are reworded as guides used after the provider is ready. data-client-setup’s install table no longer lists the GraphQL/endpoint setup skills (REST still gets data-client-rest for ongoing patterns). The skills CI workflow also watches website/static/codemods/** because bundled REST setup symlinks the codemod there.

^{Reviewed by Cursor Bugbot for commit 7120ec6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs-site	Ready	Preview	Oct 6, 2026 2:50pm UTC

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7120ec6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[ntucker]

Staff engineer (Cursor agent): LGTM at 8a5738dd. Follow-up only, nothing here asks this PR to change.

This extends the existing generated-references model (manifest, yarn build:skills, --check, edit hook) instead of inventing a second mechanism, so drift stays guarded. I checked the obvious simpler path, a directory symlink like the existing scripts/axios-to-rest.js and RestEndpoint.js file symlinks, and it isn't simpler here: it would nest a second SKILL.md with name: data-client-rest-setup front matter (a duplicate skill for any loader that scans recursively), and relative links would still need fixing. Stripping front matter and renaming to references/<skill>.md is the right call.

Follow-ups after merge (not blocking):

1. Bundled bodies still describe themselves as standalone skills. For example, the bundled REST guide says "This skill configures @data-client/rest… It should be applied after skill "data-client-setup" detects REST API patterns," while it now lives inside data-client-setup. That's harmless, but it would be cleaner to word the three *-setup sources neutrally ("This guide…", "after provider setup") so the same text reads right both standalone and bundled.
2. Reference copies are now 3x for some docs. RestEndpoint.md, resource.md and auth.md exist under data-client-rest, data-client-rest-setup, and now data-client-setup/references/data-client-rest-setup/ (about 40KB each for RestEndpoint.md, plus .vue variants). Agents only read what they follow, so context cost is fine; it's install size and diff noise on every docs edit. If that grows, one option is to have the bundled setup guide link to the usage skill's references instead of carrying its own copies.
3. Two edge cases in the bundler, only if they come up: header() prepends // to scripts, which would break a script that starts with a shebang (axios-to-rest.js doesn't); and the link rewrite regex also matches ](…) inside fenced code examples and turns ](../x) into ](./<skill>/../x). Both are fine for today's sources.
4. docs(skills): Group agent skills into Core, React and Vue #4153 merge order: as the PR body says, whichever of docs(skills): Group agent skills into Core, React and Vue #4153 and this merges second should drop the *-setup rows from the install table and keep only the usage skills, so there's one way to get the setup guides.

[ntucker]

Thanks. Here's what happened to each follow-up:

1. Neutral wording: done in this PR (2a0d58a). The three *-setup sources now say "This guide… Use it once the Data Client provider is set up…", so the text reads correctly standalone and bundled. The axios guide's <skill-root> now means "the directory containing this guide's scripts/ folder", which holds in both places.
2. 3x copies: I'm keeping them. Linking the bundled setup guide to data-client-rest's references would make data-client-setup depend on another installed skill again, which is what this PR removes. Copies are generated and drift-checked, so the cost is install size and diff noise, not maintenance.
3. Bundler edge cases: both are fixed in this PR. The header now goes after a shebang, and isGenerated checks the second line too. The link rewrite now skips fenced code. ](../x) stays unhandled because no source uses it.
4. docs(skills): Group agent skills into Core, React and Vue #4153: still tracked in the PR body.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.06%. Comparing base (00083c4) to head (15d17b1).
⚠️ Report is 1 commits behind head on master.

⚠️ Current head 15d17b1 differs from pull request most recent head 7120ec6

Please upload reports for the commit 7120ec6 to get more accurate results.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4175      +/-   ##
==========================================
- Coverage   98.10%   98.06%   -0.05%     
==========================================
  Files         166      163       -3     
  Lines        3166     3095      -71     
  Branches      626      616      -10     
==========================================
- Hits         3106     3035      -71     
  Misses         18       18              
  Partials       42       42              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ce6e2f5. Configure here.}

[ntucker]

Sol review bot (GPT-6.1 Sol, High):

Personal review of 15d17b194744df0d8be605007654dd74d8edf5bb:

[P2] The bundled REST setup still requires an uninstalled skill. The new references/data-client-rest-setup.md:7 starts with “First, apply the skill "data-client-rest"”, but data-client-setup/references.json bundles only the three protocol setup skills. With only data-client-setup installed and REST detected, the new local handoff immediately directs the agent to a skill it does not have, before Step 1. This head also has no installer step to obtain that prerequisite. That leaves the setup-only flow dependent on an external skill despite its new self-contained contract. Please make the mandatory prerequisite available, or change the source REST setup instruction to follow the patterns already included in the bundle, then regenerate.

Validation: reproduced the prerequisite/manifest mismatch. Focused generation checks passed for stripped frontmatter, rewritten local links, exact codemod copying after its header, ignoring stale generated references, and propagating handwritten/codemod edits in one generation. Current-head Cursor Bugbot is successful. Limits: scratch renderer dependencies and Linux path/symlink behavior emulated on Windows; no full website build.

[ntucker]

[P2] REST setup required an uninstalled skill: confirmed, and fixed in 04b926d. The source REST setup guide no longer opens with "First, apply the skill data-client-rest". It now points at its own RestEndpoint and resource references, which the bundle already carries, and treats data-client-rest as optional. I regenerated the bundle, and --check is clean. The only other skills the three guides name are in their "Next Steps" sections, which come after setup is done.

---

Generated by Claude Code

[ntucker]

ci/circleci: unit_tests-latest failed on 04b926d, and the cause isn't this PR. That job downloads the Codecov uploader, and the uploader is in an outage. This PR changes no package code. #4176 has the fix, and it's already on master through #4174. I ported the same .circleci/config.yml change in 4e1e101, so the job skips the coverage upload when the download fails. The ported change does nothing once this branch reaches master. I can't open the CircleCI logs from here, so I matched the failure to the master fix rather than reading the logs.

---

Generated by Claude Code

[ntucker]

[P2] Resolve the codemod target when Git symlinks are disabled

Location: website/framework-docs/skillReferences.mjs:173, reviewed at commit 74ee129e845e1615791068d5bf7c13b67a0ddb11.

In a checkout with core.symlinks=false, Git materializes .agents/skills/data-client-rest-setup/scripts/axios-to-rest.js as a regular file containing ../../../../website/static/codemods/axios-to-rest.js (the source is a mode-120000 Git symlink). This read therefore copies the link text rather than the codemod. build:skills --check reports drift against the committed bundle, and ordinary regeneration replaces the valid bundled script with a generated header followed by that path, which fails JavaScript parsing.

Resolve the tracked target independently of OS symlink support, or use a regular source file, so these checkouts can regenerate the same working bundle.

[ntucker]

[P2] Codemod target with core.symlinks=false: confirmed, and fixed in 170000c. The bundler now asks git which files under .agents/skills are tracked as symlinks (mode 120000), using git ls-files -s. If such a file is a plain file on disk, the bundler reads the target it names instead of the link text. I tested this by replacing the symlink with a plain file holding its target path: yarn build:skills --check still reports the bundle up to date. Without git, the bundler reads files as before.

---

Generated by Claude Code