Skip to content

Commit 0c2de5b

Browse files
piotrskipiotrski
authored
Add Claude Code skill and plugin marketplace (#12)
* feat: add Claude Code skill and plugin marketplace Add a react-devtools skill that teaches AI coding assistants when and how to use agent-react-devtools. The skill auto-activates when users ask about React debugging, component inspection, or render performance. - skills/react-devtools/SKILL.md with trigger description, command reference, output format docs, and common patterns - Reference docs: commands.md, profiling-guide.md, setup.md - .claude-plugin/marketplace.json for plugin distribution - Include skills/ in npm package files Closes #11 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add AI coding assistant setup instructions to README Replace the manual CLAUDE.md section with three installation tiers: - npx skills add (works across Claude Code, Cursor, Codex, etc.) - /plugin marketplace add for Claude Code native install - Manual CLAUDE.md setup as fallback
1 parent 0caec54 commit 0c2de5b

File tree

8 files changed

+479
-2
lines changed

8 files changed

+479
-2
lines changed

‎.changeset/claude-code-skill.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"agent-react-devtools": patch
3+
---
4+
5+
Add Claude Code skill and plugin marketplace metadata

‎.claude-plugin/marketplace.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
3+
"name": "piotrski",
4+
"owner": {
5+
"name": "Piotr Tomczewski",
6+
"email": "piotr@tomczewski.dev"
7+
},
8+
"metadata": {
9+
"description": "React DevTools for AI agents — inspect components, profile renders, debug performance"
10+
},
11+
"plugins": [
12+
{
13+
"name": "agent-react-devtools",
14+
"description": "Inspect React component trees, read props/state/hooks, and profile render performance from the terminal",
15+
"source": "./packages/agent-react-devtools",
16+
"strict": false,
17+
"category": "development"
18+
}
19+
]
20+
}

‎README.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -198,9 +198,28 @@ For Expo, the connection works automatically with the Expo dev client.
198198

199199
To use a custom port, set the `REACT_DEVTOOLS_PORT` environment variable.
200200

201-
## Using with AI Agents
201+
## Using with AI Coding Assistants
202202

203-
Add something like this to your project's `CLAUDE.md` (or equivalent agent instructions):
203+
Add the skill to your AI coding assistant for richer context:
204+
205+
```sh
206+
npx skills add piotrski/agent-react-devtools
207+
```
208+
209+
This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.
210+
211+
### Claude Code plugin
212+
213+
You can also install via the Claude Code plugin marketplace:
214+
215+
```
216+
/plugin marketplace add piotrski/agent-react-devtools
217+
/plugin install agent-react-devtools@piotrski
218+
```
219+
220+
### Manual setup
221+
222+
Alternatively, add something like this to your project's `CLAUDE.md` (or equivalent agent instructions):
204223

