Fix Artifacts Requirements

Problem

Artifacts do not work in Forge. Since the Forge Skill Cleanup project restructured the Artifacts skill, agents no longer produce working artifacts in LibreChat. “Enable Artifacts” is turned on in the Agent Builder UI, and “Custom Prompt Mode” for artifacts is also enabled — meaning LibreChat will not inject its own artifact instructions into the system prompt. That is our job. Neither FORGE.md (inlined as agent instructions) nor the Artifacts skill in its current form is making this happen.

Background

How LibreChat artifacts work

LibreChat has two artifact prompt modes:

Mode	Behavior
Default	LibreChat injects its full built-in artifact instructions (format, types, libraries, examples, shadcn supplement) into the system prompt automatically
Custom	LibreChat injects nothing — the agent’s own instructions must contain everything the model needs to produce valid :::artifact blocks

Our agents use Custom Prompt Mode. This means the entire artifact instruction burden falls on us.

What we currently have

Artifact	Location	Role	Loaded when?
Forge/Configs/FORGE.md	Inlined into agent instructions field by update-agents.ts	Agent system prompt	Every conversation
Forge/Skills/Artifacts/SKILL.md	On disk, readable via filesystem MCP	Full artifact spec	Only if agent reads it proactively
Forge/Projects/Forge_Skill_Cleanup/LibreChat_0.8.5_Artifact_Instructions.md	Reference copy of what LibreChat v0.8.5 normally injects	Original source	Never (reference)
Forge/Projects/Forge_Skill_Cleanup/LibreChat_0.8.5_Shadcn_Artifact_Suplement.md	Reference copy of shadcn component supplement	Original source	Never (reference)

Why artifacts are broken

1. No artifact instructions in the system prompt. FORGE.md contains zero artifact instructions. With Custom Prompt Mode, the model has no idea how to produce :::artifact blocks.

2. Skill not loaded automatically. The Artifacts skill exists on disk but agents have no trigger to read it before creating artifacts. The skill is only useful if the agent already knows it should read it — a circular dependency.

3. The condensed format lost critical detail. SKILL.md says “For full type constraints, library versions, and React/HTML rules: read Forge/Skills/Artifacts/SKILL.md” — but this pointer only works if the agent reads the skill, which it doesn’t.

4. Token budget tension. The original LibreChat artifact instructions + shadcn supplement total ~3,000 words. FORGE.md has a ≤1,500 word budget and is already near capacity. We cannot simply paste the full instructions into FORGE.md.

Key constraint: artifacts field

The update-agents.ts script syncs the artifacts field from the master agent to all variants. This field is currently set to "default" in the Agent Builder UI. With Custom Prompt Mode, the value should remain "default" (which enables the artifact UI/renderer) — but the instructions must come from us, not from LibreChat’s built-in injection.

Requirements

R1: Research how LibreChat implements artifacts and why they may not be working

Goal: Confirm the root cause and identify the exact mechanism by which Custom Prompt Mode suppresses LibreChat’s built-in instructions.

Deliverables:

• Documented explanation of the artifacts field values and their effects
• Confirmation of whether the artifacts field value needs to change
• Identification of any other LibreChat config that affects artifact rendering (e.g., artifactMaxSize, feature flags)
• List of the five artifact types LibreChat supports and their rendering requirements

Verification: Root cause is documented and unambiguous.

R2: Update FORGE.md and the Artifacts skill to make sure artifacts work

Goal: Ensure every Forge agent produces valid :::artifact blocks in every conversation, without requiring the agent to proactively read a skill file.

Approach: Add minimal but sufficient artifact instructions to FORGE.md (within the ≤1,500 word budget). The instructions must cover:

• When to use artifacts (trigger criteria)
• The :::artifact directive syntax
• All five type identifiers and their key constraints
• The rule: always provide complete content, no placeholders/ellipses
• A pointer to Forge/Skills/Artifacts/SKILL.md for library details and extended examples

