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

package/README.md

@@ -1,6 +1,6 @@
 # Artifacts CLI reference
 
-The `artifacts` Node CLI reads and writes retained artifacts through REST. It prints JSON results to stdout and diagnostics to stderr. Node 24 or later is required. Its private credential database uses Node's experimental built-in SQLite API.
+The `artifacts` Node CLI reads and writes retained artifacts through REST. It prints JSON results to stdout and diagnostics to stderr. Offline skills commands print plain text. Node 24 or later is required. Its private credential database uses Node's experimental built-in SQLite API.
 
 The `@yargote/artifacts-cli` package exposes the `artifacts` binary as compiled ESM JavaScript. Its client and contracts dependencies install automatically. Repository development uses `pnpm artifacts` with the same command syntax.
 
@@ -11,9 +11,9 @@ Use Node 24 or later. The beta targets macOS and Linux. Windows has not been ver
 Choose one persistent installation:
 
 ```sh
-npm install --global @yargote/artifacts-cli@0.1.0-beta.1
+npm install --global @yargote/artifacts-cli@0.1.0-beta.2
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.1
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.2
 artifacts --version
 ```
 
@@ -22,8 +22,8 @@ If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen
 For one-off execution, pin the same version:
 
 ```sh
-npx --yes @yargote/artifacts-cli@0.1.0-beta.1 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.1 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.2 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.2 --help
 ```
 
 `@beta` follows future prereleases. Exact versions remain reproducible. No stable `latest` release is part of this beta. An organization's pnpm minimum release age or trust policy can delay a new release. Follow that policy rather than disabling it globally.
@@ -80,6 +80,8 @@ Run `artifacts logout` before uninstalling if you want to clear credentials. Uni
 
 ## Server and local state
 
+Skills, help, and version commands work without a server or login. Skills commands do not read credentials or create private state. They accept and ignore global `--server` and `--state-dir` values, including their environment defaults.
+
 `--server RESOURCE` selects the exact canonical OAuth resource. `ARTIFACTS_SERVER` supplies the same value. A resource ending in `/mcp` uses REST under `/mcp/v1`. The CLI has no production default.
 
 `--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Credentials are separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
@@ -109,7 +111,7 @@ artifacts whoami
 artifacts create --snapshot FILE [--request-id ID] [--response full|compact]
 artifacts create --command FILE
 artifacts list [--limit N] [--cursor CURSOR]
-artifacts read ID [--revision REV] [--response full|compact] [--out FILE]
+artifacts read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
 artifacts update ID --snapshot FILE --expected-revision REV [--request-id ID]
                  [--response full|compact]
 artifacts update [ID] --command FILE
@@ -119,10 +121,42 @@ artifacts publish ID --revision REV --expected-version N [--request-id ID]
 artifacts publish [ID] --command FILE
 artifacts export ID --revision REV --out FILE
 artifacts retry REQUEST_ID
+artifacts skills [list]
+artifacts skills get NAME [--full]
+artifacts skills get --all [--full]
+artifacts skills path [NAME]
+artifacts skills install [NAME] [--agent claude] [--global] [--force]
 ```
 
 Global `--server RESOURCE` and `--state-dir DIR` options can appear before or after the command. Options cannot be repeated. Unknown options and options for another command fail before submission.
 
