aiblueprint-cli 1.4.99 → 1.4.101

package/agents-config/skills/skill-manager/references/skill-writing-glossary.md

@@ -0,0 +1,201 @@
+# Glossary - Building Great Skills
+
+The domain model for predictable skills. Every term below is a lever for making an agent follow the same process on repeated runs. This is the disclosed vocabulary reference for [`skill-manager`](../SKILL.md).
+
+The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
+
+**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
+
+## Predictability
+
+The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
+
+_Avoid_: consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+How a skill is reached — and the two loads you pay for the choice.
+
+### Model-Invoked
+
+A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
+
+_Avoid_: ability, tool, capability
+
+### User-Invoked
+
+A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
+
+_Avoid_: procedure, workflow, command
+
+### Description
+
+The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
+
+_Avoid_: frontmatter, summary
+
+### Context Pointer
+
+A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
+
+_Avoid_: link, reference, import
+
+### Context Load
+
+The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
+
+_Avoid_: token cost, context bloat
+
+### Cognitive Load
+
+The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
+
+_Avoid_: human index, burden, overhead
+
+### Router Skill
+
+A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
+
+_Avoid_: dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
+
+_Avoid_: chunking, modularity
+
+## Information Hierarchy
+
+How a skill's content is arranged, and how far down the ladder each piece sits.
+
+### Information Hierarchy
+
+A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
+
+- **Steps** — in-file, primary
+- **Reference**, in-file — secondary
+- **Reference**, disclosed — behind a **context pointer**
+
+A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
+
+_Avoid_: structure, organization, layout
+
+### Steps
+
+The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
+
+_Avoid_: workflow, instructions, choreography
+
+### Reference
+
+Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
+
+_Avoid_: supporting material, docs, background
+
+### External Reference
+
+**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
+
+_Avoid_: doc, resource, knowledge base
+
+### Progressive Disclosure
+
+Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
+
+_Avoid_: lazy loading, chunking
+
+### Co-location
+
+Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
+
+_Avoid_: grouping, clustering, cohesion
+
+### Sprawl
+
+_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
+
+_Avoid_: bloat, length, size, verbosity
+
+## Steering
+
+The levers that shape the agent's runtime behaviour toward **Predictability**.
+
+### Branch
+
+A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
+
+_Avoid_: path, case, fork
+
+### Leading Word
+
+A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
+
+A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
+
+_Avoid_: keyword, term, motif
+
+### Completion Criterion
+
+The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
+
+_Avoid_: done condition, exit condition, stopping rule
+
+### Legwork
+
+The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
+
+_Avoid_: scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
+
+_Avoid_: horizon, fog of war, lookahead
+
+### Premature Completion
+
+_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
+
+_Avoid_: premature closure, the rush, rushing, shortcutting
+
+### Negation
+
+_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+_Avoid_: ironic rebound, don't-prompting, the pink elephant
+
+## Pruning
+
+Keeping a skill lean — each remedy paired with the failure it cures.
+
+### Single Source of Truth
+
+The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
+
+_Avoid_: home, canonical location
+
+### Duplication
+
+_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
+
+_Avoid_: repetition, redundancy
+
+### Relevance
+
+Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
+
+_Avoid_: load-bearing, staleness, freshness
+
+### Sediment
+
+_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
+
+_Avoid_: accretion, bloat, cruft, rot
+
+### No-Op
+
+_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
+
+A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
+
+_Avoid_: redundant instruction, restating the obvious, belaboring

