forge-fragments9.46 KB
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). ThPreview of the first 4,000 characters. Read full instructions →