+## Bundled skills
+
+Check `artifacts --help` for `skills` support. The published `0.1.0-beta.1` package predates this command group. These commands describe the current source and packages built from it.
+
+`artifacts skills` and `artifacts skills list` print each bundled skill's name and description, separated by a tab. The initial catalog contains `artifacts-cli`. Its complete source directory is bundled with the CLI, so the instructions match the installed version and work offline.
+
+`artifacts skills get artifacts-cli` prints the complete `SKILL.md` without headers or changes to its bytes. `--full` includes every bundled reference and template. Each file starts with a catalog-relative marker such as `=== artifacts-cli/references/commands.md ===`. `artifacts skills get --all` prints every `SKILL.md` with these markers. Add `--full` to include every skill's support files.
+
+`artifacts skills path` prints the absolute bundled catalog directory. Add a skill name to print that skill's directory. These paths belong to the CLI package and do not depend on the current directory.
+
+Install a discovery skill for an agent with one of these commands.
+
+| Command | Destination |
+| --- | --- |
+| `artifacts skills install` | `./.agents/skills/artifacts-cli/SKILL.md` |
+| `artifacts skills install --agent claude` | `./.claude/skills/artifacts-cli/SKILL.md` |
+| `artifacts skills install --global` | `~/.agents/skills/artifacts-cli/SKILL.md` |
+| `artifacts skills install --agent claude --global` | `~/.claude/skills/artifacts-cli/SKILL.md` |
+
+The optional name defaults to `artifacts-cli`. The default destination always uses `.agents`, even if `.claude` already exists. Only explicit `--agent claude` selects `.claude`. Local paths resolve from the current directory. Global paths resolve from the user's home directory.
+
+The command prints the absolute destination. It leaves identical files unchanged, including their modification time. A differing file requires `--force`. Forced installation replaces only `SKILL.md` and preserves neighboring files. A directory or symbolic link at `SKILL.md` is rejected.
+
+The discovery file instructs the agent to run `artifacts skills get artifacts-cli --full` and follow the returned instructions. It contains no copied workflow or fixed package path. After a CLI upgrade, the same discovery command loads that installed version's skill.
+
+## Artifact input and output
+
 Create and update snapshot files contain the complete domain snapshot.
 
 ```json
@@ -133,7 +167,11 @@ Create and update snapshot files contain the complete domain snapshot.
 }
 ```
 
-`read --out FILE` saves the returned artifact JSON and also prints it to stdout. A default full read contains the complete snapshot under `revision.snapshot`. `export --out FILE` saves the exact ZIP and prints its filename, local path, media type, SHA-256, and byte count. Output files use exclusive creation and never overwrite an existing path.
+`read --out FILE` saves the returned artifact JSON and also prints it to stdout. Add `--quiet` to suppress successful stdout while saving the same bytes for the selected response mode. `--quiet` is available only for `read` and requires a nonempty `--out FILE`. Errors still go to stderr and exit with code `1`.
+
+Check installed help for `--quiet` support. Version `0.1.0-beta.1` predates this option. With that version, `artifacts read ARTIFACT_ID --out saved.json > /dev/null` suppresses stdout while preserving stderr and the exit status.
+
+A default full read contains the complete snapshot under `revision.snapshot`. `export --out FILE` saves the exact ZIP and prints its filename, local path, media type, SHA-256, and byte count. Output files use exclusive creation and never overwrite an existing path.
 
 History defaults to complete revisions. `--summary` returns revision metadata and attachment summaries. `--before-sequence` continues a page. `list --cursor` continues an artifact list.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "private": false,
   "type": "module",
   "description": "Command-line client for the Artifacts REST API.",
