Skip to content

Commit f9c5975

Browse files
feat: add hybrid /add-extension skill for merging SE-2 extensions
Split extension merging into deterministic (Node.js script) and intelligent (Claude AI) operations. The script handles fetch, copy, and package.json merge, then outputs structured JSON tasks for Claude to process .args.mjs files and resolve file conflicts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent e12009a commit f9c5975

File tree

9 files changed

+1746
-0
lines changed

9 files changed

+1746
-0
lines changed
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.tmp
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# /add-extension - SE-2 Extension Merger (Hybrid)
2+
3+
Claude Code skill for adding Scaffold-ETH-2 extensions to existing projects post-creation.
4+
5+
Uses a **hybrid approach**: a Node.js script handles deterministic operations (fetch, copy, package.json merge), while Claude handles intelligent file merging (.args.mjs processing).
6+
7+
**Requirements:** SE-2 project root, Git, Yarn
8+
9+
## Quick Start
10+
11+
```bash
12+
# In SE-2 project root
13+
/add-extension erc-20
14+
15+
# Preview changes first
16+
/add-extension subgraph --dry-run
17+
18+
# Choose framework explicitly
19+
/add-extension ponder -s hardhat
20+
```
21+
22+
## Options
23+
24+
| Flag | Short | Description |
25+
|------|-------|-------------|
26+
| `--list` | `-L` | List all available extensions with repo info |
27+
| `--dry-run` | `-d` | Preview changes without applying |
28+
| `--verbose` | `-v` | Show detailed error messages |
29+
| `--local <path>` | `-l` | Use local extension repo path |
30+
| `--solidity-framework <name>` | `-s` | Choose hardhat/foundry (only if project has neither) |
31+
32+
## Available Extensions
33+
34+
Fetched dynamically from [create-eth](https://github.com/scaffold-eth/create-eth/blob/main/src/extensions/create-eth-extensions.ts).
35+
36+
Run `/add-extension --list` for current list with repository details.
37+
38+
## How It Works
39+
40+
1. **Validate** - Checks for SE-2 project (scaffold.config.ts)
41+
2. **Registry** - Fetches extension config from create-eth registry
42+
3. **Fetch** - Clones extension branch via git
43+
4. **Framework** - Auto-detects hardhat/foundry from project
44+
5. **Analyze** - Compares extension files vs project, reads .args.mjs as raw text
45+
6. **Deterministic merge** - Script copies new files, merges package.json, registers workspaces
46+
7. **AI merge** - Script outputs structured JSON tasks; Claude reads target files and applies .args.mjs exports intelligently
47+
48+
### File Handling
49+
50+
| File Type | Handler | Action |
51+
|-----------|---------|--------|
52+
| New files | Script | Copied directly |
53+
| package.json | Script | Auto-merged (deps, scripts) |
54+
| Workspaces | Script | Registered in root package.json |
55+
| `.args.mjs` files | Claude | Reads exports, modifies target files |
56+
| `.template.mjs` files | Claude | Extracts content, writes/merges target |
57+
| File conflicts | Claude | Reads both versions, merges intelligently |
58+
59+
## Architecture
60+
61+
```
62+
SKILL.md - Skill instructions (comprehensive .args.mjs guide)
63+
skill.mjs - CLI entry point, orchestration, JSON output
64+
lib/validator.mjs - SE-2 detection, registry fetching
65+
lib/fetcher.mjs - Git clone / local path handling
66+
lib/analyzer.mjs - File categorization, .args.mjs raw reading
67+
lib/merger.mjs - Deterministic operations (copy, package.json merge)
68+
lib/constants.mjs - Registry URLs, fallback extensions
69+
```
70+
71+
## Development
72+
73+
```bash
74+
# Test locally with dry-run
75+
node .claude/skills/add-extension/skill.mjs erc-20 --dry-run
76+
77+
# Test with local extension repo
78+
/add-extension erc-721 --local ../create-eth-extensions --dry-run
79+
```
80+
81+
## Source Repositories
82+
83+
| Repo | Purpose |
84+
|------|---------|
85+
| [create-eth](https://github.com/scaffold-eth/create-eth) | SE-2 CLI, extension registry |
86+
| [create-eth-extensions](https://github.com/scaffold-eth/create-eth-extensions) | Default extension source (each extension = git branch) |

0 commit comments

Comments
 (0)