adjusted ai agents skills docs

[LinoGiger]

No description provided.

[claude]

Code Review — PR #528: adjusted ai agents skills docs

This PR consolidates the Claude Code-specific docs into a broader multi-agent page and removes the migration guide. The direction is sound, but there are a few issues worth addressing before merging.

---

Issues

1. Migration guide deletion is unrelated to the PR goal (potential breaking change for users)

docs/migration_guide.md is being deleted alongside the Claude Code docs, but it covers a completely separate topic: migrating from the legacy Order API to the Audience & Job API. Users who are still on the old client.order.* / client.validation.* APIs will have no documentation path to follow. If the migration guide content is outdated or no longer needed (e.g., the legacy API has been removed), that should be stated explicitly. If it's still relevant, consider keeping it or folding its content into an existing doc rather than silently dropping it.

2. Claude Code command syntax changed without verification

Old claude_code.md:

/plugin marketplace add rapidataAI/skills
/plugin install rapidata-sdk-plugin@rapidata-sdk-marketplace

New ai_agents.md:

claude plugin marketplace add RapidataAI/skills && claude plugin install rapidata-sdk-plugin@rapidata-sdk-marketplace

These are different execution contexts. The old format used Claude Code slash commands (typed inside a Claude Code session), while the new format uses shell CLI invocations. Please verify the new commands actually work as written — a user following the doc should be able to copy-paste them into a terminal, not a Claude Code prompt.

3. "40+ more" claim is unsubstantiated

quickstart.md line 178: "...Claude Code, Cursor, Copilot, and 40+ more". The table in ai_agents.md lists 7 agents. Either the claim needs substantiation (the npx skills add tool supports that many targets) or it should be softened to something like "and more" or "many others".

4. Missing content from the old claude_code.md

Two sections didn't carry over to ai_agents.md:

• Keeping the plugin up to date (the claude plugin marketplace update workflow)
• Adding the plugin to a project (the .claude/settings.json config for sharing with team contributors)

The second one in particular is useful for teams — it lets contributors get prompted to install the marketplace automatically. Consider adding an equivalent section or footnote in ai_agents.md.

5. Minor: casing inconsistency

Old docs: rapidataAI/skills
New docs: RapidataAI/skills

GitHub org names are case-insensitive so this is harmless, but the new version (RapidataAI) matches the actual org casing and is the right one to use consistently.

---

Summary

Finding	Severity
Migration guide silently deleted	Medium — existing users lose upgrade path
Claude Code command syntax change unverified	Medium — could break for users following docs
"40+ more" unsupported claim	Low — marketing copy, but should be accurate
Missing update/project sections	Low — nice-to-have
Casing inconsistency	Trivial

The consolidation from agent-specific to multi-agent docs is a good improvement. The migration guide removal feels like a separate, unintentional deletion — worth double-checking whether it was intentional.

[claude]

PR Review: adjusted ai agents skills docs

Overall this is a sensible direction — consolidating from a Claude-Code-only page into a multi-agent page makes sense as the skill broadens its reach. A few issues worth addressing before merge:

---

Issues

1. Inconsistent Claude Code interface in the same file

The install table uses CLI syntax:

claude plugin marketplace add RapidataAI/skills && claude plugin install rapidata-sdk-plugin@rapidata-sdk-marketplace

But the "Keeping the skill up to date" section uses slash-command syntax:

/plugin marketplace update

These are different interfaces (terminal vs. in-app command). Pick one and stay consistent, or at minimum explain the distinction. If the install is done via CLI, the update should also show a CLI equivalent alongside the slash command.

2. RapidataAI/skills case differs from the old doc

The deleted claude_code.md used rapidataAI/skills (lowercase r). The new file uses RapidataAI/skills (uppercase R). GitHub org/repo names are case-insensitive in redirects, but it's worth confirming which casing is canonical to avoid confusion.

3. Migration guide deleted without replacement

migration_guide.md (112 lines) documented how to move from the legacy client.order.* / client.validation.* API to the recommended Audience & Job API. That content is now gone with no redirect or successor. Users on the legacy API hitting this from external links or search results will find a 404. Consider either:

• Preserving the guide under a different nav location, or
• Appending a short "Legacy API" note to quickstart.md or api.md

This deletion also feels unrelated to the stated goal of the PR (expanding AI agent coverage). Worth splitting into a separate PR if intentional.

4. "Any other" install command is underspecified

npx skills add RapidataAI/skills

Without -a <agent>, it's unclear what this does for arbitrary agents. A brief note on what output to expect (e.g., "outputs a SKILL.md you can drop into your agent's context") would prevent confusion.

5. Dropped content from claude_code.md

The deleted file included two sections that had real value and aren't in the new file:

• "What the plugin provides" — explicit list of SDK capabilities (classification, comparison, ranking, audiences, flows, MRI, settings, error handling). Useful for users evaluating whether to install.
• "Adding the plugin to your project" — the .claude/settings.json snippet for teams who want the skill auto-loaded for all contributors.

The second one in particular is not obvious to find elsewhere. Worth porting to the new file.

---

Minor

• The quickstart.md link text ("Let your AI agent write the integration code for you — one-line install...") is marketing copy rather than a navigation label. Shorter and more neutral would fit better alongside the other links on that page.

[claude]

test

[claude]

PR Review: adjusted ai agents skills docs

Summary

This PR replaces the Claude Code-specific plugin doc and migration guide with a new multi-agent ai_agents.md. The intent is sound - broadening support beyond Claude Code - but there are a few issues worth addressing.

---

Issues

1. Migration guide removed with no replacement

docs/migration_guide.md (112 lines of side-by-side Order vs Audience/Job API comparisons) is deleted entirely with no redirect or replacement. Users still on the legacy Orders API will lose this guidance. The quickstart.md link that previously pointed to the migration guide now points to the AI agents doc instead, silently discarding migration content.

Consider keeping the migration guide, or moving its content elsewhere (e.g. a condensed section in the quickstart). At minimum, confirm the removal is intentional.

2. Claude Code install command inconsistency

The new doc shows a CLI invocation:

claude plugin marketplace add RapidataAI/skills && claude plugin install rapidata-sdk-plugin@rapidata-sdk-marketplace

The old claude_code.md used slash commands inside the editor:

/plugin marketplace add rapidataAI/skills
/plugin install rapidata-sdk-plugin@rapidata-sdk-marketplace

Two differences to resolve:

• Casing: RapidataAI (new) vs rapidataAI (old) - which is correct for the GitHub repo path?
• Command format: claude plugin as a shell CLI command vs /plugin as an in-editor slash command - these are different invocation contexts. Please verify which Claude Code actually supports.

3. Lost content: project-level plugin setup

The old claude_code.md had a section explaining how to share the plugin across a team via .claude/settings.json. That content is entirely absent from the new doc. This is useful for teams adopting Rapidata and should be preserved somewhere.

4. Tone

Per the CLAUDE.md guidelines, docs should not fall into hyperbole. A few lines read as marketing copy:

• "One command. Done."
• "Install once. Works in every session after that. That's it."

Fine for a landing page, but out of place in technical documentation. A plain description would be more appropriate.

---

Minor

• The collapsible note for the raw SKILL.md URL is a nice touch.
• The install table is clean and readable.
• Flattening the nav from Resources > Claude Code / Migration Guide to a single AI Agents entry is a reasonable simplification.

---

Verdict

Good direction overall. Suggested follow-ups:

1. Restore or redirect the migration guide content (or explicitly confirm it is intentionally dropped)
2. Verify and fix the Claude Code command format and repo casing
3. Re-add the project-level plugin setup instructions
4. Soften the marketing-style language in the install section