@yargote/artifacts-cli 0.1.0-beta.1 → 0.1.0-beta.3

package/skills/artifacts-design/references/catppuccin.md

@@ -0,0 +1,38 @@
+# Catppuccin roles
+
+The starter maps the official [Catppuccin palette](https://github.com/catppuccin/palette/blob/main/palette.json) to semantic tokens. Latte serves the light theme and Mocha the dark theme. Blue is the Artifacts accent.
+
+| Token | Role | Latte (light) | Mocha (dark) |
+| --- | --- | --- | --- |
+| `--page` | Page background | Base `#eff1f5` | Mantle `#181825` |
+| `--surface` | Strip, table, or panel | White `#ffffff` | Base `#1e1e2e` |
+| `--sunken` | Table header, hover, code | Mantle `#e6e9ef` | Crust `#11111b` |
+| `--line` | Hairline divider | Surface 0 `#ccd0da` | Surface 0 `#313244` |
+| `--control` | Input and button boundary | Overlay 1 `#8c8fa1` | Overlay 0 `#6c7086` |
+| `--fg` | Main text | Text `#4c4f69` | Text `#cdd6f4` |
+| `--muted` | Secondary text and labels | Subtext 1 `#5c5f77` | Subtext 0 `#a6adc8` |
+| `--accent` | Focus, selection, primary fill | Blue `#1e66f5` | Blue `#89b4fa` |
+| `--accent-ink` | Links and accent text | `#1957d0` | Blue `#89b4fa` |
+| `--ok` / `--ok-ink` | Success mark / text | Green `#40a02b` / `#307820` | Green `#a6e3a1` |
+| `--warn` / `--warn-ink` | Warning mark / text | Yellow `#df8e1d` / `#915c13` | Yellow `#f9e2af` |
+| `--bad` / `--bad-ink` | Error mark / text | Red `#d20f39` / `#b20d30` | Red `#f38ba8` |
+
+The Latte ink values darken the palette color so pill text reaches 4.5:1 on its soft background. Each `*-soft` token mixes 14 % of its color into `--surface`, so it adapts to both themes without a second definition.
+
+Every text token reaches 4.5:1 on `--page` and `--surface` in both themes. `--control` reaches 3:1 for input boundaries. `--line` is decorative and must not be the only boundary of a control.
+
+## Chart series
+
+Use these in order after Blue. Give each series a direct label or marker as well as a color.
+
+| Series | Latte | Mocha |
+| --- | --- | --- |
+| 1 | Blue `#1e66f5` | Blue `#89b4fa` |
+| 2 | Peach `#fe640b` | Peach `#fab387` |
+| 3 | Teal `#179299` | Teal `#94e2d5` |
+| 4 | Mauve `#8839ef` | Mauve `#cba6f7` |
+| 5 | Yellow `#df8e1d` | Yellow `#f9e2af` |
+
+Mauve is a data color only, never the accent.
+
+The palette's license notice is retained in [third-party notices](../THIRD-PARTY-NOTICES.md).

package/skills/artifacts-design/references/interface-checks.md

@@ -0,0 +1,50 @@
+# Interface checks for HTML artifacts
+
+Use these checks for visual authoring and review. Apply only the checks relevant to the artifact. Keep the requested content and behavior central.
+
+## Accessible, resilient interfaces
+
+- Use semantic headings, buttons, links, and tables. Label controls and icon buttons. Give meaningful images alternative text.
+- Make every action keyboard accessible. Keep focus visible and unobscured. Restore focus after dismissing overlays.
+- Announce asynchronous status changes without interrupting reading. Pair errors with a useful next action.
+- Provide click and keyboard alternatives for gestures. Keep essential information available without hover.
+- Preserve zoom and paste. Associate input labels with their controls. Use suitable input types.
+- Support narrow viewports, empty results, and long content. Let flex children shrink. Wrap text before hiding overflow.
+- Reserve image dimensions. Defer below-fold media. Batch layout reads and writes. Paginate or virtualize long lists when needed.
+- Use tabular numerals for comparisons and `Intl` for localized values. Keep units attached to numbers.
+- Set native controls to the document's color scheme. Keep hover, active, and focus states distinguishable.
+- Avoid motion that blocks interaction. Provide pause controls for extended autoplay and a reduced-motion alternative.
+
+## Motion and interaction detail
+
+Adapt motion to repetition and purpose. Frequent actions should respond immediately. Add animation when it explains a state change or spatial relationship.
+
+Prefer interruptible CSS transitions with named properties. Start around 100 to 160 ms for press feedback and 125 to 250 ms for small overlays. Use an ease-out curve for entry. Anchor popover transforms to their trigger and center modal transforms.
+
+Prefer `transform` and `opacity` for movement. Avoid `transition: all`, large blur effects, and entrance scaling from zero. Keep feedback subtle enough that labels remain readable.
+
+Under `prefers-reduced-motion: reduce`, remove decorative movement and retain immediate state feedback. Gate hover effects with `(hover: hover) and (pointer: fine)`. Do not make content wait for an entrance animation.
+
+## Adapt to the Artifacts sandbox
+
+Keep input-driven calculations in document memory. Use labeled controls without a form submission workflow. Do not imply that an in-document control saves a retained revision or publishes an artifact.
+
+Keep filters and tabs local to the document. Do not depend on host URL synchronization, router packages, persistent storage, network requests, or remote fonts. Embed fonts and other required assets as `data:` URIs within the snapshot budget.
+
+## Check the result
+
+When browser tools are available, inspect the generated document at a narrow viewport around 375 px and a wide viewport around 1280 px, or the user's requested sizes. Verify that body content fits, labels remain legible, and only intentionally wide tables or code regions scroll locally. Check the artifact itself rather than relying on the surrounding application's appearance.
+
+Exercise every distinct action with keyboard and pointer input. Observe the expected output or state change, including input errors, reset behavior, and empty filter results where applicable. Confirm that focus stays visible and follows opened and dismissed overlays. Check reduced motion when animation is present. Inspect the console for runtime errors and confirm that required content and controls work without external requests.
+
+Finish when each relevant check passes or an unavailable check is identified. Fix observed failures and repeat affected checks. Source inspection establishes markup and script intent; report browser behavior as verified only after observing it.
+
+For a requested audit, identify each issue by element or source location and state its correction. Distinguish source inspection from browser verification. Do not turn ordinary artifact delivery into an unsolicited audit report.
+
+## Sources
+
+Adapted on 2026-10-14 from [Emil Kowalski's design engineering skill](https://raw.githubusercontent.com/emilkowalski/skills/refs/heads/main/skills/emil-design-eng/SKILL.md) and [Vercel's web design guidelines skill](https://raw.githubusercontent.com/vercel-labs/agent-skills/refs/heads/main/skills/web-design-guidelines/SKILL.md).
+
+The accessibility and interface checks incorporate Vercel's Web Interface Guidelines `command.md` as local guidance. Its remote command workflow and output format are not required. The sandbox adaptations are specific to Artifacts.
+
+License notices are retained in [Third-party notices](../THIRD-PARTY-NOTICES.md).

package/skills/artifacts-design/references/visual-explanations.md

@@ -0,0 +1,13 @@
+# Beginner visual explanations
+
+When the user requests a visual HTML explanation for a beginner, assume no prior knowledge. Identify the topic from the conversation. Ask for it only if it is missing or ambiguous.
+
+Build a visual sequence with one idea per scene. Start with a concrete example the reader can recognize, then show how the parts connect or change. Use large illustrations, diagrams, or pictures to carry the explanation. Decorative icons and oversized headings do not replace explanatory images.
+
+Pair each visual with a short heading and a brief caption. Use familiar words and define necessary terms where they first appear. Keep labels close to what they explain. Preserve essential qualifications and the limits of an analogy even when the user asks for few words.
+
+Use inline SVG or CSS for diagrams. Use embedded raster images when the subject benefits from illustrations or photographs. Resize and compress them to fit the snapshot budget while keeping details readable. If image tools are unavailable, use a clear diagram when it can convey the concept faithfully. Report any requested imagery you cannot provide.
+
+Make the main visual dominant and its labels legible on narrow and wide screens. Give meaningful images text alternatives. Add interaction only when it helps the reader understand a relationship or change. Keep the core explanation accessible without operating a control.
+
+Before saving, check that the sequence explains the topic with its pictures and short captions, without a separate essay. Apply the [interface guidelines](interface-checks.md) visual checks and report any checks you could not run.

package/skills/artifacts-design/scripts/embed-fonts.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const fonts = join(dirname(fileURLToPath(import.meta.url)), '../fonts');
+const latin = 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD';
+const faces = [
+  { family: 'Bricolage Grotesque', style: 'normal', weight: '500 800', file: 'bricolage-grotesque.woff2' },
+  { family: 'Public Sans', style: 'normal', weight: '400 700', file: 'public-sans.woff2' },
+  { family: 'Public Sans', style: 'italic', weight: '400 700', file: 'public-sans-italic.woff2' },
+  { family: 'JetBrains Mono', style: 'normal', weight: '400 700', file: 'jetbrains-mono.woff2' },
+  { family: 'Newsreader', style: 'normal', weight: '400 700', file: 'newsreader.woff2' },
+  { family: 'Newsreader', style: 'italic', weight: '400 700', file: 'newsreader-italic.woff2' },
+];
+const limit = 1024 * 1024;
+const embedded = /<style data-artifacts-fonts>[\s\S]*?<\/style>\n?/;
+
+const paths = process.argv.slice(2);
+if (paths.length !== 1) {
+  process.stderr.write('Usage: node embed-fonts.mjs PAGE.html\nEmbeds the bundled font faces that PAGE.html names, in place.\n');
+  process.exit(2);
+}
+const [path] = paths;
+const page = (await readFile(path, 'utf8')).replace(embedded, '');
+const italic = /font-style\s*:\s*italic|<(em|i|cite)[\s>]/i.test(page);
+const used = faces.filter((face) => page.includes(face.family) && (face.style === 'normal' || italic));
+const rules = await Promise.all(used.map(async (face) => {
+  const data = (await readFile(join(fonts, face.file))).toString('base64');
+  return `@font-face{font-family:"${face.family}";font-style:${face.style};font-weight:${face.weight};font-display:swap;src:url(data:font/woff2;base64,${data}) format("woff2");unicode-range:${latin}}`;
+}));
+const block = rules.length ? `<style data-artifacts-fonts>${rules.join('')}</style>\n` : '';
+
+const anchor = page.search(/<style[\s>]/i);
+const head = /<head[^>]*>\n?/i.exec(page) ?? /<!doctype[^>]*>\n?/i.exec(page);
+const at = anchor >= 0 ? anchor : head ? head.index + head[0].length : 0;
+const output = page.slice(0, at) + block + page.slice(at);
+const bytes = Buffer.byteLength(output);
+if (bytes > limit) {
+  process.stderr.write(`Not written. ${path} would be ${bytes} bytes, above the 1 MiB revision limit. Drop a family or the italic faces, or shrink the content.\n`);
+  process.exit(1);
+}
+await writeFile(path, output);
+const names = used.map((face) => `${face.family}${face.style === 'italic' ? ' italic' : ''}`);
+process.stdout.write(`${names.length ? `Embedded ${names.join(', ')}` : 'No bundled family named; nothing embedded'}. ${path} is ${bytes} bytes.\n`);

package/skills/artifacts-design/templates/starter.html

@@ -0,0 +1,170 @@
+<!doctype html>
+<html lang="es">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Artifact starter</title>
+<style>
+/* Layout: one centered column; summary before detail, then the dominant table, chart, or diagram. */
+:root{
+  --page:#eff1f5; --surface:#ffffff; --sunken:#e6e9ef; --line:#ccd0da; --control:#8c8fa1;
+  --fg:#4c4f69; --muted:#5c5f77; --accent:#1e66f5; --on-accent:#ffffff; --accent-ink:#1957d0;
+  --ok:#40a02b; --ok-ink:#307820; --warn:#df8e1d; --warn-ink:#915c13; --bad:#d20f39; --bad-ink:#b20d30;
+  --neutral-soft:color-mix(in srgb,var(--fg) 9%,var(--surface));
+  --accent-soft:color-mix(in srgb,var(--accent) 14%,var(--surface));
+  --ok-soft:color-mix(in srgb,var(--ok) 14%,var(--surface));
+  --warn-soft:color-mix(in srgb,var(--warn) 14%,var(--surface));
+  --bad-soft:color-mix(in srgb,var(--bad) 14%,var(--surface));
+  --f-display:"Bricolage Grotesque","Avenir Next",system-ui,sans-serif;
+  --f-body:"Public Sans","Segoe UI",system-ui,sans-serif;
+  --f-mono:"JetBrains Mono",ui-monospace,"SF Mono",Menlo,Consolas,monospace;
+  --radius:10px; --width:1120px;
+  color-scheme:light;
+}
+@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){
+  --page:#181825; --surface:#1e1e2e; --sunken:#11111b; --line:#313244; --control:#6c7086;
+  --fg:#cdd6f4; --muted:#a6adc8; --accent:#89b4fa; --on-accent:#11111b; --accent-ink:#89b4fa;
+  --ok:#a6e3a1; --ok-ink:#a6e3a1; --warn:#f9e2af; --warn-ink:#f9e2af; --bad:#f38ba8; --bad-ink:#f38ba8;
+  color-scheme:dark}}
+:root[data-theme="dark"]{
+  --page:#181825; --surface:#1e1e2e; --sunken:#11111b; --line:#313244; --control:#6c7086;
+  --fg:#cdd6f4; --muted:#a6adc8; --accent:#89b4fa; --on-accent:#11111b; --accent-ink:#89b4fa;
+  --ok:#a6e3a1; --ok-ink:#a6e3a1; --warn:#f9e2af; --warn-ink:#f9e2af; --bad:#f38ba8; --bad-ink:#f38ba8;
+  color-scheme:dark}
+
+*{box-sizing:border-box}
+html{background:var(--page)}
+body{margin:0;background:var(--page);color:var(--fg);font:15px/1.55 var(--f-body);-webkit-font-smoothing:antialiased}
+.wrap{max-width:var(--width);margin:0 auto;padding-left:max(16px,env(safe-area-inset-left,0px));padding-right:max(16px,env(safe-area-inset-right,0px));padding-block:32px 64px;display:grid;gap:24px}
+.wrap>*{min-width:0}
+h1,h2,h3{font-family:var(--f-display);margin:0;text-wrap:balance;letter-spacing:-.01em}
+h1{font-size:clamp(28px,4vw,40px);line-height:1.05;font-weight:700}
+h2{font-size:clamp(20px,2.4vw,24px);line-height:1.2;font-weight:700}
+h3{font-size:17px;line-height:1.3;font-weight:600}
+p{margin:0}
+a{color:var(--accent-ink);text-underline-offset:3px}
+code,kbd,pre{font-family:var(--f-mono);font-size:.86em}
+pre{margin:0;padding:14px 16px;background:var(--sunken);border-radius:8px;overflow-x:auto;line-height:1.5}
+:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+
+.eyebrow,.label{font:600 11.5px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
+header{display:grid;gap:8px}
+.lede{color:var(--muted);max-width:68ch;font-size:16px}
+.prose{display:grid;gap:12px;max-width:68ch}
+section{display:grid;gap:14px}
+
+.strip{display:flex;flex-wrap:wrap;gap:1px;background:var(--line);border:1px solid var(--line);border-radius:var(--radius);overflow:hidden}
+.stat{flex:1 1 150px;display:grid;gap:2px;padding:14px 16px;background:var(--surface)}
+.stat b{font:700 26px/1.1 var(--f-display);font-variant-numeric:tabular-nums}
+.stat span{font-size:13px;color:var(--muted)}
+
+.pill{display:inline-flex;align-items:center;gap:6px;font:600 11.5px/1.25 var(--f-body);padding:3px 8px;border-radius:5px;background:var(--neutral-soft);color:var(--muted)}
+.pills{display:flex;flex-wrap:wrap;gap:5px}
+.pill.accent{background:var(--accent-soft);color:var(--accent-ink)}
+.pill.ok{background:var(--ok-soft);color:var(--ok-ink)}
+.pill.warn{background:var(--warn-soft);color:var(--warn-ink)}
+.pill.bad{background:var(--bad-soft);color:var(--bad-ink)}
+
+.panel{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);padding:16px 18px;display:grid;gap:10px}
+.note{border-left:3px solid var(--accent);padding:2px 0 2px 14px;display:grid;gap:4px;max-width:72ch}
+.note.warn{border-color:var(--warn)}
+
+.table{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);overflow-x:auto}
+table{width:100%;border-collapse:collapse;font-size:14px}
+th{font:600 11px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted);text-align:left;padding:10px 14px;background:var(--sunken);border-bottom:1px solid var(--line);white-space:nowrap}
+td{padding:11px 14px;border-bottom:1px solid var(--line);vertical-align:top;font-variant-numeric:tabular-nums}
+tr:last-child td{border-bottom:0}
+td.num,th.num{text-align:right;white-space:nowrap}
+
+.rows{background:var(--surface);border:1px solid var(--line);border-radius:var(--radius);overflow:hidden}
+.rows-head,.row>summary{display:grid;grid-template-columns:var(--cols,88px minmax(0,2fr) minmax(0,1fr) minmax(0,1.4fr));gap:16px;padding:12px 16px;align-items:start}
+.rows-head{font:600 11px/1.2 var(--f-mono);letter-spacing:.06em;text-transform:uppercase;color:var(--muted);background:var(--sunken);border-bottom:1px solid var(--line)}
+.row{border-bottom:1px solid var(--line)}
+.row:last-child{border-bottom:0}
+.row>summary{cursor:pointer;list-style:none}
+.row>summary::-webkit-details-marker{display:none}
+.row>summary>*{min-width:0}
+.row>summary>:first-child::before{content:"▸";display:inline-block;margin-right:6px;color:var(--muted);font-size:11px;transition:transform .15s}
+.row[open]>summary>:first-child::before{transform:rotate(90deg)}
+.row-detail{padding:4px 16px 18px;display:grid;grid-template-columns:repeat(auto-fit,minmax(min(260px,100%),1fr));gap:14px 28px}
+.row-detail dl{margin:0;display:grid;gap:10px;align-content:start}
+.row-detail dd{margin:2px 0 0;font-size:13.5px;overflow-wrap:anywhere}
+.row.closed>summary{color:var(--muted)}
+
+.bar{display:flex;flex-wrap:wrap;gap:10px;align-items:center}
+input,select,button{font:inherit;font-size:14px;color:var(--fg);background:var(--surface);border:1px solid var(--control);border-radius:8px;padding:8px 10px;min-width:0}
+button{cursor:pointer}
+button.primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent);font-weight:600}
+.chip{border:1px solid var(--line);border-radius:999px;padding:5px 11px;font-size:13px;font-weight:500}
+.chip[aria-pressed="true"]{background:var(--accent-soft);border-color:var(--accent);color:var(--accent-ink)}
+.count{margin-left:auto;font:13px var(--f-mono);color:var(--muted)}
+
+footer{font-size:12.5px;color:var(--muted);display:grid;gap:4px;border-top:1px solid var(--line);padding-top:16px}
+
+@media (max-width:720px){.rows-head{display:none}.row>summary{grid-template-columns:minmax(0,1fr);gap:6px}}
+@media (hover:hover) and (pointer:fine){tbody tr:hover td,.row>summary:hover{background:var(--sunken)}button:hover{border-color:var(--accent)}}
+@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}
+</style>
+</head>
+<body>
+<main class="wrap">
+  <header>
+    <div class="eyebrow">Specimen · artifacts-design</div>
+    <h1>Starter primitives</h1>
+    <p class="lede">Replace this body with the artifact's own composition. Keep the tokens and the primitives the page needs, and delete the rest.</p>
+  </header>
+
+  <section class="strip" aria-label="Summary">
+    <div class="stat"><b>34</b><span>Records</span></div>
+    <div class="stat"><b>23</b><span>Open</span></div>
+    <div class="stat"><b>4</b><span>Need attention</span></div>
+  </section>
+
+  <section>
+    <h2>Status and data</h2>
+    <div class="bar">
+      <input id="q" type="search" placeholder="Search" aria-label="Search">
+      <button class="chip" aria-pressed="true">All</button>
+      <button class="chip" aria-pressed="false">Open</button>
+      <span class="count">3 of 34</span>
+    </div>
+    <div class="table">
+      <table>
+        <thead><tr><th>Item</th><th>State</th><th class="num">Value</th></tr></thead>
+        <tbody>
+          <tr><td>Accent</td><td><span class="pill accent">In review</span></td><td class="num">1,204</td></tr>
+          <tr><td>Success</td><td><span class="pill ok">Passed</span></td><td class="num">98.6 %</td></tr>
+          <tr><td>Warning and error</td><td><span class="pill warn">Pending</span> <span class="pill bad">Failed</span></td><td class="num">−12</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+
+  <section>
+    <h2>Expandable records</h2>
+    <div class="rows">
+      <div class="rows-head" aria-hidden="true"><span>ID</span><span>Title</span><span>Group</span><span>State</span></div>
+      <details class="row">
+        <summary><b>#2088</b><span>Parallelize search and listing data fetching</span><span>Performance</span><span class="pills"><span class="pill">Draft</span><span class="pill ok">Build passed</span></span></summary>
+        <div class="row-detail">
+          <dl><dt class="label">Next step</dt><dd>Keep separate and wait for team review.</dd></dl>
+          <dl><dt class="label">Branch</dt><dd><code>refactor/search-plp-parallel-fetch</code></dd></dl>
+        </div>
+      </details>
+      <details class="row closed">
+        <summary><b>#2086</b><span>Temporary workspace configuration</span><span>Temporary</span><span class="pills"><span class="pill">Closed</span></span></summary>
+        <div class="row-detail"><dl><dt class="label">Reason</dt><dd>Closed without merge by the owner.</dd></dl></div>
+      </details>
+    </div>
+  </section>
+
+  <section class="prose">
+    <h2>Reading text</h2>
+    <p>Body copy stays near 68 characters per line. Use <code>code</code> for identifiers and the <span class="label">label</span> style for metadata.</p>
+    <div class="note"><b>Note.</b><p>A note marks one consequential statement. It is not a container for ordinary paragraphs.</p></div>
+  </section>
+
+  <footer><span>Source and date of the data go here.</span></footer>
+</main>
+</body>
+</html>

