@canonical/pragma-cli 0.18.0

package/src/domains/shared/prefixes.ts

@@ -0,0 +1,37 @@
+/**
+ * Prefix map for ke store creation.
+ *
+ * Registered as PREFIX declarations in every SPARQL query.
+ * Single source of truth — rename a key here and P updates automatically.
+ */
+
+import type { PrefixMap } from "@canonical/ke";
+
+export const PREFIX_MAP = {
+  ds: "https://ds.canonical.com/",
+  cs: "http://pragma.canonical.com/codestandards#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  skos: "http://www.w3.org/2004/02/skos/core#",
+} as const satisfies PrefixMap;
+
+/**
+ * SPARQL prefix accessors derived from {@link PREFIX_MAP}.
+ *
+ * Use in query templates: `${P.ds}Component` → `"ds:Component"`.
+ * Renaming a key in PREFIX_MAP automatically updates every query.
+ */
+export const P = Object.fromEntries(
+  Object.keys(PREFIX_MAP).map((k) => [k, `${k}:`]),
+) as { readonly [K in keyof typeof PREFIX_MAP]: `${K}:` };
+
+/**
+ * Turtle `@prefix` declarations derived from {@link PREFIX_MAP}.
+ *
+ * Includes `xsd:` which TTL data files commonly use but SPARQL queries
+ * don't need (ke auto-injects PREFIX_MAP for queries).
+ */
+export const TTL_PREFIXES = [
+  ...Object.entries(PREFIX_MAP).map(([k, uri]) => `@prefix ${k}: <${uri}> .`),
+  "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",
+].join("\n");

package/src/domains/shared/runtime.ts

@@ -0,0 +1,62 @@
+/**
+ * Unified boot path for pragma CLI, MCP, and completions server.
+ *
+ * `PragmaRuntime` encapsulates all boot-time state (store, config, cwd).
+ * `bootPragma()` is the single factory function that creates it. All three
+ * surfaces (CLI, MCP, completions) call `bootPragma()` instead of manually
+ * assembling store + config.
+ *
+ * @note Impure — reads config from filesystem and boots ke store (WASM + TTL).
+ */
+
+import type { SourceSpec, Store } from "@canonical/ke";
+import { type PragmaConfig, readConfig } from "#config";
+import { bootStore } from "./bootStore.js";
+
+/**
+ * Boot-time state shared by CLI, MCP, and completions server.
+ *
+ * Four members:
+ * - `store` — the ke triple store, loaded and ready for SPARQL queries.
+ * - `config` — resolved pragma config (tier, channel).
+ * - `cwd` — working directory used for config and source resolution.
+ * - `dispose()` — tears down the store and frees WASM memory. Must be
+ *   called exactly once; calling operations after dispose is undefined.
+ */
+export interface PragmaRuntime {
+  readonly store: Store;
+  readonly config: PragmaConfig;
+  readonly cwd: string;
+  dispose(): void;
+}
+
+/**
+ * Create a fully initialized `PragmaRuntime`.
+ *
+ * Reads config from `cwd` (defaults to `process.cwd()`), boots the ke
+ * store from resolved sources, and returns a runtime ready for operation
+ * calls. The caller owns the lifecycle and must call `dispose()`.
+ *
+ * @param options.cwd - Working directory for config and source resolution.
+ * @param options.sources - Override sources for testing (skip filesystem resolution).
+ * @throws PragmaError with code CONFIG_ERROR if config is invalid.
+ * @throws PragmaError with code STORE_ERROR if store fails to initialize.
+ */
+export async function bootPragma(options?: {
+  cwd?: string;
+  sources?: SourceSpec[];
+}): Promise<PragmaRuntime> {
+  const cwd = options?.cwd ?? process.cwd();
+  const config = readConfig(cwd);
+  const store = await bootStore({
+    cwd,
+    sources: options?.sources,
+  });
+
+  return {
+    store,
+    config,
+    cwd,
+    dispose: () => store.dispose(),
+  };
+}

package/src/domains/shared/types.test-d.ts

