docs: reframe agent docs around skills-first, align CLI and plugin docs with 1.0.0#822
Conversation
…l matrix Adds the install-script tab to the CLI install matrix, rewrites the description of `arcjet skills` and `arcjet skills install` to reflect that they are breadcrumbs pointing at `npx skills add arcjet/skills` rather than file-writers, and renames the plugin's skills table to use the canonical `add-request-protection` and `add-guard-protection` names (with a note that the previous names remain as deprecated aliases). Cross-references arcjet/skills (https://github.com/arcjet/skills) as the source of canonical skills. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![arcjet-review[bot]](https://avatars.githubusercontent.com/u/24397786?s=60&v=4){kind=small}
There was a problem hiding this comment.
Arcjet Review — 🟢 Low Risk
Decision: Approved
Rationale: Documentation-only changes to two MDX files (CLI docs and Arcjet plugin docs). No source code, dependencies, infra, or auth logic touched. No secrets introduced. The diff updates skill names to canonical 1.0.0 names (add-request-protection, add-guard-protection), notes deprecated aliases, and adds an install-script tab plus refined behavior descriptions for arcjet skills subcommands. Changes are internally consistent across both files.
Summary of Changes
Aligns CLI and Arcjet plugin documentation with the 1.0.0 canonical skill names (add-request-protection, add-guard-protection), notes that the legacy names (protect-route, add-ai-protection) remain as deprecated aliases, points at the standalone arcjet/skills package as the source of truth, adds an install-script install option to the CLI install matrix, and clarifies that arcjet skills / arcjet skills install are now breadcrumbs that print a pointer to npx skills add arcjet/skills rather than file-writers.
Notes
Docs-only PR, ~35 changed lines, well under the 1000-line size threshold. Security-review skill checklist applied: no auth, injection, secrets, crypto, or data-protection surface touched. The only security-adjacent item is documenting a curl | bash install flow, which is conventional but worth a non-blocking inline question.
Review: 3ee4df7a | Powered by Arcjet Review
For the 1.0.0 initial public release there's no legacy `arcjet skills` behavior to clarify. Drop the `arcjet skills`/`install`/`initialize` rows from the command table and the breadcrumb paragraphs from the Skills section — `npx skills add arcjet/skills` is the canonical entry point for skill installation. Tighten the plugin skills table per review feedback (id 3164916672) so the separator row isn't ~200 chars wide.
…ugin Lead with `npx skills add arcjet/skills` as the canonical entry path per the 1.0.0 framing: skills are the primary agent-facing surface, CLI and MCP are support transports, the plugin is an alternative for users who prefer it. Drop the duplicated MCP client setup block, collapse redundant Tabs, add cross-links between the four pages, and align the agent-get-started CLI install on `npx`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
arcjet-rei
changed the title
|
@qw-in @davidmytton this set of changes reflects our conversation on Tuesday, but it's a dramatic enough reshaping of the agent-based workflow documentation that one or both of you should put eyes on it before we ship it. |
2 participants
Summary
Restructures the four agent-facing documentation pages around a new framing decision: skills (
arcjet/skills) are the preferred entry path for agentic workflows; the CLI and MCP server are support transports for connecting skills to the Arcjet API; the plugin is an alternative for users who prefer a bundled experience and is not the recommended first step.This PR also ships the original 1.0.0 alignment work — canonical skill names, install matrix updates, and removal of the deprecated
arcjet skillssubcommand documentation.What changed
agent-get-started.mdx— restructured around skills as the lead.npx skills add arcjet/skills) → connect via CLI or MCP (parallel support paths) → install SDK → add protection → verify.npx -y @arcjet/cli@latest(matches the canonical install order incli.mdx)./mcp-server#setup) replaced with a single link.ARCJET_ENVis consumed by the SDK in the user's app (not the MCP connection itself), and dropped it from the CLI bootstrap path since the CLI does not read it.cli.mdx— reframed as "one of two transports" alongside MCP.## Skillssection was replaced with a one-line pointer to/agent-get-started#skills. Skills aren't a CLI surface, so they belong on the canonical entry-point page, not duplicated here.npx, then npm, Homebrew, install script, release binary.arcjet skills/arcjet skills install/arcjet skills initializerows from the command reference table. For 1.0.0 (the initial public release) the canonical entry point isnpx skills add arcjet/skills, not a CLI subcommand.mcp-server.mdx— added a## See alsosection linking to/agent-get-started,/cli, and/arcjet-plugin(the page was previously an island). Collapsed the duplicate capabilities/tools listings into one canonical## Available toolsblock.arcjet-plugin.mdx— added a top-of-page<Aside>framing the plugin as an alternative for Claude Code and Cursor users who prefer a bundled experience, with the recommended path pointing at/agent-get-started. Collapsed the two identical install Tabs into one block. Renamed the plugin's slash commands to the canonical names —/arcjet:add-request-protection(HTTP routes) and/arcjet:add-guard-protection(non-HTTP code paths) — with a note that/arcjet:protect-routeand/arcjet:add-ai-protectionremain as deprecated aliases that emit a diagnostic. Added a## Using the plugin with the CLIsection and a## See alsoblock.Companion PRs
The skills-canonical-names migration ships in parallel against
arcjet/arcjet-plugin. Thearcjet skillsno-op behavior is already in thearcjet/arcjetmonorepo (arcjet-decide/internal/cli/skills.go).