Ingest Design

Usage

/core-skills:ingest-design [handoff name]

Prerequisite

Requires the DesignSync MCP tool (connected to the design project) and the at@auto-task plugin's task-lifecycle skills (/at:*).

Goal

Turn a finished design handoff (authored in a separate design-system project on Claude, "Claude Design") into a ready-for-dev task in this repo, with the spec pulled into attachments - so a later session can implement it. Ingestion only: this skill stops before implementation.

Context

Design decisions and their handoffs originate in a separate Claude Design project. A finished handoff lands there under handoffs/<date>-<topic>/ - a README.md spec plus a self-contained index.html reference. This skill pulls one into a task here.

It reaches Claude Design via the DesignSync MCP tool, so it runs on the main thread - the handoff is pulled local before create-task/clarify-task spawn any subagents.

It does not run the /at:create-task skill: that skill's job is to crystallise an ongoing conversation into scoped intent, but an ingest has no conversation to crystallise — the handoff README.md is the authoritative intent. Running it would try to elicit and restate intent/criteria, exactly what Step 4 forbids. So this skill scaffolds the task file bare (numbering + template per the task convention — no intent elicitation) and hand-seeds the spec-by-reference body itself — a deliberate carve-out from any "always use /at:create-task" project rule, justified because the handoff defines the work.

It still composes clarify-task, which owns the single clarify pass and marking ready-for-dev.

ingest-design owns only what's new: the pull, and the spec-by-reference task shape.

Task files live in the project's task store — tasks/ in the repo by default; .claude/auto-task.config.md (project config, see /at:create-task) can override the location and provide creation/commit recipes. Read the config file if it exists; <task-store> below refers to the resolved location.

Step 1: Select the Handoff

1. DesignSync list_projects → the design-system project.
2. DesignSync list_files → in-flight handoffs are the folders directly under handoffs/ (exclude anything under archive/).
3. Pick one:
   • arg given → match the handoff folder by substring;
   • exactly one in-flight → use it;
   • several → ask the user which (AskUserQuestion).

Step 2: Mint the Task

1. DesignSync get_file the handoff's README.md. Derive a clean, work-naming title from the handoff topic (and H1): strip a leading Handoff: and any chosen-solution detail — name the work, not the solution. E.g. folder …-focus-mode-affordances + H1 "Handoff: … — inset square Carbon edge" → title Focus-mode affordances.
2. Create the task file with type design per the task convention (<task-store>/NNN-slug.md; use the config's create-task recipe if defined) and note the path and NNN.

Step 3: Pull the Handoff into Attachments

For every file under the handoff folder (from list_files):

• get_file it and write to <task-store>/attachments/NNN/<filename> - flat (one task, one handoff).
• If the response is base64 (isBase64), decode before writing.
• get_file caps at 256 KiB. Handoff references should be authored lean + syncable, so this is rare — but if any file returns truncated, do not write the partial file. README.md is the authoritative spec; record a one-line pointer in the task ## Notes to view the reference in Claude Design at handoffs/<folder>/.

Step 4: Seed the Task Body

Point the implementing agent at the spec; don't hand them a restated copy.

• Description → one line: Implement per the design spec - see attachments/NNN/.
• Remove the Acceptance Criteria TODO template - the handoff defines done.
• Remove the Notes TODO template, unless Step 3 left a pixel-reference pointer (keep that). Clarify re-adds Notes only for a load-bearing decision.

Do not restate or summarise the handoff in the task - it is the authoritative attachment (see /at:create-task Guidance).

Step 5: Clarify (Once)

Run /at:clarify-task <task-path>. It surfaces only genuine decisions (nothing a capable agent infers from repo + handoff), lands them as ## Notes bullets, and marks the task ready-for-dev. Do not clarify again.

Step 6: Commit

Commit the task file + its attachments folder into the task store in one commit, subject Ingest <title> design handoff (task/NNN) — using the config's commit recipe if defined. (Clarify in Step 5 already committed the task file; this commit lands the attachments.)

Stop here - implementation is a separate, later step.