Working With AI
AI workflow format reference
Understand Skafold project seeds, published AI Context snapshots, and computer-use editing.
Skafold uses a project seed for new projects and read-only AI Context for reference. Existing projects are edited through the signed-in editor.
New-project seed
A project seed creates a new project:
{
"format": "skafold-project-seed",
"schemaVersion": "1.0",
"project": {},
"pages": []
}
It may include:
generator: provider, model, skill version, and generation time.project: project name, summary, goals, audiences, constraints, delivery notes, and structured brief lists.pages: routes or application screens withid,name,parentId,path, editablepurpose, and Section placements.globalSections: reusable definitions and organisational dividers.journeys: focused actor-led paths.architecture: implementation items and direct relationships.design: visual direction and system guidance.assumptionsandopenQuestions.
Seeds may include bounded node positions and semantic connector handles in the
optional root layout field. Omit node width and height: Skafold uses native
widths and content-based heights. Seeds exclude raw canvas and internal application state.
Put page-specific requirements in purpose (Page context), relevant section
guidance, or Documentation brief lists. Page goal, audienceIntent, primaryCta,
contentRequirements, dataCmsNeeds, constraints, seoNotes, interactionNotes,
and aiHandoffNotes are legacy snapshot fields without current editor controls;
do not include them in new seeds. Project-level goals, audiences and constraints
remain supported.
Published AI Context
An existing project’s bearer URL returns:
{
"format": "skafold-ai-context",
"schemaVersion": "1.0",
"contextRevision": 4,
"contextHash": "sha256:…",
"publishedAt": "2026-08-21T03:00:00Z",
"project": {},
"protocol": {},
"frames": {}
}
Each semantic category has a hash and data. The protocol object identifies the snapshot's workflow version. In protocol 1.14, acceptedFrameUpdateVersions is an empty array: no existing-project update format is accepted.
The snapshot can contain legacy category names and page planning fields even though the editor now has Documentation, Structure, and Pages. It can also report node dimensions as read-only geometry. These are not new-seed authoring fields. It reflects the last publication and may omit content available in the editor. Inspect the current editor before changing it; absence from the snapshot is never a deletion instruction.
Existing-project editing
Use a computer-use agent for focused edits, respecting collaboration and normal saving. Without browser controls, an AI can propose manual edits. Bulk update files are retired. A substantial rebuild uses a validated seed to create a separate project with its own history, leaving the original intact.
IDs and references
Use stable lowercase kebab-case IDs.
- A page
parentIdreferences another declared page. - A page placement
globalSectionIdreferences a non-divider item inglobalSections. - A reusable definition
groupIdreferences akind: "separator"item. - A journey step
pageIdreferences a declared page. - Architecture relationships reference declared architecture items.
- IDs are unique within their collection.
Preserve IDs for unchanged items. Stable IDs let Skafold retain relationships and distinguish edits from removal and recreation.
Structure and Page Hierarchy
Structure owns the complete page list, identity, paths, purpose, and direct hierarchy. The Pages workspace owns page planning and ordered placements; JSON retains the Page Hierarchy category for compatibility.
A seed declares pages and their editable context together. A newly created page may begin without section placements.
Sections and placements
Define reusable components once in globalSections. Keep shared layout, contentSchema, notes, tags, buildGuidance, grouping, and definition status on that definition.
The section layout is a visual pattern label or ID, separate from the root layout that positions canvas nodes. The assistant packages and protocol 1.14 include a generated pattern catalogue with starter field recipes. Copy and adapt the intended fields into contentSchema; seed imports do not generate fields from the layout. Field edits do not change the pattern. Plain Base blocks support an intentionally empty structure.
AI Context records the project's selected patterns and actual fields, not a live connection to starter recipes. Each published snapshot pins its protocol references. Update AI Context to use current references; older snapshots and immutable resources remain unchanged.
Page placements contain id, name, globalSectionId, optional instanceName, and optional independent placement statusColor.
Accepted explicit status colours are blue, purple, amber, red, and green. Omit status when not started. Do not generate legacy gray or completed fields.
Collaboration
Computer-use agents inspect each target immediately before editing, respect locks and read-only controls, and verify saving. A conflict requires rereading the target; an agent must not force an older snapshot over current content. Changes use the signed-in account and normal workspace history.