feat(agents): ship the agent skill in the SDK and hint once per session

[RapidPoseidon]

This PR makes the SDK the single source of truth for the Rapidata agent skill. The full skill now lives in src/rapidata/_skill/, is edited only in this repo, and ships in every wheel. RapidataAI/skills becomes a short stub that tells agents to run python -m rapidata skill (RapidataAI/skills#14).

Follow-up to #904 and #909. This replaces #911's earlier design, which fetched the skill live from GitHub and checked freshness by content hash.

The skill moves into the SDK

• src/rapidata/_skill/ now holds SKILL.md, reference.md, examples.md and flows-for-preference-data.md, copied from RapidataAI/skills main (SDK v3.25.9 content).
• The "check the skill is up to date" pin section is replaced by one paragraph: the bundled guide always matches the installed SDK.
• Links to the companion files and to raw.githubusercontent.com are replaced by commands such as python -m rapidata skill reference.

Command

• python -m rapidata skill [main|reference|examples|flows-for-preference-data] prints the bundled copy. It uses no network.
• The new console script [project.scripts] rapidata = "rapidata.__main__:main" makes plain rapidata skill work too.
• --install writes the main guide for the chosen --agent, and records the SDK version in two places:
  • The front matter gets metadata: { rapidata-sdk-version: "<version>" }. The import hint reads it from there, and only from there.
  • The copy opens with a check that tells the agent to compare that version with rapidata.__version__ and to run the exact --install command on a mismatch. An agent that loads the installed skill without importing the SDK still catches the drift.
• rapidata skill | head no longer raises BrokenPipeError.

Import hint

• The hint shows once per agent session, keyed by CLAUDE_CODE_SESSION_ID / CODEX_THREAD_ID / CODEX_SESSION_ID.
• Anonymous reads expire after 12h. State is kept in ~/.config/rapidata/agent-state.json, with a temp-dir fallback.
• The hint stays silent when this session already read the main guide, or when an --installed copy carries the current version. The Claude Code plugin check is gone: the plugin only tells the agent to run python -m rapidata skill.
• A copy stamped with another version gets …installed by rapidata X, but Y is installed. Update it with: python -m rapidata skill --install […]. This is a plain string compare against rapidata.__version__, with no network.
• The hint keeps feat(agents): guide coding agents through login #909's status / login lines.
• RAPIDATA_AGENT_HINT=0 is still the only override, and it is documented in docs/ai_agents.md, not in the hint.
• The hint is also silent while the rapidata console script itself runs.

Removed from the earlier #911

• The live GitHub fetch and record_live_skill.
• The sha256 stamp.
• The daily freshness check with its 1s timeout.
• Content-based detection of installed copies: only a version stamp counts now.
• The "Refresh bundled agent skill" step in release_and_publish.yml.
• The release's sdk-release dispatch to RapidataAI/skills, which now carries a static pointer and no longer syncs on releases. The dispatch token is scoped to rapidata-mcp only.

New Agent Skill check (.github/workflows/agent-skill.yml + .github/scripts/agent-skill-check.js, modelled on rapidata-backend's openapi-diff.yml)

• The status is success when the PR touches src/rapidata/_skill/. That covers SKILL.md and, deliberately, the companion guides next to it.
• Otherwise it fails until a reviewer applies skill-unchanged-approved. The label now exists in this repo.
• labeled / unlabeled re-evaluate the status in a separate ack job. synchronize strips the label.
• A sticky comment explains both options. It is only posted when action is needed.
• Exempt:
  • PRs touching only openapi/**, src/rapidata/api_client/** and src/rapidata/api_client_README.md. This is a superset of automerge-openapi-client.yml's Guard 2, so the daily generator PR stays green.
  • PRs touching only pyproject.toml / src/rapidata/__init__.py whose commits are all Bump version from X to Y.
• ⚠ To gate merges, Agent Skill still has to be added as a required status in branch protection. I can't change that setting.

Docs

• Contributor instructions move from CLAUDE.md to a root AGENTS.md, so Codex and Cursor read them too. CLAUDE.md is now @AGENTS.md. A new "Agent skill" section asks for a review of src/rapidata/_skill/ with every change. When no update is needed, the PR body should say so, so the reviewer can apply skill-unchanged-approved.
• docs/ai_agents.md no longer mentions the plugin / npx skills install. It starts from pip install -U rapidata and rapidata skill / --install.
• README.md, docs/ai_agents.md, src/rapidata/AGENTS.md and the module docstrings now point at rapidata skill / python -m rapidata skill.
• They name src/rapidata/_skill/ as the place to edit the skill.
• Links to the raw SKILL.md in RapidataAI/skills are dropped.

Rollout order: SDK versions ≤ 3.25.9 fetch SKILL.md from RapidataAI/skills main at runtime. The stub PR stays a draft until a release containing this PR is on PyPI.

Verified

• uv run --frozen python -m pytest -q: 324 passed.
• black has been run on the changed files.
• pyright 1.1.396: 0 errors on src/rapidata/rapidata_client, __main__.py, _agent_hint.py, __init__.py and the changed tests.
• uv build: the wheel contains rapidata/_skill/{SKILL,reference,examples,flows-for-preference-data}.md and the rapidata console script.
• Fresh venv from that wheel, with a fresh HOME:
  1. rapidata skill prints the 930-line guide, and rapidata skill reference prints the reference.
  2. New session s1 is hinted on import.
  3. After s1 runs rapidata skill, it is not hinted again.
  4. After --install, the front matter carries rapidata-sdk-version: "3.25.9" and the copy opens with the version check. A new session is silent.
  5. With the front-matter version edited to 3.25.5, the import prints the reinstall hint naming the file.
• Agent Skill on this PR: success, "Agent skill updated in this PR."
• Label path, live on this PR: I applied and then removed skill-unchanged-approved. Each event ran the Acknowledge label change job, and both runs succeeded. The status stayed success because SKILL.md changed.
• Failure and exemption paths: the script was run against a mocked GitHub API in 10 scenarios, all passing:
  • untouched → failure plus comment
  • labeled → success, comment says confirmed
  • new commit → label stripped, failure
  • unlabeled → failure
  • generator-only → success
  • generator plus a hand edit → failure
  • version bump → success
  • non-bump pyproject.toml edit → failure
  • companion guide edit → success

🔗 Session: https://poseidon.rapidata.internal/chat/node-844bac89

🤖 Generated with Claude Code