feat: add hybrid /add-extension skill for merging SE-2 extensions

[technophile-04]

Summary

• Adds a Claude Code skill (/add-extension) that merges scaffold-eth extensions into existing SE-2 projects post-creation
• Uses a hybrid approach: Node.js script handles deterministic operations (fetch, copy, package.json merge), Claude handles intelligent file merging (.args.mjs processing)
• Replaces the previous add-extension branch approach which re-implemented create-eth's template processing pipeline (~700 lines of template code eliminated)

How to test

1. Run /add-extension erc-20 OR /add-extension add drizzle-neon and ponder in a clean SE-2 project — the script should copy files, merge package.json, then Claude processes the .args.mjs tasks
2. Run node .claude/skills/add-extension/skill.mjs erc-20 --dry-run — should show change summary and AI merge tasks without applying
3. Run node .claude/skills/add-extension/skill.mjs --list — should show all available extensions
4. After full merge, yarn install && yarn next:build should succeed

Architecture

.claude/skills/add-extension/
  SKILL.md           - Comprehensive skill instructions (teaches Claude about .args.mjs)
  skill.mjs          - CLI entry point, orchestration, JSON task output
  README.md          - User-facing documentation
  lib/
    constants.mjs    - Registry URLs, fallback extensions
    validator.mjs    - SE-2 detection, registry fetching
    fetcher.mjs      - Git clone, file discovery
    analyzer.mjs     - File categorization, raw .args.mjs reading with regex
    merger.mjs       - Deterministic operations (copy, package.json merge)

Things to look out for

• Path traversal validation: merger.mjs validates destination paths stay within project root
• Temp file cleanup timing: .args.mjs content and modified file content are inlined into JSON output before temp directory cleanup, so Claude never needs to read temp files
• Registry parsing: Uses regex on raw TypeScript files from create-eth — fragile but has fallback to hardcoded list

Detailed changes

Key design decisions

• .args.mjs files are read as raw text (no import(), no new Function()) — safer and simpler
• Export names parsed with regex (/export\s+const\s+(\w+)\s*=/g), types inferred by peeking at first character
• file_conflict tasks inline the extension file content (survives temp cleanup)
• SKILL.md documents every known export pattern: preContent, extraMenuLinksObjects, configOverrides, fullContentOverride, extraContents, additionalVars, deploymentsLogic, $$expr$$ convention, etc.

What was eliminated vs previous add-extension branch

• lib/templateMerger.mjs (257 lines) — fetched templates from GitHub, executed with new Function()
• lib/templateUtils.mjs (137 lines) — path inference, diff generation, dynamic import
• lib/extensionTracker.mjs (44 lines) — parsed withDefaults calls from remote templates
• lib/create-eth-utils/utils.js (265 lines) — vendored create-eth utilities with @fastify/deepmerge
• @fastify/deepmerge dependency (no longer needed)

Review fixes applied

• Inlined file_conflict extension content into JSON (was pointing to deleted temp files)
• Added path traversal validation in copyFile
• Added bounds checking for --local and --solidity-framework CLI flags
• Removed dead --yes flag
• Fixed showHelp to call getExtensionsRegistry() directly instead of validateExtensionName('_dummy_')
• Added numeric type detection in inferExportType
• Expanded SKILL.md with detailed merge strategies and missing-file handling

🤖 Generated with Claude Code

[rin-st]

This is great Shiv! 1.7k+ lines of clean code, it's a joy to read it!

Review fixes applied

• Inlined file_conflict extension content into JSON (was pointing to deleted temp files)
• Added path traversal validation in copyFile
• Added bounds checking for --local and --solidity-framework CLI flags
• Removed dead --yes flag
• Fixed showHelp to call getExtensionsRegistry() directly instead of validateExtensionName('_dummy_')
• Added numeric type detection in inferExportType
• Expanded SKILL.md with detailed merge strategies and missing-file handling

Thanks for fixing bugs from my pr! I've met some of them but forgot to fix

Added my thoughts regarding PR. In short, I'm not sure it's a good approach long term, but it could work for some time until we change extensions structure.

---

note: Maybe we need to change most of extensions just to AI instructions? In that case adding extensions will be much simpler (I think you guys have similar thoughts)

[technophile-04]

note: Maybe we need to change most of extensions just to AI instructions? In that case adding extensions will be much simpler (I think you guys have similar thoughts)

YESS! I think we should focus on this maybe more?

Maybe we add the SKILL.md (which maybe contain some metdata for AI like what this extesnion does, maybe a diff giving how this extesnion deviates from base create-eth) and then the files in extension will just contain the whole files code no .arg.mjs files?

---

I also pushed some commits so now instead of hardcoding the patterns for the AI to guess, we ask it to fetch the https://github.com/scaffold-eth/create-eth/blob/main/contributors/TEMPLATE-FILES.md (subagent) does this so we dont' burn the context window. Also I think this file serves as source of truth with all the examples.

[rin-st]

I also pushed some commits so now instead of hardcoding the patterns for the AI to guess, we ask it to fetch the https://github.com/scaffold-eth/create-eth/blob/main/contributors/TEMPLATE-FILES.md (subagent) does this so we dont' burn the context window. Also I think this file serves as source of truth with all the examples.

Looking good to me!

Not sure if we need to merge it though, or if we need to think about new structure of extensions and try to implement first. Or it could be next iteration

[technophile-04]

Thanks @rin-st for testing! Just moved the skills to .agents dir so that it can used with curor / opencode and seems to works nicely in cursor as well (althought it didn't gave me auto-completion with /commnd but when i wrote `/add-extension ponder and drizzle-neon and x402) it picked the skill and executed it nicely.

Not sure if we need to merge it though, or if we need to think about new structure of extensions and try to implement first. Or it could be next iteration

cc @carletex for this. I think maybe we can ship this as initial version since again it doesn't have any damange on core logic.

[technophile-04]

Pushed ef7d876 cleaning up few things:

• removed --help, --list, fallback extensions list, type inference, and README.md.

• regarding the registry fetch: now fails explicitly instead of using stale hardcoded data, because we already have the registry maintained at create-eth so it doens't make sense to have the list hardcoded again here