The Artifacts skill should remain the detailed reference (library versions, shadcn components, extended examples) and be updated to complement — not duplicate — the FORGE.md instructions.

Deliverables:

• Updated Forge/Configs/FORGE.md with artifact instructions (within word budget)
• Updated Forge/Skills/Artifacts/SKILL.md to remove duplication with FORGE.md and focus on reference material
• Run /update-agents to propagate changes to all agent variants

Verification: A new conversation with any Forge agent produces a valid artifact when asked to create one (e.g., “Create a simple React counter component”).

R3: Break up the LibreChat Instructions by artifact type to be more token efficient

Goal: The original LibreChat artifact instructions are a monolithic ~3,000 word block. When the model is creating a specific artifact type (e.g., Mermaid), it doesn’t need the React library table or shadcn component list. Restructure the reference material so agents can load only what they need.

Approach: Split Forge/Skills/Artifacts/references/ into per-type reference files:

File	Content
references/types/html.md	HTML type constraints, external script rules, placeholder image syntax
references/types/svg.md	SVG type constraints, viewBox rules
references/types/markdown.md	Markdown type constraints, supported syntax
references/types/mermaid.md	Mermaid type constraints, syntax reference
references/types/react.md	React type constraints, library versions, hook imports, Tailwind rules, shadcn/ui component list

The SKILL.md should list all five types with one-line summaries and point to the per-type files for details.

Deliverables:

• Per-type reference files under Forge/Skills/Artifacts/references/types/
• Updated Forge/Skills/Artifacts/SKILL.md with per-type pointers
• Sidebar entries for new files

Verification: Each reference file is self-contained and sufficient for its artifact type.

R4: Test each type of artifact listed

Goal: Verify that all five artifact types render correctly in LibreChat after the fix.

Artifact types to test:

1. text/html — Single-file HTML page with inline CSS/JS
2. image/svg+xml — SVG image with viewBox
3. text/markdown — Markdown document with headers, lists, code blocks, tables
4. application/vnd.mermaid — Mermaid diagram
5. application/vnd.react — React component with Tailwind styling

Deliverables:

• Before-fix test results (baseline — expected: all fail)
• After-fix test results (expected: all pass)
• Multi-artifact test file (see R5)

Verification: Each artifact type renders in the LibreChat artifact panel without errors.

R5: Use the Playwright MCP Skill for testing and create a multi-artifact test file

Goal: Use the Playwright MCP to visually verify artifact rendering before and after the fix. Create a single test file that exercises all artifact types so the user can see results at a glance.

Approach:

1. Before fix: Navigate to Forge in LibreChat, prompt for each artifact type, capture the artifact panel state via Playwright snapshot
2. After fix: Repeat the same prompts, capture the artifact panel state
3. Multi-artifact test file: Create a markdown file containing one working example of each artifact type using the :::artifact directive syntax, so the user can paste it into a conversation or use it as a reference

Deliverables:

• Playwright test results (before/after snapshots)
• Forge/Projects/Fix_Artifacts/artifact_test.md — multi-artifact test file with all five types
• Test results documented in Fix_Artifacts_State.md

Verification: Playwright snapshots show artifacts rendering in the panel after the fix; multi-artifact test file contains valid examples of all five types.

Success Criteria

#	Criterion	Measured by
1	Root cause identified and documented	R1 deliverable exists and is specific
2	FORGE.md contains sufficient artifact instructions within word budget	Word count ≤1,500; new conversation produces artifacts
3	Artifacts skill complements FORGE.md without duplication	SKILL.md has no overlap with FORGE.md artifact section
4	Per-type reference files exist and are self-contained	Each file covers its type fully
5	All five artifact types render correctly	Playwright test results
6	Multi-artifact test file exists with all five types	File present and valid
7	All agent variants updated	/update-agents run successfully

Out of Scope

• Changing the artifacts field value (unless R1 reveals it must change)
• Modifying LibreChat source code
• Adding new artifact types beyond the five LibreChat supports
• Performance optimization of artifact rendering
• Artifact versioning or persistence