@@ -0,0 +1,127 @@
+/**
+ * Compile-time type tests.
+ *
+ * Asserts that shared operation return types match their contracts.
+ * Checked by `tsc --noEmit`, not executed at runtime.
+ */
+
+import type { Store, URI } from "@canonical/ke";
+import { expectTypeOf } from "expect-type";
+import { listBlocks, lookupBlock } from "../block/operations/index.js";
+import { listModifiers, lookupModifier } from "../modifier/operations/index.js";
+import {
+  listCategories,
+  listStandards,
+  lookupStandard,
+} from "../standard/operations/index.js";
+import { listTiers } from "../tier/operations/index.js";
+import { listTokens, lookupToken } from "../token/operations/index.js";
+import type {
+  AnatomyNode,
+  AnatomyTree,
+  BlockDetailed,
+  BlockDigest,
+  BlockSummary,
+  CategorySummary,
+  CodeBlock,
+  FilterConfig,
+  ModifierFamily,
+  StandardDetailed,
+  StandardRef,
+  StandardSummary,
+  TierEntry,
+  TokenDetailed,
+  TokenRef,
+  TokenSummary,
+} from "./types.js";
+
+// =============================================================================
+// Type structure assertions
+// =============================================================================
+
+// BlockSummary
+expectTypeOf<BlockSummary["uri"]>().toEqualTypeOf<URI>();
+expectTypeOf<BlockSummary["name"]>().toBeString();
+expectTypeOf<BlockSummary["type"]>().toEqualTypeOf<
+  "component" | "pattern" | "layout" | "subcomponent"
+>();
+expectTypeOf<BlockSummary["tier"]>().toBeString();
+expectTypeOf<BlockSummary["modifiers"]>().toEqualTypeOf<readonly string[]>();
+expectTypeOf<BlockSummary["nodeCount"]>().toBeNumber();
+expectTypeOf<BlockSummary["tokenCount"]>().toBeNumber();
+
+// BlockDigest extends BlockSummary
+expectTypeOf<BlockDigest>().toMatchTypeOf<BlockSummary>();
+expectTypeOf<BlockDigest["summary"]>().toEqualTypeOf<string | null>();
+
+// BlockDetailed extends BlockSummary
+expectTypeOf<BlockDetailed>().toMatchTypeOf<BlockDigest>();
+expectTypeOf<BlockDetailed["anatomy"]>().toEqualTypeOf<AnatomyTree | null>();
+expectTypeOf<BlockDetailed["tokens"]>().toEqualTypeOf<readonly TokenRef[]>();
+expectTypeOf<BlockDetailed["standards"]>().toEqualTypeOf<
+  readonly StandardRef[]
+>();
+
+// AnatomyNode
+expectTypeOf<AnatomyNode["type"]>().toEqualTypeOf<"named" | "anonymous">();
+expectTypeOf<AnatomyNode["children"]>().toEqualTypeOf<readonly AnatomyNode[]>();
+
+// StandardSummary
+expectTypeOf<StandardSummary["uri"]>().toEqualTypeOf<URI>();
+expectTypeOf<StandardSummary["name"]>().toBeString();
+expectTypeOf<StandardSummary["category"]>().toBeString();
+
+// StandardDetailed extends StandardSummary
+expectTypeOf<StandardDetailed>().toMatchTypeOf<StandardSummary>();
+expectTypeOf<StandardDetailed["dos"]>().toEqualTypeOf<readonly CodeBlock[]>();
+expectTypeOf<StandardDetailed["donts"]>().toEqualTypeOf<readonly CodeBlock[]>();
+
+// CodeBlock
+expectTypeOf<CodeBlock["language"]>().toBeString();
+expectTypeOf<CodeBlock["code"]>().toBeString();
+
+// CategorySummary
+expectTypeOf<CategorySummary["name"]>().toBeString();
+expectTypeOf<CategorySummary["standardCount"]>().toBeNumber();
+
+// ModifierFamily
+expectTypeOf<ModifierFamily["uri"]>().toEqualTypeOf<URI>();
+expectTypeOf<ModifierFamily["values"]>().toEqualTypeOf<readonly string[]>();
+
+// TokenSummary
+expectTypeOf<TokenSummary["uri"]>().toEqualTypeOf<URI>();
+expectTypeOf<TokenSummary["name"]>().toBeString();
+expectTypeOf<TokenSummary["category"]>().toBeString();
+
+// TokenDetailed extends TokenSummary
+expectTypeOf<TokenDetailed>().toMatchTypeOf<TokenSummary>();
+
+// TierEntry
+expectTypeOf<TierEntry["uri"]>().toEqualTypeOf<URI>();
+expectTypeOf<TierEntry["path"]>().toBeString();
+expectTypeOf<TierEntry["depth"]>().toBeNumber();
+
+// FilterConfig
+expectTypeOf<FilterConfig["channel"]>().toEqualTypeOf<
+  "normal" | "experimental" | "prerelease"
+>();
+
+// =============================================================================
+// Operation return type assertions
+// =============================================================================
+
+declare const store: Store;
+declare const filters: FilterConfig;
+
+expectTypeOf(listBlocks).returns.resolves.toEqualTypeOf<BlockSummary[]>();
+expectTypeOf(lookupBlock).returns.resolves.toEqualTypeOf<BlockDetailed>();
+expectTypeOf(listStandards).returns.resolves.toEqualTypeOf<StandardSummary[]>();
+expectTypeOf(lookupStandard).returns.resolves.toEqualTypeOf<StandardDetailed>();
+expectTypeOf(listCategories).returns.resolves.toEqualTypeOf<
+  CategorySummary[]
+>();
+expectTypeOf(listModifiers).returns.resolves.toEqualTypeOf<ModifierFamily[]>();
+expectTypeOf(lookupModifier).returns.resolves.toEqualTypeOf<ModifierFamily>();
+expectTypeOf(listTokens).returns.resolves.toEqualTypeOf<TokenSummary[]>();
+expectTypeOf(lookupToken).returns.resolves.toEqualTypeOf<TokenDetailed>();
+expectTypeOf(listTiers).returns.resolves.toEqualTypeOf<TierEntry[]>();

