claude-skill-react

A specialized Claude Code skill toolkit providing modern React.js architecture, hooks patterns, and performance optimization guidelines, plus a structured React code review workflow.

The skills follow the open Agent Skills standard. They work in Claude Code and in other clients that support SKILL.md skills. You can distribute them as a Claude Code plugin, as an npm package with an installer CLI, or through the skills CLI.

What's included

| Skill | Activates | Purpose | | --- | --- | --- | | react-guidelines | Automatically, when Claude writes, refactors, or designs React code | Version-aware rules for architecture, state placement, Effects, hooks, React Compiler, and performance, with decision tables and anti-patterns | | react-review | When you ask for a React review or audit, or directly with /react-review | A step-by-step audit that produces a severity-ranked findings report with stable rule IDs (HOOK-1, PERF-3, …) and concrete fixes |

skills/
├── react-guidelines/
│   ├── SKILL.md                    # core rules, decision tables (always loaded when the skill activates)
│   └── references/                 # loaded on demand to keep context small
│       ├── architecture.md         # structure, components, state, RSC, data fetching, forms, TS, testing
│       ├── hooks.md                # every built-in hook + custom hook design
│       ├── performance.md          # measuring, React Compiler, re-renders, bundles, INP, SSR, <Activity>
│       └── react-19-apis.md        # 19.0–19.3 APIs, version-gated, React 18 migration notes
└── react-review/
    ├── SKILL.md                    # review workflow and report format
    └── references/checklist.md     # ~40 rules across hooks, purity, architecture, security, perf, a11y, TS

The guidance targets React 19.x (up to 19.3) and is written to be version-aware. The skill first checks the installed React version, whether React Compiler is enabled, and the framework, and only then recommends APIs and memoization strategies.

Installation

Pick one channel per scope. Installing both the plugin and the CLI copies gives you duplicate skills (/react-review and /react-toolkit:react-review).

1. Claude Code plugin (recommended for Claude Code)

/plugin install react-toolkit --marketplace SStadelmann/claude-skill-react

On Claude Code versions older than 2.1.275, use two steps:

/plugin marketplace add SStadelmann/claude-skill-react
/plugin install react-toolkit@claude-skill-react

Plugin skills are namespaced. Run the review with /react-toolkit:react-review. Updates arrive through /plugin when the plugin version changes.

2. npm installer CLI (no global install)

npx claude-skill-react install            # personal: ~/.claude/skills (or $CLAUDE_CONFIG_DIR/skills)
npx claude-skill-react install --project  # this repo: ./.claude/skills (commit it to share with your team)
npx claude-skill-react install --dir .agents/skills --skill react-guidelines   # any other skills directory
npx claude-skill-react uninstall          # removes only what it installed
npx claude-skill-react list

The CLI copies plain files and has no dependencies. It writes a small .claude-skill-react.json marker into each skill folder, so it can update or remove its own installs and never overwrite your folders (unless you pass --force). Use --dry-run to preview changes.

3. Pin a version per project with npm + the skills CLI

npm install --save-dev claude-skill-react
npx skills experimental_sync --agent claude-code   # links skills from node_modules into the agent directory

This keeps the skill version in your lockfile, so the whole team uses the same guidelines.

4. Directly from GitHub with the skills CLI

npx skills add SStadelmann/claude-skill-react            # interactive: choose agents and skills
npx skills add SStadelmann/claude-skill-react --list     # just list the skills

5. Your own marketplace, sourced from npm

Teams that run their own Claude Code marketplace can reference the published npm package. Claude Code fetches it without running install scripts:

{
  "name": "react-toolkit",
  "source": { "source": "npm", "package": "claude-skill-react", "version": "^1.0.0" }
}

Usage

The guidelines load automatically. Ask Claude to build or change React code as usual:

Add a debounced search box to the product list
Why does typing in this form lag?
Refactor ProfilePage to use Server Components where possible

Ask for a review explicitly, optionally with a scope:

/react-review src/features/checkout
Review my staged React changes

The review reports findings by severity, cites rule IDs and file:line, and asks before it applies any fixes.

Development

Requirements: Node.js 20 or later. There are no dependencies to install.

npm test              # node:test suites for the validator and CLI
npm run validate      # Agent Skills spec + manifest consistency checks
npm pack --dry-run    # inspect the published file list

npm run validate enforces the following:

• The frontmatter uses only Agent Skills spec fields (name, description, license, compatibility, metadata, allowed-tools), so the skills stay portable across clients. Claude Code-only fields such as context or disable-model-invocation are rejected.
• name is kebab-case, at most 64 characters, and matches the folder name. description is at most 1024 characters and says when to use the skill.
• The frontmatter is YAML that every parser reads the same way (no unquoted : , block scalars, or lists).
• The SKILL.md body is under 500 lines and about 5k tokens. All relative links resolve inside the skill, and every reference file is linked.
• package.json and .claude-plugin/plugin.json versions match, the marketplace lists the plugin, and the published files exist.

With Claude Code installed, you can also run claude plugin validate . to check the plugin and marketplace manifests.

Authoring guidelines

• Keep SKILL.md short and decision-oriented. Put depth into references/*.md and link it from SKILL.md with a "read when" hint.
• Gate every API by React version, and verify new claims against react.dev and the React changelog.
• Prefer rules that change agent behavior (what to do instead) over general explanations that the model already knows.

Releasing

npm version minor         # bumps package.json and syncs .claude-plugin/plugin.json (via the "version" script)
git push --follow-tags    # the v* tag triggers .github/workflows/publish.yml

The publish workflow runs validation and tests, checks that the tag matches the package version, and publishes with npm trusted publishing (OIDC, with automatic provenance). Configure the trusted publisher for this repository and the publish.yml workflow on npmjs.com. Alternatively, add an NPM_TOKEN repository secret. For a manual release, run npm publish (prepublishOnly runs validation and tests first).

Plugin users get updates when plugin.json's version changes on the default branch. npm and skills CLI users get them when they update the package.

License

MIT