package/src/index.js

@@ -11,6 +11,7 @@ import { canonicalResource } from '@yargote/artifacts-contracts/http';
 import { createArtifactHttpClient, HttpError, prepareArtifactEdit } from '@yargote/artifacts-client';
 import { accessToken, login, logout } from "./auth.js";
 import { loadOperation, retainOperation, submitOperation } from "./operations.js";
+import { runSkillsCommand } from "./skills.js";
 const help = `Usage: artifacts COMMAND [OPTIONS]
 
 Global options:
@@ -21,13 +22,18 @@ Global options:
   --version              Print the installed package version
 
 Commands:
+  skills [list]
+  skills get NAME [--full]
+  skills get --all [--full]
+  skills path [NAME]
+  skills install [NAME] [--agent claude] [--global] [--force]
   login [--no-browser]
   logout
   whoami
   create --snapshot FILE [--request-id ID] [--response full|compact]
   create --command FILE
   list [--limit N] [--cursor CURSOR]
-  read ID [--revision REV] [--response full|compact] [--out FILE]
+  read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
   update ID --snapshot FILE --expected-revision REV [--request-id ID]
          [--response full|compact]
   update [ID] --command FILE
@@ -41,21 +47,29 @@ Commands:
 Mutation command files contain the complete create, update, or publish JSON.
 Mutation request IDs default to a random UUID. Commands are retained before
 submission. Retry sends the exact retained command for the same server and owner.
-Read --out saves the complete artifact JSON. Export --out saves the ZIP.
+Read --out saves the returned artifact JSON. Export --out saves the ZIP.
+Read --quiet requires --out and suppresses successful JSON stdout.
 Output files are created exclusively and never overwrite an existing path.
 JSON results go to stdout. Diagnostics and recovery guidance go to stderr.
 ARTIFACTS_ACCESS_TOKEN supplies a token for automation without local login.
+Skills commands work offline without a server, login, or private state.
+They print plain text. Global server and state options are accepted and ignored.
+Skills install defaults to artifacts-cli under .agents/skills in the current
+directory. --agent claude uses .claude/skills. --global uses your home directory.
+The installed discovery file loads instructions through artifacts skills get.
+Identical files stay unchanged. Differing files require --force.
 `;
 class UsageError extends Error {
 }
 const commandOptions = {
     login: ['no-browser'], logout: [], whoami: [],
     create: ['snapshot', 'request-id', 'response', 'command'],
-    list: ['limit', 'cursor'], read: ['revision', 'response', 'out'],
+    list: ['limit', 'cursor'], read: ['revision', 'response', 'out', 'quiet'],
     update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
     edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
     publish: ['revision', 'expected-version', 'request-id', 'command'],
     export: ['revision', 'out'], retry: [],
+    skills: ['full', 'all', 'agent', 'global', 'force'],
 };
 async function jsonFile(path) {
     const file = await open(path, constants.O_RDONLY);
@@ -88,7 +102,9 @@ async function main() {
             changes: { type: 'string' }, 'request-id': { type: 'string' }, response: { type: 'string' },
             revision: { type: 'string' }, 'expected-revision': { type: 'string' }, 'expected-version': { type: 'string' },
             limit: { type: 'string' }, cursor: { type: 'string' }, 'before-sequence': { type: 'string' },
-            summary: { type: 'boolean' }, out: { type: 'string' },
+            summary: { type: 'boolean' }, out: { type: 'string' }, quiet: { type: 'boolean' },
+            full: { type: 'boolean' }, all: { type: 'boolean' }, agent: { type: 'string' },
+            global: { type: 'boolean' }, force: { type: 'boolean' },
         },
     });
     const seen = new Set();