package/src/domains/shared/types.ts

@@ -0,0 +1,348 @@
+/**
+ * Shared operation return types.
+ *
+ * Contract between the operations layer (D3) and CLI/MCP adapters.
+ * Same data, different presentations.
+ */
+
+import type { URI } from "@canonical/ke";
+
+// =============================================================================
+// Block
+// =============================================================================
+
+/** Summary view of a design-system block (component, pattern, or primitive). */
+export interface BlockSummary {
+  /** Full RDF URI identifying this block in the ke store. */
+  readonly uri: URI;
+  /** Human-readable name (local name extracted from URI). */
+  readonly name: string;
+  /** Normalized ontology type for the block. */
+  readonly type: "component" | "pattern" | "layout" | "subcomponent";
+  /** Tier path this block belongs to (e.g., `"global"`, `"apps/lxd"`). */
+  readonly tier: string;
+  /** Active modifier names applied to this block. */
+  readonly modifiers: readonly string[];
+  /** Framework implementations declared for this block, with availability flags. */
+  readonly implementations: readonly {
+    framework: string;
+    available: boolean;
+  }[];
+  /** Number of anatomy nodes (DOM elements) in this block's anatomy tree. */
+  readonly nodeCount: number;
+  /** Number of design tokens referenced by this block. */
+  readonly tokenCount: number;
+}
+
+/** Digest view of a block for richer summary displays. */
+export interface BlockDigest extends BlockSummary {
+  /** Summary guidance when present in the graph. */
+  readonly summary: string | null;
+}
+
+/** Single node in a block's anatomy tree (recursive). */
+export interface AnatomyNode {
+  /** Element name (e.g., `"trigger"`, `"panel"`). */
+  readonly name: string;
+  /** Whether the node is explicitly named or inferred as anonymous. */
+  readonly type: "named" | "anonymous";
+  /** Child nodes nested under this element. */
+  readonly children: readonly AnatomyNode[];
+  /** Named slot this node exposes, if any. */
+  readonly slot?: string;
+}
+
+/** Wrapper around the root of a block's anatomy tree. */
+export interface AnatomyTree {
+  /** Top-level anatomy node from which all children descend. */
+  readonly root: AnatomyNode;
+}
+
+/** Detailed view of a block, extending the digest with anatomy, tokens, and standards. */
+export interface BlockDetailed extends BlockDigest {
+  /** Guidance on when the block should be used. */
+  readonly whenToUse: string | null;
+  /** Guidance on when the block should not be used. */
+  readonly whenNotToUse: string | null;
+  /** Additional usage guidance. */
+  readonly guidelines: string | null;
+  /** YAML anatomy DSL payload when present. */
+  readonly anatomyDsl: string | null;
+  /** Legacy anatomy payload when present. */
+  readonly anatomyClassic: string | null;
+  /** Figma reference link when present. */
+  readonly figmaLink: string | null;
+  /** Full anatomy tree, or `null` if the block declares no anatomy. */
+  readonly anatomy: AnatomyTree | null;
+  /** Modifier families with their allowed values. */
+  readonly modifierValues: readonly {
+    family: string;
+    values: readonly string[];
+  }[];
+  /** Modifier families resolved as richer objects. */
+  readonly modifierFamilies: readonly {
+    uri: URI;
+    name: string;
+    values: readonly string[];
+  }[];
+  /** Property metadata resolved from blank nodes. */
+  readonly properties: readonly {
+    name: string;
+    propertyType: string;
+    optional: boolean;
+    defaultValue: string | null;
+    constraints: string | null;
+  }[];
+  /** Direct subcomponents of the block. */
+  readonly subcomponents: readonly {
+    uri: URI;
+    name: string;
+  }[];
+  /** File paths to framework-specific implementations. */
+  readonly implementationPaths: readonly { framework: string; path: string }[];
+  /** Design tokens referenced by this block. */
+  readonly tokens: readonly TokenRef[];
+  /** Standards (guidelines/rules) that apply to this block. */
+  readonly standards: readonly StandardRef[];
+}
+
+// =============================================================================
+// Standard
+// =============================================================================
+
+/** Summary view of a design-system standard (guideline or rule). */
+export interface StandardSummary {
+  /** Full RDF URI identifying this standard in the ke store. */
+  readonly uri: URI;
+  /** Human-readable name of the standard. */
+  readonly name: string;
+  /** Category grouping (e.g., `"accessibility"`, `"layout"`). */
+  readonly category: string;
+  /** Brief prose description of what the standard prescribes. */
+  readonly description: string;
+  /** URI of the parent standard this one extends, if any. */
+  readonly extends?: string;
+}
+
+/** Fenced code block used in standard do/don't examples. */
+export interface CodeBlock {
+  /** Programming language identifier for syntax highlighting. */
+  readonly language: string;
+  /** Source code content of the example. */
+  readonly code: string;
+  /** Optional explanatory caption displayed alongside the code. */
+  readonly caption?: string;
+}
+
+/** Detailed view of a standard, extending the summary with code examples. */
+export interface StandardDetailed extends StandardSummary {
+  /** Positive examples demonstrating correct usage. */
+  readonly dos: readonly CodeBlock[];
+  /** Negative examples demonstrating incorrect usage. */
+  readonly donts: readonly CodeBlock[];
+}
+
+/** Summary of a standards category with its member count. */
+export interface CategorySummary {
+  /** Category name (e.g., `"accessibility"`, `"layout"`). */
+  readonly name: string;
+  /** Number of standards belonging to this category. */
+  readonly standardCount: number;
+}
+
+/** Optional filters for narrowing the standards list. */
+export interface StandardListFilters {
+  /** Restrict results to a single category name. */
+  readonly category?: string;
+  /** Free-text search term matched against standard names and descriptions. */
+  readonly search?: string;
+}
+
+// =============================================================================
+// Modifier
+// =============================================================================
+
+/** A modifier family (e.g., "size", "variant") with its allowed values. */
+export interface ModifierFamily {
+  /** Full RDF URI identifying this modifier family. */
+  readonly uri: URI;
+  /** Human-readable family name. */
+  readonly name: string;
+  /** Allowed values within this family (e.g., `["small", "medium", "large"]`). */
+  readonly values: readonly string[];
+}
+
+// =============================================================================
+// Token
+// =============================================================================
+
+/** Summary view of a design token. */
+export interface TokenSummary {
+  /** Full RDF URI identifying this token in the ke store. */
+  readonly uri: URI;
+  /** Human-readable token name (e.g., `"color-primary"`). */
+  readonly name: string;
+  /** Token category (e.g., `"color"`, `"spacing"`, `"typography"`). */
+  readonly category: string;
+}
+
+/** Detailed view of a token, extending the summary with per-theme resolved values. */
+export interface TokenDetailed extends TokenSummary {
+  /** Resolved values keyed by theme (e.g., `{ theme: "dark", value: "#fff" }`). */
+  readonly values: readonly { theme: string; value: string }[];
+}
+
+/** Lightweight reference to a token (name + URI), used in cross-references. */
+export interface TokenRef {
+  /** Human-readable token name. */
+  readonly name: string;
+  /** Full RDF URI of the referenced token. */
+  readonly uri: URI;
+}
+
+// =============================================================================
+// Standard cross-reference
+// =============================================================================
+
+/** Lightweight reference to a standard, used in block cross-references. */
+export interface StandardRef {
+  /** Human-readable standard name. */
+  readonly name: string;
+  /** Full RDF URI of the referenced standard. */
+  readonly uri: URI;
+  /** Category the referenced standard belongs to. */
+  readonly category: string;
+}
+
+// =============================================================================
+// Tier
+// =============================================================================
+
+/** A single entry in the tier hierarchy (e.g., `global`, `apps`, `apps/lxd`). */
+export interface TierEntry {
+  /** Full RDF URI identifying this tier in the ke store. */
+  readonly uri: URI;
+  /** Slash-separated tier path (e.g., `"apps/lxd"`). */
+  readonly path: string;
+  /** Path of the parent tier, if this is not the root. */
+  readonly parent?: string;
+  /** Nesting depth in the tier hierarchy (0 = root). */
+  readonly depth: number;
+}
+
+// =============================================================================
+// Graph
+// =============================================================================
+
+/** A predicate group from `graph inspect`: one predicate with all its objects. */
+export interface PredicateGroup {
+  /** RDF predicate URI (e.g., `"rdfs:label"`). */
+  readonly predicate: string;
+  /** Object values (URIs or literals) associated with this predicate. */
+  readonly objects: readonly string[];
+}
+
+/** Result of `graph inspect <uri>`: all triples where URI is subject. */
+export interface InspectResult {
+  /** The inspected subject URI. */
+  readonly uri: string;
+  /** Predicate groups aggregating all outgoing triples. */
+  readonly groups: readonly PredicateGroup[];
+}
+
+// =============================================================================
+// Ontology
+// =============================================================================
+
+/** Summary of a loaded ontology namespace from `ontology list`. */
+export interface OntologySummary {
+  /** Short prefix alias (e.g., `"ds"`, `"cs"`). */
+  readonly prefix: string;
+  /** Full namespace URI the prefix expands to. */
+  readonly namespace: string;
+  /** Number of OWL/RDFS classes defined in this namespace. */
+  readonly classCount: number;
+  /** Number of properties (object + datatype) defined in this namespace. */
+  readonly propertyCount: number;
+  readonly anatomyCount: number;
+}
+
+/** A class in an ontology's class hierarchy. */
+export interface OntologyClass {
+  /** Full URI of the class. */
+  readonly uri: string;
+  /** Human-readable label (rdfs:label). */
+  readonly label: string;
+  /** URI of the direct superclass, if declared. */
+  readonly superclass?: string;
+}
+
+/** A property in an ontology namespace. */
+export interface OntologyProperty {
+  /** Full URI of the property. */
+  readonly uri: string;
+  /** Human-readable label (rdfs:label). */
+  readonly label: string;
+  /** URI of the domain class this property applies to, if declared. */
+  readonly domain?: string;
+  /** URI of the range class or datatype, if declared. */
+  readonly range?: string;
+  /** Whether this is an object property (links classes) or datatype property (links to literals). */
+  readonly type: "object" | "datatype";
+}
+
+/** Detailed view of a single ontology namespace from `ontology show`. */
+export interface OntologyDetailed {
+  /** Short prefix alias (e.g., `"ds"`). */
+  readonly prefix: string;
+  /** Full namespace URI the prefix expands to. */
+  readonly namespace: string;
+  /** All classes defined in this namespace. */
+  readonly classes: readonly OntologyClass[];
+  /** All properties defined in this namespace. */
+  readonly properties: readonly OntologyProperty[];
+}
+
+// =============================================================================
+// Filter configuration
+// =============================================================================
+
+/** Runtime filter settings controlling tier and channel visibility in queries. */
+export interface FilterConfig {
+  /** Active tier path, or `undefined` for all-tiers visibility. */
+  readonly tier: string | undefined;
+  /** Release channel determining which stability levels are visible. */
+  readonly channel: "normal" | "experimental" | "prerelease";
+}
+
+// =============================================================================
+// Disclosure
+// =============================================================================
+
+/**
+ * Controls how much detail an operation returns.
+ *
+ * - `"summary"` — minimal fields (names and counts).
+ * - `"digest"` — intermediate detail with optional example length cap.
+ * - `"detailed"` — full content including code blocks and anatomy.
+ */
+export type Disclosure =
+  | { readonly level: "summary" }
+  | { readonly level: "digest"; readonly maxExampleLength?: number }
+  | { readonly level: "detailed" };
+
+// =============================================================================
+// Batch
+// =============================================================================
+
+/** Outcome of a batch operation: successful results alongside per-item errors. */
+export interface BatchResult<T> {
+  /** Items that were processed successfully. */
+  readonly results: readonly T[];
+  /** Items that failed, each carrying the entity name, error code, and message. */
+  readonly errors: readonly {
+    name: string;
+    code: string;
+    message: string;
+  }[];
+}