@@ -23,14 +23,18 @@
   "files": [
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skills"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.1",
-    "@yargote/artifacts-client": "0.1.0-beta.1",
+    "@yargote/artifacts-contracts": "0.1.0-beta.2",
+    "@yargote/artifacts-client": "0.1.0-beta.2",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },
+  "artifactsSkills": [
+    "artifacts-cli"
+  ],
   "publishConfig": {
     "access": "public",
     "tag": "beta",

package/skills/artifacts-cli/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: artifacts-cli
+description: Create, revise, inspect, publish, and export retained Artifacts through the artifacts CLI and REST API. Use when the user chooses the CLI or a terminal workflow for Artifacts. Exclude generic build artifacts and unrelated local files.
+---
+
+# Manage retained Artifacts with the CLI
+
+Use the installed `artifacts` executable. Run `artifacts --help` and read [the command workflow](references/commands.md) before the first operation. With bundled skills support, `artifacts skills get artifacts-cli --full` returns this skill and its complete command reference. If the executable is unavailable, report that prerequisite. Do not substitute database writes or invent CLI results.
+
+## Select the account and resource
+
+Use the resource selected by the user or the existing `ARTIFACTS_SERVER` environment value. Pass `--server RESOURCE` or set `ARTIFACTS_SERVER` for service commands. Skills, help, and version commands work offline without a server or login. Login does not set an implicit default. A resource is the canonical OAuth URL, such as `https://artifacts.example.test/mcp`. REST routes are below that resource at `/v1`. Do not infer a production connection from an example or silently switch to a local server.
+
+Run `artifacts whoami` before the first mutation when the current identity is not established. Keep the selected resource and owner consistent throughout one operation. If login is needed, use `artifacts login --server RESOURCE`. The user authenticates in the browser. Do not collect their password or read another application's credentials. Never put tokens in command arguments, operation files, logs, or the final reply.
+
+## Prepare retained content
+
+A revision is a complete snapshot with `metadata`, `content`, and `files`. The command reference contains its JSON shape. Use the requested title, language, content, and attachments. Do not include unrelated files or credentials.
+
+Use self-contained HTML for interactive content. Inline styles and scripts and embed required assets as data URLs. External requests, CDN dependencies, relative executable assets, forms, browser storage, and multi-file websites are unsupported. Attachments are downloads, not importable website resources. Markdown and text display inertly.
+
+Keep the whole revision within 1 MiB of decoded content, metadata, attachment paths, media types, and attachment bytes. At most 32 attachments are accepted. Base64 changes wire size, not the decoded limit. If required content exceeds a limit, explain the constraint without silently removing it.
+
+Finish requested visual and interaction checks before saving when browser tools are available. A successful CLI write proves persistence, not visual quality or browser compatibility. Interactive HTML follows the server's Chrome policy; do not promise it in every browser.
+
+## Create or revise
+
+Create a draft when the user asks to save new content. Use a complete snapshot file and retain the CLI's request ID and operation record until the result is verified.
+
+Resolve an existing artifact by its supplied ID, an observed publication URL, or a paginated list. If several results match, ask which one the user means. Read its current full snapshot before editing. Preserve metadata, custom JSON, content fields, and attachments the user did not ask to change.
+
+Use `edit` for partial changes that preserve omitted fields. Use `update` for a complete next snapshot with the observed `headRevisionId` as its expected revision. Changing the attachment list replaces that inventory; an empty list removes all attachments. An update creates a retained revision and does not change the published revision.
+
+## Publish deliberately
+
+Publish when the user requests publication, a shareable artifact URL, or a change to the live artifact. Use the exact saved revision selected by the user or returned by the edit. Read the current publication version before preparing publication. Use zero only when the artifact is unpublished.
+
+A published URL still requires its owner's Artifacts login. Publishing a historical revision leaves the draft head unchanged. Report the returned protected URL only after the publication succeeds and its current state is verified.
+
+## Recover an uncertain write
+
+The CLI retains complete mutations before sending them. After a connection failure or uncertain result, use `retry` with that retained request ID once. Keep the same resource, owner, request ID, response mode, snapshot, and expected versions. Do not rerun a convenience edit or generate a new ID to repeat an operation whose outcome is unknown.
+
+If the retry remains unavailable, report the uncertainty and retain the recovery record. A conflict stops the failed operation. Read the current state and report the concurrent change. Do not replace expected versions to force a write. A changed operation needs a deliberate new command and request ID.
+
+A `request_conflict` means the ID was used with different arguments. Do not describe it as success. Authentication, validation, missing-artifact, and service failures likewise remain failures.
+
+## Verify and deliver
+
+After create or update, read the explicit returned revision. Use `read ARTIFACT_ID --revision REVISION_ID --out FILE --quiet` to retain the full response without printing its snapshot. Check that the installed `--help` supports `--quiet` first. For older versions, use the command workflow's stdout redirection fallback. Compare the saved complete metadata, content, and decoded attachment bytes with the intended snapshot. For an update, check that its parent is the head used for preparation. Compact responses cannot verify omitted content.
+
+After publication, read current publication and compare revision, version, and URL with the committed result. A replayed receipt describes the original commit; another writer may have changed the current publication afterward. Report that difference.
+
+Follow list and history cursors when the request needs more than the first page. Export an explicit retained revision to the requested destination. The CLI checks the archive digest. Confirm that the file exists and inspect its manifest and relevant content before linking it.
+
+Report the title, saved revision, and draft or published state in the user's language. Link the actual export or returned protected publication URL. Distinguish persistence from any visual or browser checks that did not run. Keep local credential and session identifiers private.

package/skills/artifacts-cli/references/commands.md

@@ -0,0 +1,156 @@
+# Command workflow
+
+Check the installed `artifacts --help` before use. These examples use the canonical resource selected for the task. `ARTIFACT_ID` and `REVISION_ID` stand for IDs observed in actual command output.
+
+## Inspect and install bundled skills
+
+When installed help lists `skills`, use these commands without a server or login.
+
+```sh
+artifacts skills
+artifacts skills get artifacts-cli --full
+artifacts skills get --all --full
+artifacts skills path artifacts-cli
+artifacts skills install
+artifacts skills install --agent claude --global
+```
+
+`skills` and `skills list` list names and descriptions. Plain `skills get artifacts-cli` returns the complete `SKILL.md`. `--full` includes references and templates with relative file paths. `skills path` without a name returns the catalog directory.
+
+Installation defaults to `artifacts-cli` in `.agents/skills` under the current directory. `--agent claude` selects `.claude/skills`. `--global` selects the user's home directory. Existing agent directories do not affect the default. The discovery file instructs the agent to load the installed CLI's complete instructions with `artifacts skills get artifacts-cli --full`. Installation reports the absolute path, leaves identical files unchanged, and requires `--force` to replace differing files.
+
+The published `0.1.0-beta.1` package predates skills commands. Do not assume support without checking help.
+
+## Authenticate
+
+```sh
+export ARTIFACTS_SERVER=https://artifacts.example.test/mcp
+artifacts login
+artifacts whoami
+```
+
+Replace the example with the selected resource before executing it. Service commands read `ARTIFACTS_SERVER` or an explicit `--server RESOURCE`. Login does not save a default resource. `--state-dir DIR` or `ARTIFACTS_STATE_DIR` selects an isolated private state directory. For automation, `ARTIFACTS_ACCESS_TOKEN` supplies an already authorized bearer token. Do not echo it or put it in an argument.
+
+Use `--no-browser` when the environment cannot open a browser automatically. Open the printed authorization URL and keep the CLI running for its loopback callback. A remote machine's loopback callback must be reachable by the browser used for login. Do not replace the callback with an arbitrary public listener.
+
+`logout` clears local credentials and attempts refresh-token revocation. Copied access JWTs can remain valid until expiry. The existing account page's global session revocation stops access across CLI, REST, MCP, and panel. Local logout does not claim to perform that global action.
+
+## Create a complete snapshot
+
+Save this JSON as `snapshot.json`, replacing its content with the requested artifact.
+
+```json
+{
+  "metadata": {
+    "title": "Project note",
+    "description": "A retained note",
+    "custom": { "source": "requested content" }
+  },
+  "content": {
+    "kind": "html",
+    "text": "<!doctype html><html lang=\"en\"><meta charset=\"utf-8\"><title>Project note</title><main><h1>Project note</h1><p>Retained content.</p></main></html>"
+  },
+  "files": [
+    {
+      "path": "notes.txt",
+      "mediaType": "text/plain",
+      "encoding": "utf8",
+      "data": "Retained attachment.\n"
+    }
+  ]
+}
+```
+
+`metadata.description` and `files` are required even when empty. Content kind is `html`, `markdown`, or `text`. Binary files use `encoding: "base64"` and canonical padded base64. Paths are unique normalized relative paths. Do not use empty, dot, parent, absolute, backslash, percent, or colon path segments. A file cannot also be another file's directory.
+
+```sh
+artifacts create --snapshot snapshot.json
+artifacts list --limit 25
+artifacts read ARTIFACT_ID --out saved.json --quiet
+```
+
+Keep the request ID printed for the mutation. Successful JSON goes to stdout; diagnostics and recovery instructions go to stderr. Exit zero indicates command success. A nonzero exit must be inspected before claiming completion.
+
+For `read`, `--out FILE --quiet` saves the returned response without printing successful JSON. It requires a nonempty output path. It preserves the selected response mode, so use the default full response for snapshot verification. Errors still go to stderr and exit nonzero. Without `--quiet`, `read --out FILE` also prints the response to stdout.
+
+Check installed help for `--quiet` support before running these examples. Older versions, including `0.1.0-beta.1`, can suppress stdout with `artifacts read ARTIFACT_ID --out saved.json > /dev/null`. This redirection preserves stderr and the command's exit status. Use the same fallback for the revision reads below.
+
+## Edit without losing retained data
+
+For a title change, save `changes.json` with only the requested field.
+
+```json
+{ "metadata": { "title": "Reviewed project note" } }
+```
+
+```sh
+artifacts edit ARTIFACT_ID --changes changes.json
+artifacts read ARTIFACT_ID --out current.json --quiet
+```
+
+For a complete replacement, read the current head, preserve untouched data in `next-snapshot.json`, and use that observed revision.
+
+```sh
+artifacts update ARTIFACT_ID --snapshot next-snapshot.json --expected-revision REVISION_ID
+```
+
+A complete command file can preserve a caller-owned request ID, snapshot, and expected revision. Use `artifacts create --command create.json`, `artifacts update --command update.json`, or `artifacts publish --command publish.json`. Do not add `response: "full"` to an existing command that omitted it. Optional response modes affect exact mutation identity.
+
+Command files contain the command itself, without the CLI's retained-operation wrapper.
+
+| Command | Required JSON fields |
+| --- | --- |
+| `create` | `requestId`, `snapshot` |
+| `update` | `requestId`, `artifactId`, `expectedRevisionId`, `snapshot` |
+| `publish` | `requestId`, `artifactId`, `revisionId`, `expectedPublicationVersion` |
+
+`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
+
+```json
+{
+  "requestId": "reviewed-update-001",
+  "artifactId": "OBSERVED_ARTIFACT_ID",
+  "expectedRevisionId": "OBSERVED_HEAD_REVISION_ID",
+  "snapshot": {
+    "metadata": { "title": "Reviewed project note", "description": "A retained note" },
+    "content": { "kind": "text", "text": "Reviewed content." },
+    "files": []
+  }
+}
+```
+
+Create uses the same `requestId` and complete `snapshot` fields without artifact or expected-revision IDs. A complete publication command has this shape. Replace zero with the observed publication version when already published.
+
+```json
+{
+  "requestId": "reviewed-publish-001",
+  "artifactId": "OBSERVED_ARTIFACT_ID",
+  "revisionId": "SELECTED_REVISION_ID",
+  "expectedPublicationVersion": 0
+}
+```
+
+## Inspect history and publish
+
+```sh
+artifacts history ARTIFACT_ID --summary
+artifacts read ARTIFACT_ID --revision REVISION_ID --out historical.json --quiet
+artifacts publish ARTIFACT_ID --revision REVISION_ID --expected-version 0
+```
+
+The publication example applies only to an unpublished artifact. For an existing publication, replace zero with the `publication.version` observed in a current read. After publishing, read again and compare current publication with the returned receipt.
+
+History returns `nextBeforeSequence`; pass it as `--before-sequence N` to continue. List returns `nextCursor`; pass it as `--cursor CURSOR`. Do not substitute an offset or assume that one page contains everything.
+
+## Retry and export
+
+```sh
+artifacts retry REQUEST_ID
+artifacts export ARTIFACT_ID --revision REVISION_ID --out artifact.zip
+```
+
+`retry` loads the saved complete operation. It does not prepare a new edit or change expected versions. Keep the record after an uncertain result. The server checks current authority before replaying an original receipt.
+
+`read --out` and `export --out` create files exclusively. Use a new destination if one already exists. Do not delete an existing output merely to rerun an example.
+
+The archive contains `artifact.json`, `content.html`, `content.md`, or `content.txt`, and attachments under `files/`. Inspect the manifest's artifact and revision IDs, content, and required attachment bytes. Exporting the same retained revision through REST, MCP, or the panel must yield identical ZIP bytes.

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,166 @@
+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;
+}
+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));
+            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`);
+    }
+}