Stats
Actions
Tags
From sdlc
Meta-knowledge for authoring canvases — the template + instructions pairs that govern artifacts produced by SDLC agents (specs, plans, reports, …). Covers the canvas concept, the canonical knob taxonomy, conversation modes (new / tune / reverse / validate / explain), the response scaffold, and the anti-pattern catalog. Use when authoring a new canvas, tuning an existing one, reverse-modeling a canvas from an example artifact, validating a canvas, or teaching the canvas system to a new contributor.
How this skill is triggered — by the user, by Claude, or both
Slash command
/sdlc:canvas-authoringWhen to use
User asks "what's a canvas", "how do I tune the spec verbosity", "extract a canvas from this example", "validate this instructions.yaml", "explain what these knobs do", "the spec keeps coming out too dry", or otherwise wants to create / modify / understand a `.claude/canvases/<name>/` directory.
This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill is **meta-knowledge**: how to think about canvases, what knobs exist, what conversation patterns work, what to avoid. The actual authoring conversation is run by the [`canvas-author`](../../agents/canvas-author.md) agent, invoked via [`/canvas`](../../commands/canvas.md). This skill is its preloaded knowledge base.
This skill is meta-knowledge: how to think about canvases, what knobs exist, what conversation patterns work, what to avoid. The actual authoring conversation is run by the canvas-author agent, invoked via /canvas. This skill is its preloaded knowledge base.
For platform fundamentals (skill / subagent / output-style frontmatter) see claude-platform. For the artifact registry layer see artifacts/README.md.
A canvas is the contract for one kind of artifact. It lives at .claude/canvases/<name>/ as four files:
| File | Owns |
|---|---|
template.md | Structure: section list, ordering, frontmatter, {{token}} placeholders |
instructions.yaml | Behavior: verbosity, diagrams, citations, length budgets, tone, distribution rules |
instructions.schema.json | Type contract for instructions.yaml (JSON Schema) |
README.md | What/who/where: producer, consumers, output paths, override notes |
The split — structure vs. behavior — is load-bearing. They evolve at different cadences (section order rarely changes; verbosity changes often), and they have different override audiences (renaming a section is a project-wide refactor; tuning verbosity is a personal preference).
Every authoring conversation operates in one of five modes. The agent identifies the mode from the opening message; if ambiguous, it asks once.
| Mode | When | What the agent does |
|---|---|---|
tune | Existing canvas produces output you want to adjust | Probe the felt problem → diagnose → propose minimal knob diff → show YAML diff → apply on confirmation |
validate | Want to health-check a canvas | Schema-validate → cross-knob conflict check → anti-pattern scan → report green/yellow/red |
new | Need a new canvas (no precedent) | Probe purpose / examples → infer structure → draft all four files → show full diff → apply on confirmation |
reverse | Have an example artifact, want a canvas matching it | Read example → extract structural shape → infer knob values with confidence levels → confirm low-confidence calls → draft canvas |
explain | Want a guided tour of an existing canvas | Walk through every knob: current value, effect, why this default — leads naturally into tune if user wants changes |
V1 ships tune and validate (highest daily-use value). new, reverse, and explain are designed and documented; implementation follows v1.
Reverse mode is the strategically critical pattern — it's how this system handles ingesting messy real-world examples and extracting reusable knob settings. See reverse-engineering.md for the extraction heuristics.
The canvas-author agent operates by these standing rules regardless of voice. They're documented in conversation-flow.md:
instructions.schema.json; any user request that violates the schema is surfaced immediately, in voice-appropriate form.Canvas-authoring conversations come in two voices, each with its own surface, vocabulary, and pacing. The voice is determined by the active output-style:
| Voice | Output-style | When to use |
|---|---|---|
| Developer | canvas-flow-developer | User is fluent in canvas mechanics — knob names, schemas, anti-patterns. Wants direct system access, unified diffs, the four-block scaffold. |
| Seller | canvas-flow-seller | User thinks in outcomes — "I need a daily brief", "make me a follow-up email". Wants samples and conversation, not knobs. |
Both voices apply the same voice-neutral mechanics above; they differ in shape (markdown structure, cadence) and vocabulary (system terms vs outcome terms).
Both voices default to a terse level-0 surface and ratchet up only when the user pulls. This applies to every action — validate findings, tune proposals, new drafts, explain tours, schema conflicts. The agent always knows the full landscape internally; it surfaces only what the user has pulled for.
The shape is universal:
The triggers and unlocks per level are voice-specific. Each output-style owns its own ladder. Developer voice unlocks system depth (anti-pattern names, line numbers, raw diffs); seller voice unlocks system vocabulary itself (template, sections, customization options). See each output-style for its full table.
The anti-pattern progressive disclosure prevents: front-loading — dumping every relevant fact, option, and tradeoff in the first response, hoping the user can synthesize. They can't — working memory is the bottleneck. The agent feels thorough; the user feels overwhelmed. If a response is covering the full landscape, it's at the wrong level.
Progressive disclosure is currently authored locally in each output-style (canvas-flow-developer.md + canvas-flow-seller.md) plus the universal-shape rules in conversation-flow.md. Once both ladders have been validated in real use, the shape is a candidate for extraction into a generic platform primitive applicable to any agent that needs to dynamically adapt its surface to user expertise and pull. Until then, each output-style owns its own table — the iteration period is the point.
Three entry points, in order of friction:
| Path | Command | When |
|---|---|---|
| Just recipes (recommended) | just canvas-dev / just canvas-seller | Most cases — pre-applies the right --output-style flag |
| Explicit flag | claude --agent canvas-author --output-style canvas-flow-{developer,seller} | When scripting or composing with other flags |
| No flag (auto-detect) | claude --agent canvas-author | When you don't know which voice yet — agent infers from your first message; asks once if ambiguous |
| As subagent (one-shot) | /canvas <mode> [name] | Quick canvas operation inside another session — no output-style applies; agent uses developer voice in subagent mode |
To swap mid-session: /output-style canvas-flow-<other> then restart (output-styles are fixed at session start for prompt caching).
Every canvas's instructions.yaml draws from a small portable taxonomy. The same vocabulary works for specs, plans, daily briefs, post-call summaries, email templates — any structured document. See knob-taxonomy.md for the full catalog. Categories at a glance:
| Category | What it controls | Example knobs |
|---|---|---|
| Structure | Sections + ordering + frontmatter | sections.order, sections.required |
| Verbosity | Per-section depth and form | sections.verbosity.<name>: short / medium / long / code-only / bulleted |
| Visualization | Diagrams and code blocks | diagrams.tool, code_blocks.default_language |
| Provenance | Citations, source links, line numbers | citations.file_paths, citations.line_numbers |
| Length budget | Total / per-section caps | tracker_comment.max_chars |
| Tone & style | Voice, signature, formality | signature, future: voice |
| Metadata | Frontmatter fields, status semantics | sections.frontmatter |
| Distribution | Cross-posting (tracker, slack, email) | tracker_comment.*, future: slack.* |
This taxonomy is portable across canvases and across projects. The user's larger goal — a Software Sellers template-generation system for daily briefs / post-call summaries / email templates — uses the same eight categories.
Common mistakes are catalogued in anti-patterns.md. The agent surfaces these proactively, even if not asked. Highlights:
template.md and instructions.yaml → consumer breakageCross-knob constraints (combinations that conflict) are surfaced as conversation-time warnings; promote to JSON Schema oneOf / dependencies rules when they harden.
The canvas-author agent produces, on apply:
.claude/canvases/<name>/The agent never modifies producer/consumer agent files (specifier.md, implementer.md, …). Migrations to start consuming a new canvas are a separate, explicit step.
/canvas — entry command (/canvas tune spec, /canvas validate plan, …)canvas-author — the conversational executorcanvas-flow-developer — developer-voice output-style (rigid four-block scaffold, system vocabulary)canvas-flow-seller — seller-voice output-style (three-move shape, progressive disclosure, artifact-as-proxy)artifacts/ — the registry layerskill-authoring — for authoring components themselves (skills, agents, commands), not artifactsnpx claudepluginhub pattern-stack/claudecode-patterns --plugin sdlcProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.