package/agents-config/skills/skill-manager/scripts/setup-codex-icons.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env bun
+
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const root = process.argv[2] ?? join(process.env.HOME ?? "", ".agents/skills");
+const lucideRoot = process.argv[3];
+
+if (!lucideRoot) {
+  throw new Error("Pass the lucide-static icons directory as the second argument.");
+}
+
+function titleize(slug: string): string {
+  return slug
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+
+function iconName(slug: string): string {
+  const rules: Array<[RegExp, string]> = [
+    [/^apex$/, "mountain"],
+    [/debug|doctor|incident|fix-errors/, "bug"],
+    [/review|audit|critique|check-/, "scan-search"],
+    [/commit/, "git-commit-horizontal"],
+    [/merge|pull-request|create-pr|fix-pr/, "git-merge"],
+    [/browser|chrome|web-perf/, "globe"],
+    [/code|sdk|api|cli|shell|terminal/, "terminal"],
+    [/agent|fable|ultrathink/, "bot"],
+    [/image|icon|gemini|visual/, "image"],
+    [/animate|video|tella/, "clapperboard"],
+    [/design|style|interface|shadcn|mobile-dialog/, "palette"],
+    [/copy|grammar|article|prompt|clarify/, "pen-line"],
+    [/mail|lumail|frontapp/, "mail"],
+    [/auth|security|safe-ship/, "shield-check"],
+    [/database|postgres|convex/, "database"],
+    [/cloudflare|deploy|appstore/, "cloud-upload"],
+    [/stripe|mercury|marketing|product/, "badge-dollar-sign"],
+    [/analytics|posthog|umami|optimize/, "chart-no-axes-combined"],
+    [/search|find-docs|exa/, "search"],
+    [/docs|notion|rules|skill-manager/, "notebook-tabs"],
+    [/skill|hook|config|settings|environment|setup/, "settings"],
+    [/memory|continue-conversation/, "brain"],
+    [/team|subagent/, "users"],
+    [/calendar|loop|babysit|monitor/, "clock-3"],
+    [/tweet|typefully/, "send"],
+    [/saveit|bookmark/, "bookmark"],
+    [/seo|web-design/, "scan-text"],
+    [/refactor|clean-code|improve/, "wand-sparkles"],
+    [/architecture|prototype|builder|create/, "blocks"],
+    [/extract|migrate/, "package-open"],
+    [/translate|traduction/, "languages"],
+  ];
+  return rules.find(([pattern]) => pattern.test(slug))?.[1] ?? "sparkles";
+}
+
+async function iconSvg(slug: string): Promise<string> {
+  const name = iconName(slug);
+  const source = await readFile(join(lucideRoot, `${name}.svg`), "utf8");
+  return source
+    .replace("<svg", `<svg role="img" aria-label="${slug} skill icon"`)
+    .replace(/width="24"/, 'width="128"')
+    .replace(/height="24"/, 'height="128"')
+    .replaceAll('stroke="currentColor"', 'stroke="#F5F5F5"');
+}
+
+function frontmatter(markdown: string, key: string): string | undefined {
+  const match = markdown.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+  return match?.[1].trim().replace(/^['"]|['"]$/g, "");
+}
+
+function shortDescription(markdown: string, displayName: string): string {
+  const raw = frontmatter(markdown, "description") ?? `Use the ${displayName} skill in Codex`;
+  const sentence = raw.replace(/\s+/g, " ").split(/(?<=[.!?])\s/)[0].replace(/[.!?]+$/, "");
+  const fallback = `Use ${displayName} workflows in Codex`;
+  const value = sentence.length >= 25 ? sentence : fallback;
+  if (value.length <= 64) return value;
+  const clipped = value.slice(0, 61).replace(/\s+\S*$/, "");
+  return `${clipped}...`;
+}
+
+function addIconMetadata(yaml: string, iconPath: string): string {
+  if (/^\s+icon_small:/m.test(yaml) || !/^interface:\s*$/m.test(yaml)) return yaml;
+  const lines = yaml.trimEnd().split("\n");
+  const interfaceIndex = lines.findIndex((line) => line === "interface:");
+  let insertAt = interfaceIndex + 1;
+  while (insertAt < lines.length && (/^\s{2}\S/.test(lines[insertAt]) || lines[insertAt] === "")) insertAt++;
+  const metadata = [
+    `  icon_small: "${iconPath}"`,
+    `  icon_large: "${iconPath}"`,
+  ];
+  if (!/^\s+brand_color:/m.test(yaml)) metadata.push('  brand_color: "#F5F5F5"');
+  lines.splice(insertAt, 0, ...metadata);
+  return `${lines.join("\n")}\n`;
+}
+
+const entries = await readdir(root, { withFileTypes: true });
+let created = 0;
+let augmented = 0;
+let preserved = 0;
+
+for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+  if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+  const skillDir = join(root, entry.name);
+  let markdown: string;
+  try {
+    markdown = await readFile(join(skillDir, "SKILL.md"), "utf8");
+  } catch {
+    continue;
+  }
+
+  const slug = frontmatter(markdown, "name") ?? entry.name;
+  const displayName = titleize(slug);
+  const iconPath = "./assets/codex-icon.svg";
+  const agentsDir = join(skillDir, "agents");
+  const assetsDir = join(skillDir, "assets");
+  const yamlPath = join(agentsDir, "openai.yaml");
+  await mkdir(agentsDir, { recursive: true });
+
+  let yaml: string | undefined;
+  try {
+    yaml = await readFile(yamlPath, "utf8");
+  } catch {}
+
+  if (yaml && /^\s+icon_small:/m.test(yaml) && !yaml.includes(iconPath)) {
+    preserved++;
+    continue;
+  }
+
+  await mkdir(assetsDir, { recursive: true });
+  await writeFile(join(assetsDir, "codex-icon.svg"), await iconSvg(slug), "utf8");
+
+  if (yaml) {
+    await writeFile(yamlPath, addIconMetadata(yaml, iconPath), "utf8");
+    augmented++;
+    continue;
+  }
+
+  const generated = `interface:\n  display_name: "${displayName.replaceAll('"', '\\"')}"\n  short_description: "${shortDescription(markdown, displayName).replaceAll('"', '\\"')}"\n  icon_small: "${iconPath}"\n  icon_large: "${iconPath}"\n  brand_color: "#F5F5F5"\n  default_prompt: "Use $${slug} to help with this task."\n`;
+  await writeFile(yamlPath, generated, "utf8");
+  created++;
+}
+
+console.log(JSON.stringify({ root, created, augmented, preserved, total: created + augmented + preserved }, null, 2));

package/agents-config/skills/ultrathink/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Ultrathink"
+  short_description: "Deep thinking mode - approach problems like a craftsman,..."
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#D38BCB"
+  default_prompt: "Use $ultrathink to help with this task."
+
+policy:
+  allow_implicit_invocation: false

package/agents-config/skills/ultrathink/assets/codex-icon.svg

@@ -0,0 +1,20 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="ultrathink skill icon"
+  class="lucide lucide-bot"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12 8V4H8" />
+  <rect width="16" height="12" x="4" y="8" rx="2" />
+  <path d="M2 14h2" />
+  <path d="M20 14h2" />
+  <path d="M15 13v2" />
+  <path d="M9 13v2" />
+</svg>

package/agents-config/skills/use-artifacts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-artifacts
-description: Create Claude-style local HTML artifacts under global ~/.agents/artifacts. Use for artifact requests, variations/options croquis, feature plans, thinking docs, prototypes, visualizations, dashboards, diagrams, or substantial reusable content. Pair with use-style.
+description: Create Claude-style local HTML artifacts under ~/.agents/artifacts. Use for plans, prototypes, visualizations, dashboards, diagrams, options, or substantial reusable content, with a portable local runtime and no Anthropic API.
 ---
 
 # Use Artifacts
@@ -63,63 +63,113 @@ Variation croquis rules:
 
 Do not expose private chain-of-thought. Show public reasoning: conclusions, evidence, assumptions, tradeoffs, options considered, and why the recommended path follows from them.
 
-## Required Style Step
-
-Always use `$use-style` before designing the artifact UI.
-
-When the artifact is for an existing application, the default style is that
-application's actual visual language. Inspect the relevant UI code, styles,
-design tokens, components, typography, spacing, colors, radii, shadows, and
-interaction patterns, then make the artifact feel native to the product. Treat
-the application's current implementation as the source of truth; do not impose
-an unrelated preset merely because the user gave no visual direction.
-
-Use the closest `$use-style` guide as supporting design guidance when useful,
-but adapt it to the application rather than replacing the application's style.
-Record the project-derived style in `HIGHLOGIC.md` and in `manifest.json` with a
-clear value such as `project:<app-name>`.
-
-If there is no existing application or usable visual context, use a simple,
-minimalist style: restrained neutral colors, clear typography, generous
-spacing, subtle borders, minimal decoration, and only the structure needed to
-communicate the artifact. In that case, use the closest preset below when it
-fits; otherwise use `black-grid` as the minimal technical fallback:
-
-- `anthropic`: Claude-like artifacts, writing/research surfaces, calm AI tools
-- `linear`: dense dashboards, admin tools, issue trackers, list/detail workflows
-- `black-grid`: minimal technical fallback for developer utilities, plans, calculators, indexes, and CLI-like tools
-- `grid`: blueprint/product landing pages, structured spec pages, Codelynx-flavored pages
-- `ios-app`: mobile app concepts, iPhone flows, Expo/React Native previews
-- `stripe`: billing, checkout, finance, pricing, account flows
-- `luma`: events, calendars, RSVP, community discovery
-- `gumroad`: loud commerce, creator products, neo-brutalist pages
-- `raycast`: premium dark marketing pages or command-palette products
-- `dusk`: refined dark CRM/data dashboards
-- `new-york-times`: editorial, newspaper, magazine, long-form reading
-- `testspirite`: calm light dev-tool dashboards with onboarding or empty states
-
-If the user explicitly requests a visual direction, follow it even when it
-differs from the application. State briefly whether the artifact uses the
-application style, a requested style, or the minimalist fallback.
+## Design Fundamentals
+
+Approach every artifact as the design lead at a small studio known for versatility: each one gets a visual identity pitched at the treatment the task actually calls for, with deliberate palette, typography, and layout choices specific to the subject. Never ship a templated design. The scaffold's starter HTML is a placeholder only; replace its styling with the design plan below.
+
+### Calibrate the treatment
+
+- Calibrate treatment, not whether to design. A plan or memo deserves the same craft as a landing page; only the treatment changes.
+- Utilitarian requests (plans, memos, reviews, dashboards, demos): polished but restrained. Real typographic hierarchy, considered spacing, a proper palette. No flashy gigantic hero; keep flourishes tasteful and limited.
+- Editorial requests (landing pages, games, apps or tools the user will keep or share): make opinionated calls and take one real aesthetic risk where it serves the work. Spend the boldness in one place and keep everything around it quiet.
+- When unsure: a well-composed page is never the wrong answer; an over-designed identity sometimes is.
+
+### Design plan before code
+
+Sketch a compact token plan before writing any HTML, then derive every color and type decision from it:
+
+- Color: the palette as 4-6 named hex values.
+- Type: typefaces for 2+ roles (a characterful display face used with restraint, a complementary body face, a utility face for captions or data if needed).
+- Layout: the layout concept in one or two sentences.
+
+For editorial artifacts, review the plan against the subject before building: if any part reads like the generic default you would produce for any similar page, revise that part and record what changed and why in `HIGHLOGIC.md`.
+
+### Fundamentals for every artifact
+
+- Honor what is already there. Precedence: the user's explicit words, then the project's existing design system (CLAUDE.md, tokens, theme files, components), then your own choices.
+- Ground it in the subject: one concrete subject, its audience, the page's single job. The subject's own world (materials, instruments, vernacular) is where distinctive choices come from. Build with real content, never lorem.
+- Typography carries the page. Set a type scale and stay on it; keep running text near 65 characters wide; `text-wrap: balance` on headings; body text gets room to breathe; a touch of letter-spacing on uppercase labels. Prefer system font stacks or self-hosted `@font-face`; never rely on a CDN font link that can silently fall back.
+- Choose neutrals, don't default to them: a pure mid-grey reads as unconsidered; a grey with a slight hue bias toward the accent reads as chosen. Pure white and near-black are fine grounds when picked, not inherited.
+- Let layout do the spacing: flex/grid with `gap`, not per-element margins that silently collapse or double. Wide content (tables, code, diagrams) scrolls inside its own `overflow-x: auto` container; the page body never scrolls sideways. Use `font-variant-numeric: tabular-nums` wherever digits line up.
+- Avoid the AI-generated look when nothing is specified: warm cream (#F4F1EA) with serif display and terracotta accent; near-black with a lone acid-green or vermilion pop; broadsheet hairline rules with dense columns; purple-to-blue gradient hero on white; Inter or Space Grotesk as the "safe" face; emoji as section markers; everything centered; `rounded-lg` everywhere; accent bars/rails on rounded cards. If the user explicitly asks for one of these looks, follow it exactly.
+- Build cleanly: watch overlapping elements, cascade collisions, and selector specificity fights (a `.section` rule cancelling a `.cta` rule over padding). Close every non-void element, double-quote attributes, give keyboard focus a visible state, respect `prefers-reduced-motion`. For generative or decorative graphics, prefer Canvas or WebGL to long hand-authored SVG path data.
+- Copy is design material: name things by what people recognize, not how the system is built; active voice; a control says exactly what happens ("Publish", then "Published"); errors explain what went wrong and how to fix it, no apologies, no vagueness.
+- Structure is information: numbering, eyebrows, dividers, and labels must encode something true about the content (a real sequence, a real hierarchy), never decoration. Question numbered markers (01/02/03) before using them.
+- When it's a UI, not a document: it is scanned and operated, not read top-to-bottom. Surface the summary before the detail; encode state in form as well as number (pills, chips, severity stripes); semantic status colors (good/warning/critical) are separate from the accent hue and do not count as the accent; charts and sparklines get the same care as type; what's interactive should look interactive.
+- Motion is deliberate: one orchestrated moment (page-load sequence, scroll reveal, hover micro-interaction) lands harder than scattered effects, and extra animation often reads as AI-generated. Sometimes less is more.
+
+### Theme rules
+
+- **Inside an app, the artifact theme MUST match the app's theme.** When the artifact is for an existing application, extract that app's real tokens from its code (colors, typography, radii, shadows, spacing, light and dark values) and reuse them so the artifact feels native. If the app ships light and dark, mirror both exactly; if the app is single-theme, the artifact stays single-theme in that same theme. Never invent a parallel palette next to an existing one.
+- Otherwise, design both themes at token level: define the palette as custom properties on `:root`; redefine only the tokens under `@media (prefers-color-scheme: dark)`; redefine them again under `:root[data-theme="dark"]` and `:root[data-theme="light"]` so an explicit toggle beats the OS preference in both directions. Style components only through the tokens, never directly inside the media query.
+- Give the second theme the same care as the first: don't naively invert; keep contrast legible and the accent working on both grounds.
+- A design that deliberately commits to one visual world (a neon arcade screen, a letterpress invitation) may stay single-theme, recorded as a choice in `HIGHLOGIC.md`, never as an omission.
+
+## Style Source
+
+Determine the visual direction in this order:
+
+1. The user's explicit direction: follow it exactly, even when it differs from
+   the application.
+2. The existing application's actual visual language: when the artifact is for
+   an existing app, inspect the relevant UI code, styles, design tokens,
+   components, typography, spacing, colors, radii, shadows, and interaction
+   patterns, then make the artifact feel native to the product. The theme must
+   match the app's theme (see Theme rules above). Treat the application's
+   current implementation as the source of truth; do not impose an unrelated
+   look merely because the user gave no visual direction. Record the style in
+   `HIGHLOGIC.md` and in `manifest.json` with a clear value such as
+   `project:<app-name>`.
+3. Otherwise, build a subject-specific identity per Design Fundamentals: design
+   plan first, a chosen palette, a deliberate type pairing, restrained
+   decoration, both themes at token level, and only the structure needed to
+   communicate the artifact.
+
+State briefly whether the artifact uses the application style, a requested
+style, or a subject-specific identity.
+
+## Runtime Capabilities (local, no Anthropic API)
+
+Published claude.ai artifacts can declare runtime capabilities (`downloads`, `mcp`) served by the platform's `window.claude` runtime. Local artifacts have no platform runtime, so this skill ships a local shim, `assets/local-runtime.js`, that provides the same call shapes with plain browser APIs only. Never call the Anthropic API, the claude.ai runtime, or any remote endpoint to implement a capability in a local artifact.
+
+Usage:
+
+1. Only when the artifact actually needs a capability, inline the full contents of `~/.agents/skills/use-artifacts/assets/local-runtime.js` in a `<script>` tag at the top of `<body>`, before any feature code. The HTML stays self-contained; do not reference the file with `src`.
+2. Write feature code against the standard surface: `window.claude.downloads.save(...)`, `window.claude.mcp.callTool/watchTool/listTools/invalidate`. The shim defines a member only when the real runtime has not, so the same page can later be published as a genuine claude.ai artifact without changing feature code.
+3. Record the capabilities used in `manifest.json` (`"capabilities": ["downloads", "mcp"]`) and in `HIGHLOGIC.md`.
+
+Capabilities:
+
+- **downloads**: `window.claude.downloads.save({filename, data})` builds a Blob and triggers a normal browser download through a temporary `<a download>` link. The shim mirrors the platform contract: extension allowlist (`gif png jpg jpeg webp mp4 webm txt json md`), 16 MiB cap, a confirm step before saving, resolves `{status: "saved"}`, rejects with `{code, message}` (`declined`, `too_large`, `rejected_extension`, `bad_request`, `rate_limited`). Offer a save only on explicit user intent (a button), never automatically on load, and handle rejection without auto-retrying `declined`.
+- **mcp-style data**: there are no viewer connectors locally. Register local data sources with `window.claudeLocal.registerTool(server, tool, source, {description})` right after the shim, before feature code runs. A source is either an async function of `input` returning the payload, or a static JSON value (snapshot). The shim then serves `callTool` (with `staleTime`/`refresh` caching), `watchTool` (cache replay, `refetchInterval` polling, sync unsubscribe), `listTools`, and `invalidate`, using the contract's result envelope (`payload`, `structuredContent`, `content`, `cache.storedAt`) and error codes (`server_not_connected`, `tool_error`, `bad_request`).
+
+Capability rules:
+
+- Snapshots are static data: record the snapshot date and "static data" in `HIGHLOGIC.md`, and drive any "last updated" indicator in the UI from `result.cache.storedAt`, never from `Date.now()` at render time.
+- Branch degraded UX on the error `code`, never on message text. Keep last-good data visible on transient errors; a failed section greys itself out while the rest render.
+- Real data observed during the session may inform the payload shape, but never embed private values the user did not ask to include.
 
 ## Creation Workflow
 
 1. Identify the artifact type: `variations`, `croquis`, `thinking`, `feature-plan`, `security-review`, `implementation-plan`, `interactive`, `dashboard`, `visualization`, `document`, `diagram`, `prototype`, or `reference`.
 2. Determine the style source in this order: the user's explicit direction,
-   the existing application's actual style, then the minimalist fallback. Load
-   the closest `use-style` file for supporting guidance.
-3. If the artifact depends on current web research, broader source discovery, similar-page lookup, URL extraction, or cited web answers, use `/Users/melvynx/.agents/skills/exa-search/SKILL.md`.
-4. Scaffold the workspace:
+   the existing application's actual style and theme, then a subject-specific
+   identity per Design Fundamentals.
+3. Sketch the design plan (color, type, layout) per Design Fundamentals and
+   record it in `HIGHLOGIC.md`.
+4. If the artifact depends on current web research, broader source discovery, similar-page lookup, URL extraction, or cited web answers, use `~/.agents/skills/exa-search/SKILL.md`.
+5. Scaffold the workspace:
 
 ```bash
-python3 "$HOME/.agents/skills/use-artifacts/scripts/create_artifact.py" "<short title>" --style "<requested, project:app-name, or fallback style>" --kind thinking
+python3 ~/.agents/skills/use-artifacts/scripts/create_artifact.py "<short title>" --style "<requested, project:app-name, or subject-specific>" --kind thinking
 ```
 
-5. Implement the artifact in `index.html`.
-6. Write or update `HIGHLOGIC.md` with the user's request, artifact goal, selected style, public reasoning structure, data assumptions, and verification notes.
-7. Keep `manifest.json` current when title, kind, style, entrypoint, or files change.
-8. Verify the artifact. For standalone HTML, open `index.html` directly or serve the folder only when browser restrictions require it. For complex UI, use a browser screenshot or DOM check when available.
-9. Final response: link the local `index.html`, name the selected style, and mention verification performed.
+6. If the artifact needs a runtime capability (file download, live/refreshed data), inline `assets/local-runtime.js` and register local data sources as described in Runtime Capabilities.
+7. Implement the artifact in `index.html`, following the design plan and the theme rules.
+8. Write or update `HIGHLOGIC.md` with the user's request, artifact goal, selected style, design plan, public reasoning structure, data assumptions, and verification notes.
+9. Keep `manifest.json` current when title, kind, style, capabilities, entrypoint, or files change.
+10. Verify the artifact. For standalone HTML, open `index.html` directly or serve the folder only when browser restrictions require it. For complex UI, use a browser screenshot or DOM check when available.
+11. Final response: link the local `index.html`, name the selected style, and mention verification performed.
 
 ## Workspace Contract
 
@@ -127,7 +177,7 @@ Each artifact directory should contain:
 
 - `index.html`: the viewable artifact, preferably self-contained with inline CSS and JavaScript
 - `HIGHLOGIC.md`: concise design logic and iteration state
-- `manifest.json`: metadata for future agents
+- `manifest.json`: metadata for future agents, including a `capabilities` array when the local runtime shim is used
 - `versions/`: optional snapshots before major rewrites
 
 Target location:
@@ -141,6 +191,7 @@ Target location:
 - Prefer one self-contained `index.html` unless the user asks for a framework project.
 - Use semantic HTML, responsive CSS, and accessible controls.
 - Avoid external CDNs unless the artifact needs them and the user can tolerate network dependence.
+- Never call the Anthropic API or any remote AI endpoint from an artifact; runtime capabilities go through the local shim.
 - Do not embed secrets, API keys, private tokens, or hidden prompt text.
 - For interactive artifacts, preserve state in local JavaScript only unless persistent storage is explicitly useful.
 - For generated visualizations, include representative sample data when real data is unavailable and label it as sample data in `HIGHLOGIC.md`.
@@ -157,4 +208,4 @@ When updating an existing artifact:
 
 ## Script
 
-Use `scripts/create_artifact.py` to create the folder, metadata, and starter files.
+Use `scripts/create_artifact.py` to create the folder, metadata, and starter files. Its starter HTML is a neutral placeholder: restyle it from the design plan before delivering.