@@ -114,6 +130,8 @@ async function main() {
     for (const option of seen)
         if (!['server', 'state-dir', 'help', ...commandOptions[command]].includes(option))
             throw new UsageError(`Option --${option} is not supported by ${command}`);
+    if (command === 'skills')
+        return runSkillsCommand(arguments_, values, seen);
     const resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
     if (!resourceValue)
         throw new UsageError('Specify --server RESOURCE or ARTIFACTS_SERVER. No production server is selected by default.');
@@ -145,6 +163,9 @@ async function main() {
     const response = values.response;
     if (response !== undefined && response !== 'full' && response !== 'compact')
         throw new UsageError('--response requires full or compact');
+    const quiet = values.quiet ?? false;
+    if (quiet)
+        required('out');
     let commandToken;
     const client = createArtifactHttpClient({ resource, accessToken: () => commandToken ??= accessToken({ resource, stateDir }) });
     async function mutate(mutation) {
@@ -191,7 +212,7 @@ async function main() {
             const result = await client.read({ artifactId: argument(), ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
             if (values.out)
                 await writeOutput(values.out, `${JSON.stringify(result, null, 2)}\n`);
-            return result;
+            return quiet ? undefined : result;
         }
         case 'update': {
             if (values.command)

package/src/skills.d.ts

@@ -0,0 +1,9 @@
+interface SkillsOptions {
+    full?: boolean;
+    all?: boolean;
+    agent?: string;
+    global?: boolean;
+    force?: boolean;
+}
+export declare function runSkillsCommand(positionals: string[], options: SkillsOptions, seen: ReadonlySet<string>): Promise<void>;
+export {};

package/src/skills.js

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const catalogDirectory = resolve(fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../../../skills/' : '../skills/', import.meta.url)));
+function parseCommand(positionals, options, seen) {
+    const [kind = 'list', ...arguments_] = positionals;
+    const allowed = { list: [], get: ['all', 'full'], path: [], install: ['agent', 'global', 'force'] };
+    if (!Object.hasOwn(allowed, kind))
+        throw new TypeError(`Unknown skills command ${kind}. Use artifacts --help for the reference.`);
+    for (const option of seen) {
+        if (!['server', 'state-dir', ...allowed[kind]].includes(option))
+            throw new TypeError(`Option --${option} is not supported by skills ${kind}`);
+    }
+    switch (kind) {
+        case 'list':
+            if (arguments_.length)
+                throw new TypeError('skills list does not accept positional arguments');
+            return { kind };
+        case 'get':
+            if (arguments_.length > 1 || (options.all ? arguments_.length !== 0 : arguments_.length !== 1))
+                throw new TypeError('skills get requires either one skill name or --all');
+            return { kind, selection: options.all ? { all: true } : { name: arguments_[0] }, full: options.full ?? false };
+        case 'path':
+            if (arguments_.length > 1)
+                throw new TypeError('skills path accepts zero or one skill name');
+            return { kind, name: arguments_[0] };
+        case 'install':
+            if (arguments_.length > 1)
+                throw new TypeError('skills install accepts zero or one skill name');
+            if (options.agent !== undefined && options.agent !== 'claude')
+                throw new TypeError('--agent requires claude. Omit --agent to install under .agents.');
+            return { kind, name: arguments_[0] ?? 'artifacts-cli', agent: options.agent === 'claude' ? 'claude' : 'agents', global: options.global ?? false, force: options.force ?? false };
+        default:
+            throw new TypeError(`Unknown skills command ${kind}`);
+    }
+}
+async function loadCatalog() {
+    const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const names = manifest.artifactsSkills;
+    if (!Array.isArray(names) || names.some((name) => typeof name !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) || new Set(names).size !== names.length)
+        throw new Error('Invalid bundled skills declaration');
+    return Promise.all(names.toSorted().map(async (name) => {
+        const directory = join(catalogDirectory, name);
+        const skillText = await readFile(join(directory, 'SKILL.md'));
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(skillText.toString('utf8'))?.[1];
+        const declaredName = frontmatter && /^name: (.+)$/m.exec(frontmatter)?.[1];
+        const description = frontmatter && /^description: (.+)$/m.exec(frontmatter)?.[1];
+        if (declaredName !== name || !description)
+            throw new Error(`Invalid bundled skill frontmatter at ${join(directory, 'SKILL.md')}`);
+        return { name, description, directory, skillText };
+    }));
+}
+async function fullFiles(directory, prefix = '') {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name, 'en'))) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            files.push(...await fullFiles(join(directory, entry.name), relative));
+        else if (entry.isFile())
+            files.push(relative);
+        else
+            throw new Error(`Bundled skill contains a non-regular file at ${join(directory, entry.name)}`);
+    }
+    return files;
+}
+function isText(content) {
+    if (content.includes(0))
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function labeledContent(skills, full) {
+    const chunks = [];
+    for (const skill of skills) {
+        const files = full ? ['SKILL.md', ...(await fullFiles(skill.directory)).filter((path) => path !== 'SKILL.md')] : ['SKILL.md'];
+        for (const path of files) {
+            const content = path === 'SKILL.md' ? skill.skillText : await readFile(join(skill.directory, path));
+            if (!isText(content)) {
+                chunks.push(Buffer.from(`=== ${skill.name}/${path} (binary, ${content.length} bytes) ===\n`));
+                continue;
+            }
+            chunks.push(Buffer.from(`=== ${skill.name}/${path} ===\n`), content);
+            if (content.at(-1) !== 10)
+                chunks.push(Buffer.from('\n'));
+        }
+    }
+    return Buffer.concat(chunks);
+}
+function discoveryText(skill) {
+    return `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\nBefore using this skill, run \`artifacts skills get ${skill.name} --full\`.\nLoad and follow the complete instructions, references, and templates bundled with the installed CLI version.\nRelative paths refer to the bundled directory reported by \`artifacts skills path ${skill.name}\`.\n`;
+}
+async function installSkill(skill, command) {
+    const destination = resolve(command.global ? homedir() : process.cwd(), command.agent === 'claude' ? '.claude' : '.agents', 'skills', skill.name, 'SKILL.md');
+    const content = Buffer.from(discoveryText(skill));
+    await mkdir(dirname(destination), { recursive: true });
+    try {
+        const file = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            await file.writeFile(content);
+        }
+        finally {
+            await file.close();
+        }
+        return destination;
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+    const existing = await lstat(destination);
+    if (!existing.isFile())
+        throw new TypeError(`Cannot install ${destination}. The destination must be a regular file, not a directory or symbolic link.`);
+    const file = await open(destination, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let previous;
+    try {
+        if (!(await file.stat()).isFile())
+            throw new TypeError(`Cannot install ${destination}. The destination must be a regular file.`);
+        previous = await file.readFile();
+    }
+    finally {
+        await file.close();
+    }
+    if (previous.equals(content))
+        return destination;
+    if (!command.force)
+        throw new TypeError(`Cannot replace differing file ${destination}. Use --force to replace it.`);
+    const temporary = join(dirname(destination), `.SKILL.md.${randomUUID()}.tmp`);
+    try {
+        const replacement = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            await replacement.writeFile(content);
+        }
+        finally {
+            await replacement.close();
+        }
+        const current = await lstat(destination);
+        if (!current.isFile())
+            throw new TypeError(`Cannot install ${destination}. The destination must be a regular file, not a directory or symbolic link.`);
+        if (current.ino !== existing.ino || current.dev !== existing.dev || current.mtimeMs !== existing.mtimeMs || current.ctimeMs !== existing.ctimeMs)
+            throw new TypeError(`Cannot replace ${destination}. The destination changed during installation. Run the command again.`);
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return destination;
+}
+export async function runSkillsCommand(positionals, options, seen) {
+    const command = parseCommand(positionals, options, seen);
+    const skills = await loadCatalog();
+    function named(name) {
+        const skill = skills.find((entry) => entry.name === name);
+        if (!skill)
+            throw new TypeError(`Unknown bundled skill ${name}. Use artifacts skills list to inspect available skills.`);
+        return skill;
+    }
+    switch (command.kind) {
+        case 'list':
+            process.stdout.write(skills.map((skill) => `${skill.name}\t${skill.description}\n`).join(''));
+            return;
+        case 'get': {
+            const selection = 'all' in command.selection ? skills : [named(command.selection.name)];
+            process.stdout.write(!command.full && 'name' in command.selection ? selection[0].skillText : await labeledContent(selection, command.full));
+            return;
+        }
+        case 'path':
+            process.stdout.write(`${command.name === undefined ? catalogDirectory : named(command.name).directory}\n`);
+            return;
+        case 'install':
+            process.stdout.write(`${await installSkill(named(command.name), command)}\n`);
+    }
+}