create-restforge-skills 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +158 -150
  2. package/package.json +1 -1
  3. package/skills/restforge/SKILL.md +740 -559
  4. package/skills/restforge/references/rdf-advanced.md +538 -488
  5. package/skills/restforge/references/udf-catalog.md +14 -6
package/README.md CHANGED
@@ -1,150 +1,158 @@
1
- # RESTForge — Agent Skills (portable)
2
-
3
- Vendor-neutral [Agent Skills](https://agentskills.io) for RESTForge. The same
4
- end-to-end RESTForge workflow knowledge, packaged in the open `SKILL.md` format
5
- so it works across any skills-compatible agent — **Claude Code, Cursor, Gemini
6
- CLI, and OpenAI Codex** — not only Claude Code.
7
-
8
- ## What this package is (and is not)
9
-
10
- This package is the **portable** distribution of RESTForge agent knowledge.
11
-
12
- - It contains pure Agent Skills: a `skills/restforge/SKILL.md` plus `references/`.
13
- - It has **no** client-specific packaging — no Claude Code `plugin.json`,
14
- `marketplace.json`, or `.mcp.json`.
15
-
16
- It is a **complement to**, not a replacement for, [`restforge-plugins`](../packages/restforge-plugins).
17
-
18
- | | `restforge-plugins` | `restforge-skills` (this package) |
19
- |---|---|---|
20
- | Target | Claude Code only | Claude Code, Cursor, Gemini CLI, Codex |
21
- | Distribution | Claude Code plugin + marketplace | Copy/symlink the skill folder into each client's skills directory |
22
- | MCP registration | Bundled (`.mcp.json`) | Done per client by the user (see below) |
23
- | Knowledge source | `skills/restforge-skills/` | Same knowledge, portable form |
24
-
25
- Both packages wrap the **same** workflow knowledge and depend on the **same**
26
- execution engine: the `@restforgejs/mcp-server` MCP server. A skill describes
27
- *how* to drive RESTForge; the MCP server is *what* actually executes the
28
- operations. The skill is useless without the MCP server registered in the client.
29
-
30
- ## Directory layout
31
-
32
- ```
33
- restforge-skills/
34
- ├── README.md ← this file
35
- ├── package.json ← npm package: create-restforge-skills
36
- ├── bump-and-publish.bat ← version bump + npm publish
37
- ├── sync-to-plugin.bat ← mirror the skill into the Claude Code plugin
38
- ├── cli/
39
- │ ├── index.js ← installer that copies the skill into each client
40
- │ └── mcp.js ← merges the MCP server into each client config
41
- ├── docs/ ← internal docs, NOT published (excluded from npm files)
42
- └── skills/
43
- └── restforge/
44
- ├── SKILL.md ← the portable skill (name + description + workflow)
45
- └── references/ ← progressive-disclosure reference material
46
- ```
47
-
48
- ## Single source of truth
49
-
50
- `skills/restforge/` here is the **one** authoritative copy of the skill. Two
51
- distribution channels consume it — do not edit the skill anywhere else:
52
-
53
- - **This package** (`create-restforge-skills`) — published to npm; cross-client.
54
- - **The Claude Code plugin** (`../packages/restforge-plugins`) — its
55
- `skills/restforge-skills/` folder is a **generated mirror**. After editing the
56
- canonical skill, run `sync-to-plugin.bat` to propagate, then commit the plugin
57
- repo. Hand-edits to the plugin's skill copy are overwritten on the next sync.
58
-
59
- ## Install
60
-
61
- One command. It detects your installed clients (Claude Code, Cursor), copies the
62
- skill into each, and registers the RESTForge MCP server — because the skill is
63
- inert without it:
64
-
65
- ```bash
66
- npx create-restforge-skills
67
- ```
68
-
69
- The MCP server is registered via `npx -y @restforgejs/mcp-server`, so there is no
70
- separate global install. The MCP config is **merged, not overwritten**, and the
71
- existing file is backed up to `<config>.bak` first.
72
-
73
- ### Where to run it (working directory)
74
-
75
- This is an **installer**, not a project scaffolder. Unlike `create-restforge-app`,
76
- it takes **no positional folder argument** (`myapp` / `.`). The install location
77
- is chosen by `--scope`, not by where you stand or by a path you pass.
78
-
79
- - **Default (`--scope=user`) — run it from anywhere.** The current directory is
80
- ignored. The skill goes to your home (`~/.claude/skills/`, `~/.cursor/skills/`)
81
- and is available across **all** your projects. This is the normal usage: a skill
82
- is editor/agent tooling, not part of any one app's source.
83
-
84
- - **`--scope=project` — run it inside the project folder.** Here the current
85
- directory matters: the skill and MCP config are written relative to it
86
- (`./.claude/...`, `./.cursor/...`), so you must `cd` into the target project
87
- first. Use this to commit the skill with a specific repo so the team gets it on
88
- clone.
89
-
90
- ```bash
91
- # normal — anywhere, global for every project
92
- npx create-restforge-skills
93
-
94
- # attach to one project — cd in first
95
- cd path/to/my-project
96
- npx create-restforge-skills --scope=project
97
- ```
98
-
99
- Note: a bare path such as `npx create-restforge-skills .` is **not** recognized as
100
- "install here" — it is treated as an unknown argument. Use `--scope=project`.
101
-
102
- ### Options
103
-
104
- ```bash
105
- npx create-restforge-skills --client=cursor # one client only
106
- npx create-restforge-skills --scope=project # into ./.claude or ./.cursor (commit for the team)
107
- npx create-restforge-skills --mcp-command=global # use the installed restforge-mcp binary instead of npx
108
- npx create-restforge-skills --no-mcp # skill only; you manage MCP yourself
109
- npx create-restforge-skills --dry-run # preview, write nothing
110
- npx create-restforge-skills --force # overwrite an existing skill (update)
111
- ```
112
-
113
- After install, set a valid RESTForge `LICENSE` for `codegen_*`/`runtime_*`
114
- operations (Designer/frontend tools need no license). On Claude Code, if the
115
- skills directory was just created, restart the client so it watches the new
116
- directory.
117
-
118
- ### Where it installs
119
-
120
- | Client | Skill (user scope) | MCP config |
121
- |---|---|---|
122
- | Claude Code | `~/.claude/skills/restforge/` | `~/.claude.json` |
123
- | Cursor | `~/.cursor/skills/restforge/` | `~/.cursor/mcp.json` |
124
-
125
- > For Claude Code, a turnkey alternative is the `restforge-plugins` package,
126
- > which bundles the skill **and** MCP registration in one `/plugin install`.
127
-
128
- ### Manual install (no CLI)
129
-
130
- The skill folder is self-contained — copy `skills/restforge/` (including
131
- `references/`) into the client's skills directory and add
132
- `{ "mcpServers": { "restforge": { "command": "npx", "args": ["-y", "@restforgejs/mcp-server"] } } }`
133
- to the client's MCP config.
134
-
135
- ### Gemini CLI / OpenAI Codex
136
-
137
- Planned. Both consume the same `skills/restforge/` folder; only the skills
138
- directory path and MCP config file differ per client.
139
-
140
- ## Source of truth
141
-
142
- The knowledge in this skill mirrors the RESTForge handbook
143
- ([`restforge-handbook`](../restforge-handbook)) and the MCP tool surface
144
- ([`mcp-server`](../packages/mcp-server)). When RESTForge behavior changes, update the
145
- handbook first, then this skill — the skill is downstream documentation of real
146
- tool behavior, never an independent source.
147
-
148
- ## License
149
-
150
- MIT.
1
+ # RESTForge — Agent Skills (portable)
2
+
3
+ Vendor-neutral [Agent Skills](https://agentskills.io) for RESTForge. The same
4
+ end-to-end RESTForge workflow knowledge, packaged in the open `SKILL.md` format
5
+ so it works across any skills-compatible agent — **Claude Code, Cursor, Gemini
6
+ CLI, and OpenAI Codex** — not only Claude Code.
7
+
8
+ ## What this package is (and is not)
9
+
10
+ This package is the **portable** distribution of RESTForge agent knowledge.
11
+
12
+ - It contains pure Agent Skills: a `skills/restforge/SKILL.md` plus `references/`.
13
+ - It has **no** client-specific packaging — no Claude Code `plugin.json`,
14
+ `marketplace.json`, or `.mcp.json`.
15
+
16
+ It is a **complement to**, not a replacement for, [`restforge-plugins`](../packages/restforge-plugins).
17
+
18
+ | | `restforge-plugins` | `restforge-skills` (this package) |
19
+ |---|---|---|
20
+ | Target | Claude Code only | Claude Code, Cursor, Gemini CLI, Codex |
21
+ | Distribution | Claude Code plugin + marketplace | Copy/symlink the skill folder into each client's skills directory |
22
+ | MCP registration | Bundled (`.mcp.json`) | Done per client by the user (see below) |
23
+ | Knowledge source | `skills/restforge-skills/` | Same knowledge, portable form |
24
+
25
+ Both packages wrap the **same** workflow knowledge and depend on the **same**
26
+ execution engine: the `@restforgejs/mcp-server` MCP server. A skill describes
27
+ *how* to drive RESTForge; the MCP server is *what* actually executes the
28
+ operations. The skill is useless without the MCP server registered in the client.
29
+
30
+ ## Directory layout
31
+
32
+ ```
33
+ restforge-skills/
34
+ ├── README.md ← this file
35
+ ├── package.json ← npm package: create-restforge-skills
36
+ ├── bump-and-publish.bat ← version bump + npm publish
37
+ ├── sync-to-plugin.bat ← mirror the skill into the Claude Code plugin
38
+ ├── cli/
39
+ │ ├── index.js ← installer that copies the skill into each client
40
+ │ └── mcp.js ← merges the MCP server into each client config
41
+ ├── docs/ ← internal docs, NOT published (excluded from npm files)
42
+ └── skills/
43
+ └── restforge/
44
+ ├── SKILL.md ← the portable skill (name + description + workflow)
45
+ └── references/ ← progressive-disclosure reference material
46
+ ```
47
+
48
+ ## Single source of truth
49
+
50
+ `skills/restforge/` here is the **one** authoritative copy of the skill. Two
51
+ distribution channels consume it — do not edit the skill anywhere else:
52
+
53
+ - **This package** (`create-restforge-skills`) — published to npm; cross-client.
54
+ - **The Claude Code plugin** (`../packages/restforge-plugins`) — its
55
+ `skills/restforge-skills/` folder is a **generated mirror**. After editing the
56
+ canonical skill, run `sync-to-plugin.bat` to propagate, then commit the plugin
57
+ repo. Hand-edits to the plugin's skill copy are overwritten on the next sync.
58
+
59
+ ## Install
60
+
61
+ One command. It detects your installed clients (Claude Code, Cursor), copies the
62
+ skill into each, and registers the RESTForge MCP server — because the skill is
63
+ inert without it:
64
+
65
+ ```bash
66
+ npx create-restforge-skills
67
+ ```
68
+
69
+ The MCP server is registered via `npx -y @restforgejs/mcp-server`, so there is no
70
+ separate global install. The MCP config is **merged, not overwritten**, and the
71
+ existing file is backed up to `<config>.bak` first.
72
+
73
+ ### Where to run it (working directory)
74
+
75
+ This is an **installer**, not a project scaffolder. Unlike `create-restforge-app`,
76
+ it takes **no positional folder argument** (`myapp` / `.`). The install location
77
+ is chosen by `--scope`, not by where you stand or by a path you pass.
78
+
79
+ - **Default (`--scope=user`) — run it from anywhere.** The current directory is
80
+ ignored. The skill goes to your home (`~/.claude/skills/`, `~/.cursor/skills/`)
81
+ and is available across **all** your projects. This is the normal usage: a skill
82
+ is editor/agent tooling, not part of any one app's source.
83
+
84
+ - **`--scope=project` — run it inside the project folder.** Here the current
85
+ directory matters: the skill and the MCP config are written relative to it, so
86
+ you must `cd` into the target project first. The skill lands in
87
+ `./.claude/skills/` or `./.cursor/skills/`; the MCP config goes to `./.mcp.json`
88
+ for Claude Code (its project-scope convention, not a file under `.claude/`) and
89
+ to `./.cursor/mcp.json` for Cursor. Use this to commit the skill with a specific
90
+ repo so the team gets it on clone.
91
+
92
+ ```bash
93
+ # normal — anywhere, global for every project
94
+ npx create-restforge-skills
95
+
96
+ # attach to one project — cd in first
97
+ cd path/to/my-project
98
+ npx create-restforge-skills --scope=project
99
+ ```
100
+
101
+ Note: a bare path such as `npx create-restforge-skills .` is **not** recognized as
102
+ "install here" — it is treated as an unknown argument. Use `--scope=project`.
103
+
104
+ ### Options
105
+
106
+ ```bash
107
+ npx create-restforge-skills --client=cursor # one client only
108
+ npx create-restforge-skills --scope=project # skill into ./.claude or ./.cursor, MCP into ./.mcp.json (commit for the team)
109
+ npx create-restforge-skills --mcp-command=global # use the installed restforge-mcp binary instead of npx
110
+ npx create-restforge-skills --no-mcp # skill only; you manage MCP yourself
111
+ npx create-restforge-skills --dry-run # preview, write nothing
112
+ npx create-restforge-skills --force # overwrite an existing skill (update)
113
+ ```
114
+
115
+ After install, set a valid RESTForge `LICENSE` for `codegen_*`/`runtime_*`
116
+ operations (Designer/frontend tools need no license). On Claude Code, if the
117
+ skills directory was just created, restart the client so it watches the new
118
+ directory.
119
+
120
+ ### Where it installs
121
+
122
+ | Client | Scope | Skill | MCP config |
123
+ |---|---|---|---|
124
+ | Claude Code | user (default) | `~/.claude/skills/restforge/` | `~/.claude.json` |
125
+ | Claude Code | project | `./.claude/skills/restforge/` | `./.mcp.json` |
126
+ | Cursor | user (default) | `~/.cursor/skills/restforge/` | `~/.cursor/mcp.json` |
127
+ | Cursor | project | `./.cursor/skills/restforge/` | `./.cursor/mcp.json` |
128
+
129
+ Note the asymmetry on the project row: Claude Code reads a project-scope MCP
130
+ server from `./.mcp.json` in the repo root, so that is where the installer writes
131
+ it — not into `./.claude/`.
132
+
133
+ > For Claude Code, a turnkey alternative is the `restforge-plugins` package,
134
+ > which bundles the skill **and** MCP registration in one `/plugin install`.
135
+
136
+ ### Manual install (no CLI)
137
+
138
+ The skill folder is self-contained — copy `skills/restforge/` (including
139
+ `references/`) into the client's skills directory and add
140
+ `{ "mcpServers": { "restforge": { "command": "npx", "args": ["-y", "@restforgejs/mcp-server"] } } }`
141
+ to the client's MCP config.
142
+
143
+ ### Gemini CLI / OpenAI Codex
144
+
145
+ Planned. Both consume the same `skills/restforge/` folder; only the skills
146
+ directory path and MCP config file differ per client.
147
+
148
+ ## Source of truth
149
+
150
+ The knowledge in this skill mirrors the RESTForge handbook
151
+ ([`restforge-handbook`](../restforge-handbook)) and the MCP tool surface
152
+ ([`mcp-server`](../packages/mcp-server)). When RESTForge behavior changes, update the
153
+ handbook first, then this skill — the skill is downstream documentation of real
154
+ tool behavior, never an independent source.
155
+
156
+ ## License
157
+
158
+ MIT.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-restforge-skills",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Install the RESTForge Agent Skill into Claude Code, Cursor, and other skills-compatible clients.",
5
5
  "type": "commonjs",
6
6
  "bin": {