Forge

View saved version →

---
name: forge-fragments
description: Use Forge Fragments (hosted React components with variants, collections and skills) through the Forge MCP. Use when the user mentions Forge, a fragment, a Forge collection or kit, a ui8.dev page, or a forge.ui8.ai share link; when they want to find, preview, publish, remix or organize UI they keep in Forge; when they ask about feedback on a fragment; and in a code project before building a piece of UI they may already have in Forge. Not for general UI questions with no Forge workspace involved.
---

# Forge Fragments

A **fragment** is a small React project hosted in Forge Cloud: Vite-shaped,
previewed live at a URL, with one or more **variants** (named entry files that
share every other file) and a **story** (the props and values its controls
edit). Fragments are filed in **collections**. A collection or a workspace
carries **skills**: SKILL.md rules that say how its fragments are meant to be
used, and **files**: one tree of logos, PDFs, fonts or reference data. A
collection with only skills is a design system; one with only fragments is a
parts bin.

The Forge MCP's own instructions carry the must-know; `fragment_docs` is the
full reference (limits, tree rules, the story format, error codes). Read it
when a detail here is not enough.

## Where you are decides what you can do

- **Codex, or any agent with a shell and a filesystem**: every flow below.
- **ChatGPT (no local shell)**: find, preview, publish, feedback, organize,
  remix and skills. Do not call `fragment_start_session` or `fragment_pull`
  there: an edit session needs you to run its download and upload commands,
  and a pull needs a project to write files into. When the user asks to
  create or change a fragment's code in ChatGPT, say that it needs Codex or
  another coding agent connected to Forge, and offer what you can do here
  (find a similar fragment, preview it, remix it, or edit its description,
  tags and variant values).

## Use a fragment in the project you are in

Do this before building any piece of UI the user might already keep in Forge.

1. `fragment_find { intent, project? }`. Say what you are about to build in
   your own words; pass `project` facts (framework, styling, dependencies)
   when you know them. Follow the `next` line it returns.
2. If `gate.fits` is false, nothing fits: build it yourself, still following
   the `relevant` skills.
3. `skill_get { skillId }` for every skill listed. Read them before touching
   code: they hold the tokens, spacing, naming and what never to do.
4. `fragment_pull { fragmentId, variant? }`. It returns the files inline (or a
   tar URL and command for a large tree), signed asset URLs (curl them; they
   expire in an hour), dependencies, the story and the governing skills.
5. Adapt, do not paste: match the project's import aliases and styling
   entry, wire props to the story's values, keep the kit's tokens. Put
   `provenance.header` as the first line of the adapted entry file. If the
   project keeps agent skills, write each pulled skill as its whole
   `folder` at `folder.path` (`.agents/skills/<name>/`, named exactly the
   skill): run `folder.tar.command` (it replaces the folder once the
   download worked, so files a skill dropped do not linger), or write
   `folder.markdown` as SKILL.md, curl each file url to its relative path
   and `chmod +x` `scripts/`.
6. Never write one skill over another. Skills that share a name come back
   in `skillCollisions`, and a folder whose SKILL.md has no
   `metadata.forge-skill-id`, or a different one, is another skill (or the
   user's own): ask the user which to keep.

A hit that belongs to a collection is usually one part of a kit:
`fragment_collection_get { collectionId }` lists its siblings, which the same
skills govern. A share link `/share/collection/<id>` names a collection; read
it the same way.

Find, pull and `fragment_collection_get` also list the **files** kept beside
the fragments (`fileTrees`: paths, mime, size). Th

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: forge-projects
description: Use Forge Projects (hosted, live React components, organized in collections with skills) through the Forge MCP. Use when the user mentions Forge, a Forge project or component, a Forge collection or kit, a ui8.dev page, or a forge.ui8.ai share link; when they want to find, preview, publish, remix or organize UI they keep in Forge; when they ask about feedback on a Forge project; and in a codebase before building a piece of UI they may already have in Forge. Not for general UI questions with no Forge workspace involved.
---

# Forge Projects

A **project** is a small React app hosted in Forge Cloud: Vite-shaped,
previewed live at a URL, with one or more **components** (named entry files
that share every other file) and a **story** (the props and values its
controls edit). One component is the project's **cover**: the one shown
first, used for its preview image and opened by its share and publish links.
Projects are filed in **collections**. A collection or a workspace carries
**skills**: SKILL.md rules that say how its projects are meant to be used,
and **files**: one tree of logos, PDFs, fonts or reference data. A
collection with only skills is a design system; one with only projects is a
parts bin.

The tools still use the older names: a **fragment** is a project and a
**variant** is a component. Call every tool and pass every argument exactly
as named (`fragment_find`, `fragmentId`, `variant`, `fragment_save_variant`
and so on), and say "project" and "component" to the user.

The Forge MCP's own instructions carry the must-know; `fragment_docs` is the
full reference (limits, tree rules, the story format, error codes). Read it
when a detail here is not enough.

## Where you are decides what you can do

- **Codex, or any agent with a shell and a filesystem**: every flow below.
- **ChatGPT (no local shell)**: find, preview, publish, feedback, organize,
  remix and skills. Do not call `fragment_start_session` or `fragment_pull`
  there: an edit session needs you to run its download and upload commands,
  and a pull needs a codebase to write files into. When the user asks to
  create or change a project's code in ChatGPT, say that it needs Codex or
  another coding agent connected to Forge, and offer what you can do here
  (find a similar project, preview it, remix it, or edit its description,
  tags and component values).

## Use a Forge project in the codebase you are in

Do this before building any piece of UI the user might already keep in Forge.

1. `fragment_find { intent, project? }`. Say what you are about to build in
   your own words; pass `project` facts about the codebase (framework,
   styling, dependencies) when you know them. Follow the `next` line it
   returns.
2. If `gate.fits` is false, nothing fits: build it yourself, still following
   the `relevant` skills.
3. `skill_get { skillId }` for every skill listed. Read them before touching
   code: they hold the tokens, spacing, naming and what never to do.
4. `fragment_pull { fragmentId, variant? }`. It returns the files inline (or a
   tar URL and command for a large tree), signed asset URLs (curl them; they
   expire in an hour), dependencies, the story and the governing skills.
5. Adapt, do not paste: match the codebase's import aliases and styling
   entry, wire props to the story's values, keep the kit's tokens. Put
   `provenance.header` as the first line of the adapted entry file. If the
   codebase keeps agent skills, write each pulled skill as its whole
   `folder` at `folder.path` (`.agents/skills/<name>/`, named exactly the
   skill): run `folder.tar.command` (it replaces the folder once the
   download worked, so files a skill dropped do not linger), or write
   `folder.markdown` as SKILL.md, curl each file url to its relative path
   and `chmod +x` `scripts/`.
6. Never write one skill over another. Skills that share a name come back
   in `skillCollisions`, and a folder whose SKILL.md has no
   `metadata.forge-skil

Preview of the first 4,000 characters. Read full instructions →