create-restforge-skills 0.2.0 → 0.4.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 (10) hide show
  1. package/README.md +148 -150
  2. package/package.json +33 -30
  3. package/skills/restforge/SKILL.md +832 -559
  4. package/skills/restforge/references/auth.md +2 -2
  5. package/skills/restforge/references/config-schema.md +238 -173
  6. package/skills/restforge/references/dbschema-catalog.md +245 -238
  7. package/skills/restforge/references/design-to-sdf.md +621 -618
  8. package/skills/restforge/references/field-validation.md +247 -173
  9. package/skills/restforge/references/rdf-advanced.md +695 -488
  10. package/skills/restforge/references/udf-catalog.md +623 -496
package/README.md CHANGED
@@ -1,150 +1,148 @@
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 **only** 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`. The installer (`create-restforge-skills`)
15
+ copies the skill into each client and registers the MCP server there.
16
+
17
+ The skill depends on one execution engine: the `@restforgejs/mcp-server` MCP
18
+ server. A skill describes *how* to drive RESTForge; the MCP server is *what*
19
+ actually executes the operations. The skill is useless without the MCP server
20
+ registered in the client.
21
+
22
+ ## Directory layout
23
+
24
+ ```
25
+ restforge-skills/
26
+ ├── README.md ← this file (end-user guide, published to npm)
27
+ ├── package.json ← npm package: create-restforge-skills
28
+ ├── *.bat ← maintainer scripts (see docs/DEVELOPMENT.md)
29
+ ├── cli/
30
+ │ ├── index.js ← installer that copies the skill into each client
31
+ │ └── mcp.js ← merges the MCP server into each client config
32
+ ├── docs/
33
+ │ └── DEVELOPMENT.md ← maintainer guide, NOT published (excluded from npm files)
34
+ └── skills/
35
+ └── restforge/
36
+ ├── SKILL.md ← the portable skill (name + description + workflow)
37
+ └── references/ ← progressive-disclosure reference material
38
+ ```
39
+
40
+ ## Install
41
+
42
+ One command. It detects your installed clients (Claude Code, Cursor), copies the
43
+ skill into each, and registers the RESTForge MCP server — because the skill is
44
+ inert without it:
45
+
46
+ ```bash
47
+ npx create-restforge-skills
48
+ ```
49
+
50
+ The MCP server is registered via `npx -y @restforgejs/mcp-server`, so there is no
51
+ separate global install. The MCP config is **merged, not overwritten**, and the
52
+ existing file is backed up to `<config>.bak` first.
53
+
54
+ ### Where to run it (working directory)
55
+
56
+ This is an **installer**, not a project scaffolder. Unlike `create-restforge-app`,
57
+ it takes **no positional folder argument** (`myapp` / `.`). The install location
58
+ is chosen by `--scope`, not by where you stand or by a path you pass.
59
+
60
+ - **Default (`--scope=user`) — run it from anywhere.** The current directory is
61
+ ignored. The skill goes to your home (`~/.claude/skills/`, `~/.cursor/skills/`)
62
+ and is available across **all** your projects. This is the normal usage: a skill
63
+ is editor/agent tooling, not part of any one app's source.
64
+
65
+ - **`--scope=project` — run it inside the project folder.** Here the current
66
+ directory matters: the skill and the MCP config are written relative to it, so
67
+ you must `cd` into the target project first. The skill lands in
68
+ `./.claude/skills/` or `./.cursor/skills/`; the MCP config goes to `./.mcp.json`
69
+ for Claude Code (its project-scope convention, not a file under `.claude/`) and
70
+ to `./.cursor/mcp.json` for Cursor. Use this to commit the skill with a specific
71
+ repo so the team gets it on clone.
72
+
73
+ ```bash
74
+ # normal — anywhere, global for every project
75
+ npx create-restforge-skills
76
+
77
+ # attach to one project — cd in first
78
+ cd path/to/my-project
79
+ npx create-restforge-skills --scope=project
80
+ ```
81
+
82
+ Note: a bare path such as `npx create-restforge-skills .` is **not** recognized as
83
+ "install here" — it is treated as an unknown argument. Use `--scope=project`.
84
+
85
+ ### Options
86
+
87
+ ```bash
88
+ npx create-restforge-skills --client=cursor # one client only
89
+ npx create-restforge-skills --scope=project # skill into ./.claude or ./.cursor, MCP into ./.mcp.json (commit for the team)
90
+ npx create-restforge-skills --mcp-command=global # use the installed restforge-mcp binary instead of npx
91
+ npx create-restforge-skills --no-mcp # skill only; you manage MCP yourself
92
+ npx create-restforge-skills --dry-run # preview, write nothing
93
+ npx create-restforge-skills --force # overwrite an existing skill (update)
94
+ ```
95
+
96
+ After install, set a valid RESTForge `LICENSE` for `codegen_*`/`runtime_*`
97
+ operations (Designer/frontend tools need no license). On Claude Code, if the
98
+ skills directory was just created, restart the client so it watches the new
99
+ directory.
100
+
101
+ ### Update
102
+
103
+ `npx` caches previously downloaded packages, so when updating always pin
104
+ `@latest` and pass `--force` to overwrite the installed skill folder:
105
+
106
+ ```bash
107
+ npx create-restforge-skills@latest --force
108
+ ```
109
+
110
+ If the machine already has the RESTForge MCP server registered the way you want
111
+ it (for example via a globally installed `restforge-mcp` binary), add `--no-mcp`
112
+ so the update touches only the skill and leaves the MCP config alone.
113
+
114
+ ### Where it installs
115
+
116
+ | Client | Scope | Skill | MCP config |
117
+ |---|---|---|---|
118
+ | Claude Code | user (default) | `~/.claude/skills/restforge/` | `~/.claude.json` |
119
+ | Claude Code | project | `./.claude/skills/restforge/` | `./.mcp.json` |
120
+ | Cursor | user (default) | `~/.cursor/skills/restforge/` | `~/.cursor/mcp.json` |
121
+ | Cursor | project | `./.cursor/skills/restforge/` | `./.cursor/mcp.json` |
122
+
123
+ Note the asymmetry on the project row: Claude Code reads a project-scope MCP
124
+ server from `./.mcp.json` in the repo root, so that is where the installer writes
125
+ it — not into `./.claude/`.
126
+
127
+ ### Manual install (no CLI)
128
+
129
+ The skill folder is self-contained — copy `skills/restforge/` (including
130
+ `references/`) into the client's skills directory and add
131
+ `{ "mcpServers": { "restforge": { "command": "npx", "args": ["-y", "@restforgejs/mcp-server"] } } }`
132
+ to the client's MCP config.
133
+
134
+ ### Gemini CLI / OpenAI Codex
135
+
136
+ Planned. Both consume the same `skills/restforge/` folder; only the skills
137
+ directory path and MCP config file differ per client.
138
+
139
+ ## Developing and releasing
140
+
141
+ Maintainer topics live in [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md): the
142
+ skill source, testing the skill from the working tree, the reference audit, the
143
+ release flow, and the extra care needed on machines that double as RESTForge
144
+ development machines. That guide is not published to npm.
145
+
146
+ ## License
147
+
148
+ MIT.
package/package.json CHANGED
@@ -1,30 +1,33 @@
1
- {
2
- "name": "create-restforge-skills",
3
- "version": "0.2.0",
4
- "description": "Install the RESTForge Agent Skill into Claude Code, Cursor, and other skills-compatible clients.",
5
- "type": "commonjs",
6
- "bin": {
7
- "create-restforge-skills": "cli/index.js"
8
- },
9
- "files": [
10
- "cli",
11
- "skills",
12
- "README.md"
13
- ],
14
- "engines": {
15
- "node": ">=18"
16
- },
17
- "keywords": [
18
- "restforge",
19
- "agent-skills",
20
- "skill",
21
- "claude-code",
22
- "cursor",
23
- "mcp"
24
- ],
25
- "author": {
26
- "name": "RESTForge",
27
- "url": "https://restforge.dev"
28
- },
29
- "license": "MIT"
30
- }
1
+ {
2
+ "name": "create-restforge-skills",
3
+ "version": "0.4.0",
4
+ "description": "Install the RESTForge Agent Skill into Claude Code, Cursor, and other skills-compatible clients.",
5
+ "type": "commonjs",
6
+ "bin": {
7
+ "create-restforge-skills": "cli/index.js"
8
+ },
9
+ "scripts": {
10
+ "audit-references": "node scripts/audit-references.js"
11
+ },
12
+ "files": [
13
+ "cli",
14
+ "skills",
15
+ "README.md"
16
+ ],
17
+ "engines": {
18
+ "node": ">=18"
19
+ },
20
+ "keywords": [
21
+ "restforge",
22
+ "agent-skills",
23
+ "skill",
24
+ "claude-code",
25
+ "cursor",
26
+ "mcp"
27
+ ],
28
+ "author": {
29
+ "name": "RESTForge",
30
+ "url": "https://restforge.dev"
31
+ },
32
+ "license": "MIT"
33
+ }