create-restforge-skills 0.1.1 → 0.3.0

package/README.md

@@ -1,150 +1,158 @@
-# RESTForge — Agent Skills (portable)
-
-Vendor-neutral [Agent Skills](https://agentskills.io) for RESTForge. The same
-end-to-end RESTForge workflow knowledge, packaged in the open `SKILL.md` format
-so it works across any skills-compatible agent — **Claude Code, Cursor, Gemini
-CLI, and OpenAI Codex** — not only Claude Code.
-
-## What this package is (and is not)
-
-This package is the **portable** distribution of RESTForge agent knowledge.
-
-- It contains pure Agent Skills: a `skills/restforge/SKILL.md` plus `references/`.
-- It has **no** client-specific packaging — no Claude Code `plugin.json`,
-  `marketplace.json`, or `.mcp.json`.
-
-It is a **complement to**, not a replacement for, [`restforge-plugins`](../packages/restforge-plugins).
-
-| | `restforge-plugins` | `restforge-skills` (this package) |
-|---|---|---|
-| Target | Claude Code only | Claude Code, Cursor, Gemini CLI, Codex |
-| Distribution | Claude Code plugin + marketplace | Copy/symlink the skill folder into each client's skills directory |
-| MCP registration | Bundled (`.mcp.json`) | Done per client by the user (see below) |
-| Knowledge source | `skills/restforge-skills/` | Same knowledge, portable form |
-
-Both packages wrap the **same** workflow knowledge and depend on the **same**
-execution engine: the `@restforgejs/mcp-server` MCP server. A skill describes
-*how* to drive RESTForge; the MCP server is *what* actually executes the
-operations. The skill is useless without the MCP server registered in the client.
-
-## Directory layout
-
-```
-restforge-skills/
-├── README.md                 ← this file
-├── package.json              ← npm package: create-restforge-skills
-├── bump-and-publish.bat      ← version bump + npm publish
-├── sync-to-plugin.bat        ← mirror the skill into the Claude Code plugin
-├── cli/
-│   ├── index.js              ← installer that copies the skill into each client
-│   └── mcp.js                ← merges the MCP server into each client config
-├── docs/                     ← internal docs, NOT published (excluded from npm files)
-└── skills/
-    └── restforge/
-        ├── SKILL.md          ← the portable skill (name + description + workflow)
-        └── references/       ← progressive-disclosure reference material
-```
-
-## Single source of truth
-
-`skills/restforge/` here is the **one** authoritative copy of the skill. Two
-distribution channels consume it — do not edit the skill anywhere else:
-
-- **This package** (`create-restforge-skills`) — published to npm; cross-client.
-- **The Claude Code plugin** (`../packages/restforge-plugins`) — its
-  `skills/restforge-skills/` folder is a **generated mirror**. After editing the
-  canonical skill, run `sync-to-plugin.bat` to propagate, then commit the plugin
-  repo. Hand-edits to the plugin's skill copy are overwritten on the next sync.
-
-## Install
-
-One command. It detects your installed clients (Claude Code, Cursor), copies the
-skill into each, and registers the RESTForge MCP server — because the skill is
-inert without it:
-
-```bash
-npx create-restforge-skills
-```
-
-The MCP server is registered via `npx -y @restforgejs/mcp-server`, so there is no
-separate global install. The MCP config is **merged, not overwritten**, and the
-existing file is backed up to `<config>.bak` first.
-
-### Where to run it (working directory)
-
-This is an **installer**, not a project scaffolder. Unlike `create-restforge-app`,
-it takes **no positional folder argument** (`myapp` / `.`). The install location
-is chosen by `--scope`, not by where you stand or by a path you pass.
-
-- **Default (`--scope=user`) — run it from anywhere.** The current directory is
-  ignored. The skill goes to your home (`~/.claude/skills/`, `~/.cursor/skills/`)
-  and is available across **all** your projects. This is the normal usage: a skill
-  is editor/agent tooling, not part of any one app's source.
-
-- **`--scope=project` — run it inside the project folder.** Here the current
-  directory matters: the skill and MCP config are written relative to it
-  (`./.claude/...`, `./.cursor/...`), so you must `cd` into the target project
-  first. Use this to commit the skill with a specific repo so the team gets it on
-  clone.
-
-```bash
-# normal — anywhere, global for every project
-npx create-restforge-skills
-
-# attach to one project — cd in first
-cd path/to/my-project
-npx create-restforge-skills --scope=project
-```
-
-Note: a bare path such as `npx create-restforge-skills .` is **not** recognized as
-"install here" — it is treated as an unknown argument. Use `--scope=project`.
-
-### Options
-
-```bash
-npx create-restforge-skills --client=cursor      # one client only
-npx create-restforge-skills --scope=project      # into ./.claude or ./.cursor (commit for the team)
-npx create-restforge-skills --mcp-command=global # use the installed restforge-mcp binary instead of npx
-npx create-restforge-skills --no-mcp             # skill only; you manage MCP yourself
-npx create-restforge-skills --dry-run            # preview, write nothing
-npx create-restforge-skills --force              # overwrite an existing skill (update)
-```
-
-After install, set a valid RESTForge `LICENSE` for `codegen_*`/`runtime_*`
-operations (Designer/frontend tools need no license). On Claude Code, if the
-skills directory was just created, restart the client so it watches the new
-directory.
-
-### Where it installs
-
-| Client | Skill (user scope) | MCP config |
-|---|---|---|
-| Claude Code | `~/.claude/skills/restforge/` | `~/.claude.json` |
-| Cursor | `~/.cursor/skills/restforge/` | `~/.cursor/mcp.json` |
-
-> For Claude Code, a turnkey alternative is the `restforge-plugins` package,
-> which bundles the skill **and** MCP registration in one `/plugin install`.
-
-### Manual install (no CLI)
-
-The skill folder is self-contained — copy `skills/restforge/` (including
-`references/`) into the client's skills directory and add
-`{ "mcpServers": { "restforge": { "command": "npx", "args": ["-y", "@restforgejs/mcp-server"] } } }`
-to the client's MCP config.
-
-### Gemini CLI / OpenAI Codex
-
-Planned. Both consume the same `skills/restforge/` folder; only the skills
-directory path and MCP config file differ per client.
-
-## Source of truth
-
-The knowledge in this skill mirrors the RESTForge handbook
-([`restforge-handbook`](../restforge-handbook)) and the MCP tool surface
-([`mcp-server`](../packages/mcp-server)). When RESTForge behavior changes, update the
-handbook first, then this skill — the skill is downstream documentation of real
-tool behavior, never an independent source.
-
-## License
-
-MIT.
+# RESTForge — Agent Skills (portable)
+
+Vendor-neutral [Agent Skills](https://agentskills.io) for RESTForge. The same
+end-to-end RESTForge workflow knowledge, packaged in the open `SKILL.md` format
+so it works across any skills-compatible agent — **Claude Code, Cursor, Gemini
+CLI, and OpenAI Codex** — not only Claude Code.
+
+## What this package is (and is not)
+
+This package is the **portable** distribution of RESTForge agent knowledge.
+
+- It contains pure Agent Skills: a `skills/restforge/SKILL.md` plus `references/`.
+- It has **no** client-specific packaging — no Claude Code `plugin.json`,
+  `marketplace.json`, or `.mcp.json`.
+
+It is a **complement to**, not a replacement for, [`restforge-plugins`](../packages/restforge-plugins).
+
+| | `restforge-plugins` | `restforge-skills` (this package) |
+|---|---|---|
+| Target | Claude Code only | Claude Code, Cursor, Gemini CLI, Codex |
+| Distribution | Claude Code plugin + marketplace | Copy/symlink the skill folder into each client's skills directory |
+| MCP registration | Bundled (`.mcp.json`) | Done per client by the user (see below) |
+| Knowledge source | `skills/restforge-skills/` | Same knowledge, portable form |
+
+Both packages wrap the **same** workflow knowledge and depend on the **same**
+execution engine: the `@restforgejs/mcp-server` MCP server. A skill describes
+*how* to drive RESTForge; the MCP server is *what* actually executes the
+operations. The skill is useless without the MCP server registered in the client.
+
+## Directory layout
+
+```
+restforge-skills/
+├── README.md                 ← this file
+├── package.json              ← npm package: create-restforge-skills
+├── bump-and-publish.bat      ← version bump + npm publish
+├── sync-to-plugin.bat        ← mirror the skill into the Claude Code plugin
+├── cli/
+│   ├── index.js              ← installer that copies the skill into each client
+│   └── mcp.js                ← merges the MCP server into each client config
+├── docs/                     ← internal docs, NOT published (excluded from npm files)
+└── skills/
+    └── restforge/
+        ├── SKILL.md          ← the portable skill (name + description + workflow)
+        └── references/       ← progressive-disclosure reference material
+```
+
+## Single source of truth
+
+`skills/restforge/` here is the **one** authoritative copy of the skill. Two
+distribution channels consume it — do not edit the skill anywhere else:
+
+- **This package** (`create-restforge-skills`) — published to npm; cross-client.
+- **The Claude Code plugin** (`../packages/restforge-plugins`) — its
+  `skills/restforge-skills/` folder is a **generated mirror**. After editing the
+  canonical skill, run `sync-to-plugin.bat` to propagate, then commit the plugin
+  repo. Hand-edits to the plugin's skill copy are overwritten on the next sync.
+
+## Install
+
+One command. It detects your installed clients (Claude Code, Cursor), copies the
+skill into each, and registers the RESTForge MCP server — because the skill is
+inert without it:
+
+```bash
+npx create-restforge-skills
+```
+
+The MCP server is registered via `npx -y @restforgejs/mcp-server`, so there is no
+separate global install. The MCP config is **merged, not overwritten**, and the
+existing file is backed up to `<config>.bak` first.
+
+### Where to run it (working directory)
+
+This is an **installer**, not a project scaffolder. Unlike `create-restforge-app`,
+it takes **no positional folder argument** (`myapp` / `.`). The install location
+is chosen by `--scope`, not by where you stand or by a path you pass.
+
+- **Default (`--scope=user`) — run it from anywhere.** The current directory is
+  ignored. The skill goes to your home (`~/.claude/skills/`, `~/.cursor/skills/`)
+  and is available across **all** your projects. This is the normal usage: a skill
+  is editor/agent tooling, not part of any one app's source.
+
+- **`--scope=project` — run it inside the project folder.** Here the current
+  directory matters: the skill and the MCP config are written relative to it, so
+  you must `cd` into the target project first. The skill lands in
+  `./.claude/skills/` or `./.cursor/skills/`; the MCP config goes to `./.mcp.json`
+  for Claude Code (its project-scope convention, not a file under `.claude/`) and
+  to `./.cursor/mcp.json` for Cursor. Use this to commit the skill with a specific
+  repo so the team gets it on clone.
+
+```bash
+# normal — anywhere, global for every project
+npx create-restforge-skills
+
+# attach to one project — cd in first
+cd path/to/my-project
+npx create-restforge-skills --scope=project
+```
+
+Note: a bare path such as `npx create-restforge-skills .` is **not** recognized as
+"install here" — it is treated as an unknown argument. Use `--scope=project`.
+
+### Options
+
+```bash
+npx create-restforge-skills --client=cursor      # one client only
+npx create-restforge-skills --scope=project      # skill into ./.claude or ./.cursor, MCP into ./.mcp.json (commit for the team)
+npx create-restforge-skills --mcp-command=global # use the installed restforge-mcp binary instead of npx
+npx create-restforge-skills --no-mcp             # skill only; you manage MCP yourself
+npx create-restforge-skills --dry-run            # preview, write nothing
+npx create-restforge-skills --force              # overwrite an existing skill (update)
+```
+
+After install, set a valid RESTForge `LICENSE` for `codegen_*`/`runtime_*`
+operations (Designer/frontend tools need no license). On Claude Code, if the
+skills directory was just created, restart the client so it watches the new
+directory.
+
+### Where it installs
+
+| Client | Scope | Skill | MCP config |
+|---|---|---|---|
+| Claude Code | user (default) | `~/.claude/skills/restforge/` | `~/.claude.json` |
+| Claude Code | project | `./.claude/skills/restforge/` | `./.mcp.json` |
+| Cursor | user (default) | `~/.cursor/skills/restforge/` | `~/.cursor/mcp.json` |
+| Cursor | project | `./.cursor/skills/restforge/` | `./.cursor/mcp.json` |
+
+Note the asymmetry on the project row: Claude Code reads a project-scope MCP
+server from `./.mcp.json` in the repo root, so that is where the installer writes
+it — not into `./.claude/`.
+
+> For Claude Code, a turnkey alternative is the `restforge-plugins` package,
+> which bundles the skill **and** MCP registration in one `/plugin install`.
+
+### Manual install (no CLI)
+
+The skill folder is self-contained — copy `skills/restforge/` (including
+`references/`) into the client's skills directory and add
+`{ "mcpServers": { "restforge": { "command": "npx", "args": ["-y", "@restforgejs/mcp-server"] } } }`
+to the client's MCP config.
+
+### Gemini CLI / OpenAI Codex
+
+Planned. Both consume the same `skills/restforge/` folder; only the skills
+directory path and MCP config file differ per client.
+
+## Source of truth
+
+The knowledge in this skill mirrors the RESTForge handbook
+([`restforge-handbook`](../restforge-handbook)) and the MCP tool surface
+([`mcp-server`](../packages/mcp-server)). When RESTForge behavior changes, update the
+handbook first, then this skill — the skill is downstream documentation of real
+tool behavior, never an independent source.
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-restforge-skills",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Install the RESTForge Agent Skill into Claude Code, Cursor, and other skills-compatible clients.",
   "type": "commonjs",
   "bin": {