package/src/domains/skill/commands/index.ts

@@ -0,0 +1,2 @@
+/** @module Skill command definitions for `pragma skill`. */
+export { default as listCommand } from "./list.js";

package/src/domains/skill/commands/list.test.ts

@@ -0,0 +1,111 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CommandDefinition } from "@canonical/cli-core";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import type { PragmaContext } from "../../shared/context.js";
+import type { SkillListInput } from "../formatters/types.js";
+import buildListCommand from "./list.js";
+
+const TMP_ROOT = join(tmpdir(), `pragma-skill-cmd-${Date.now()}`);
+
+const TEST_SOURCES = [
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    packageName: "@canonical/design-system",
+  },
+];
+
+vi.mock("../helpers/resolveSkillSources.js", () => ({
+  default: () => TEST_SOURCES,
+}));
+
+beforeAll(() => {
+  mkdirSync(TMP_ROOT, { recursive: true });
+
+  const dir = join(TEST_SOURCES[0].dir, "design-audit");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "SKILL.md"),
+    `---
+name: design-audit
+description: Audit a component against DS specs
+metadata:
+  author: canonical
+---
+`,
+  );
+});
+
+afterAll(() => {
+  rmSync(TMP_ROOT, { recursive: true, force: true });
+});
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: TMP_ROOT,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store: {} as PragmaContext["store"],
+    config: { tier: undefined, channel: "normal" },
+    ...overrides,
+  } as PragmaContext;
+}
+
+async function executeOutput(
+  cmd: CommandDefinition,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<{ value: unknown; text: string }> {
+  const result = await cmd.execute(params, ctx);
+  expect(result.tag).toBe("output");
+  if (result.tag !== "output") throw new Error("Expected output result");
+  const text = result.render.plain(result.value);
+  return { value: result.value, text };
+}
+
+describe("buildListCommand", () => {
+  it("returns output result with skill data", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { value } = await executeOutput(cmd, {}, ctx);
+    const input = value as SkillListInput;
+    expect(input.skills).toHaveLength(1);
+    expect(input.skills[0].name).toBe("design-audit");
+  });
+
+  it("renders plain text output", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("design-audit");
+    expect(text).toContain("@canonical/design-system");
+  });
+
+  it("renders LLM markdown", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    expect(text).toContain("## Skills");
+    expect(text).toContain("**design-audit**");
+  });
+
+  it("renders JSON output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const cmd = buildListCommand(ctx);
+    const { text } = await executeOutput(cmd, {}, ctx);
+    const parsed = JSON.parse(text);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed[0].name).toBe("design-audit");
+  });
+
+  it("passes detailed flag to formatter input", async () => {
+    const ctx = makeCtx();
+    const cmd = buildListCommand(ctx);
+    const { value } = await executeOutput(cmd, { detailed: true }, ctx);
+    expect((value as SkillListInput).detailed).toBe(true);
+  });
+});