RESTForge — Agent Skills (portable)

Vendor-neutral Agent Skills 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.

| | 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:

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.

# 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

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) and the MCP tool surface (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.