205224
```markdown
206225
## React Debugging

‎packages/agent-react-devtools/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
},
2020
"files": [
2121
"dist",
22+
"skills",
2223
"README.md",
2324
"CHANGELOG.md"
2425
],

‎packages/agent-react-devtools/skills/react-devtools/SKILL.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
name: react-devtools
3+
description: React DevTools CLI for AI agents. Use when the user asks you to debug a React or React Native app at runtime, inspect component props/state/hooks, diagnose render performance, profile re-renders, find slow components, or understand why something re-renders. Triggers include "why does this re-render", "inspect the component", "what props does X have", "profile the app", "find slow components", "debug the UI", "check component state", "the app feels slow", or any React runtime debugging task.
4+
allowed-tools: Bash(agent-react-devtools:*)
5+
---
6+
7+
# agent-react-devtools
8+
9+
CLI that connects to a running React or React Native app via the React DevTools protocol and exposes the component tree, props, state, hooks, and profiling data in a token-efficient format.
10+
11+
## Core Workflow
12+
13+
1. **Ensure connection** — check `agent-react-devtools status`. If the daemon is not running, start it with `agent-react-devtools start`.
14+
2. **Inspect** — get the component tree, search for components, inspect props/state/hooks.
15+
3. **Profile** — start profiling, trigger the interaction (or ask the user to), stop profiling, analyze results.
16+
4. **Act** — use the data to fix the bug, optimize performance, or explain what's happening.
17+
18+
## Essential Commands
19+
20+
### Daemon
21+
22+
```bash
23+
agent-react-devtools start # Start daemon (auto-starts on first command)
24+
agent-react-devtools stop # Stop daemon
25+
agent-react-devtools status # Check connection: port, connected apps, component count
26+
```
27+
28+
### Component Inspection
29+
30+
```bash
31+
agent-react-devtools get tree # Full component hierarchy (labels: @c1, @c2, ...)
32+
agent-react-devtools get tree --depth 3 # Limit depth
33+
agent-react-devtools get component @c5 # Props, state, hooks for a specific component
34+
agent-react-devtools find Button # Search by display name (fuzzy)
35+
agent-react-devtools find Button --exact # Exact match
36+
agent-react-devtools count # Count by type: fn, cls, host, memo, ...
37+
```
38+
39+
### Performance Profiling
40+
41+
```bash
42+
agent-react-devtools profile start # Start recording
43+
agent-react-devtools profile stop # Stop and collect data
44+
agent-react-devtools profile slow # Slowest components by avg render time
45+
agent-react-devtools profile slow --limit 10 # Top 10
46+
agent-react-devtools profile rerenders # Most re-rendered components
47+
agent-react-devtools profile report @c5 # Detailed report for one component
48+
agent-react-devtools profile timeline # Chronological commit list
49+
agent-react-devtools profile commit 3 # Detail for commit #3
50+
```
51+
52+
## Understanding the Output
53+
54+
### Component Labels
55+
56+
Every component gets a stable label like `@c1`, `@c2`. Use these to reference components in follow-up commands:
57+
58+
```
59+
@c1 [fn] "App"
60+
├─ @c2 [fn] "Header"
61+
├─ @c3 [fn] "TodoList"
62+
│ ├─ @c4 [fn] "TodoItem" key="1"
63+
│ └─ @c5 [fn] "TodoItem" key="2"
64+
└─ @c6 [host] "div"
65+
```
66+
67+
Type abbreviations: `fn` = function, `cls` = class, `host` = DOM element, `memo` = React.memo, `fRef` = forwardRef, `susp` = Suspense, `ctx` = context.
68+
69+
### Inspected Component
70+
71+
```
72+
@c3 [fn] "TodoList"
73+
props:
74+
items: [{"id":1,"text":"Buy milk"},{"id":2,"text":"Walk dog"}]
75+
onDelete: ƒ
76+
state:
77+
filter: "all"
78+
hooks:
79+
useState: "all"
80+
useMemo: [...]
81+
useCallback: ƒ
82+
```
83+
84+
`ƒ` = function value. Values over 60 chars are truncated.
85+
86+
### Profiling Output
87+
88+
```
89+
Slowest (by avg render time):
90+
ExpensiveList avg:12.3ms max:18.1ms renders:47 cause:props-changed
91+
TodoItem avg:2.1ms max:5.0ms renders:94 cause:parent-rendered
92+
```
93+
94+
Render causes: `props-changed`, `state-changed`, `hooks-changed`, `parent-rendered`, `force-update`, `first-mount`.
95+
96+
## Common Patterns
97+
98+
### Diagnose slow interactions
99+
100+
```bash
101+
agent-react-devtools profile start
102+
# User interacts with the app (or use agent-browser to drive the UI)
103+
agent-react-devtools profile stop
104+
agent-react-devtools profile slow --limit 5
105+
agent-react-devtools profile rerenders --limit 5
106+
```
107+
108+
Then inspect the worst offenders with `get component @cN` and `profile report @cN`.
109+
110+
### Find a component and check its state
111+
112+
```bash
113+
agent-react-devtools find SearchBar
114+
agent-react-devtools get component @c12
115+
```
116+
117+
### Verify a fix worked
118+
119+
```bash
120+
agent-react-devtools profile start
121+
# Repeat the interaction
122+
agent-react-devtools profile stop
123+
agent-react-devtools profile slow --limit 5
124+
# Compare render counts and durations to the previous run
125+
```
126+
127+
## Important Rules
128+
129+
- **Labels reset** when the app reloads or components unmount/remount. Always re-check with `get tree` or `find` after a page reload.
130+
- **`status` first** — if status shows 0 connected apps, the React app is not connected. The user may need to run `npx agent-react-devtools init` in their project first.
131+
- **Profile while interacting** — profiling only captures renders that happen between `profile start` and `profile stop`. Make sure the relevant interaction happens during that window.
132+
- **Use `--depth`** on large trees — a deep tree can produce a lot of output. Start with `--depth 3` or `--depth 4` and go deeper only on the subtree you care about.
133+
134+
## References
135+
136+
| File | When to read |
137+
|------|-------------|
138+
| [commands.md](references/commands.md) | Full command reference with all flags and edge cases |
139+
| [profiling-guide.md](references/profiling-guide.md) | Step-by-step profiling workflows and interpreting results |
140+
| [setup.md](references/setup.md) | How to connect different frameworks (Vite, Next.js, Expo, CRA) |

‎packages/agent-react-devtools/skills/react-devtools/references/commands.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Command Reference
2+
3+
## Daemon Management
4+
5+
### `agent-react-devtools start [--port N]`
6+
Start the background daemon. Default port: 8097. The daemon listens for WebSocket connections from React apps and IPC connections from the CLI. Auto-starts when you run any other command, so you rarely need this explicitly.
7+
8+
### `agent-react-devtools stop`
9+
Stop the daemon process. All connection state is lost.
10+
11+
### `agent-react-devtools status`
12+
Show daemon status: port, connected apps, component count, profiling state, uptime.
13+
14+
Output:
15+
```
16+
Daemon: running (port 8097)
17+
Apps: 1 connected, 42 components
18+
Uptime: 120s
19+
```
20+
21+
If profiling is active, shows `Profiling: active`.
22+
23+
## Component Inspection
24+
25+
### `agent-react-devtools get tree [--depth N]`
26+
Print the component hierarchy as an indented tree. Each node shows:
27+
- Label (`@c1`, `@c2`, ...) — stable within a session, resets on app reload
28+
- Type tag (`fn`, `cls`, `host`, `memo`, `fRef`, `susp`, `ctx`)
29+
- Display name
30+
- Key (if present)
31+
32+
Use `--depth N` to limit tree depth. Recommended for large apps.
33+
34+
### `agent-react-devtools get component <@cN | id>`
35+
Inspect a single component. Shows:
36+
- **props** — all prop values (functions shown as `ƒ`, long values truncated at 60 chars)
37+
- **state** — state values (class components and useState)
38+
- **hooks** — all hooks with current values and sub-hooks
39+
40+
Accepts a label (`@c5`) or numeric React fiber ID.
41+
42+
### `agent-react-devtools find <name> [--exact]`
43+
Search components by display name. Default is case-insensitive substring match. Use `--exact` for exact match.
44+
45+
Returns a flat list of matching components with labels, types, and keys.
46+
47+
### `agent-react-devtools count`
48+
Count components by type. Output: `42 components (fn:25 host:12 memo:3 cls:2)`.
49+
50+
## Profiling
51+
52+
### `agent-react-devtools profile start [name]`
53+
Start a profiling session. Optional name for identification. Only one session can be active at a time.
54+
55+
### `agent-react-devtools profile stop`
56+
Stop profiling and collect data from React. Shows a summary with duration, commit count, and top rendered components.
57+
58+
### `agent-react-devtools profile slow [--limit N]`
59+
Rank components by average render duration (slowest first). Default limit: 10.
60+
61+
Output columns: component name, avg duration, max duration, render count, primary cause.
62+
63+
### `agent-react-devtools profile rerenders [--limit N]`
64+
Rank components by render count (most re-renders first). Default limit: 10.
65+
66+
Output columns: component name, render count, primary cause.
67+
68+
### `agent-react-devtools profile report <@cN | id>`
69+
Detailed render report for a single component: render count, avg/max/total duration, all render causes.
70+
71+
### `agent-react-devtools profile timeline [--limit N]`
72+
Chronological list of React commits during the profiling session. Each entry: index, duration, component count.
73+
74+
### `agent-react-devtools profile commit <N | #N> [--limit N]`
75+
Detail for a specific commit by index. Shows per-component self/total duration and render causes.
76+
77+
## Setup
78+
79+
### `agent-react-devtools init [--dry-run]`
80+
Auto-detect the framework in the current directory and configure the devtools connection. Supports Vite, Next.js, CRA, and Expo/React Native.
81+
82+
Use `--dry-run` to preview changes without writing files.

0 commit comments

Comments
 (0)