@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/skill/formatters/lookup.ts

@@ -0,0 +1,57 @@
+import chalk from "chalk";
+import type { Formatters } from "../../shared/formatters.js";
+import type { SkillDetailed } from "../types.js";
+
+/**
+ * Formatters for `pragma skill lookup` output.
+ *
+ * - **plain** renders a chalk-styled header (name, source, files) above
+ *   the full SKILL.md content.
+ * - **llm** renders a markdown header above the content — the skill body
+ *   is already markdown, so it is served verbatim.
+ * - **json** serializes the skill with its content and companion files.
+ */
+const formatters: Formatters<SkillDetailed> = {
+  plain(skill) {
+    const lines: string[] = [
+      chalk.bold(skill.name),
+      chalk.dim(skill.description),
+      chalk.dim(`Source: ${skill.sourcePackage} (${skill.sourcePath})`),
+    ];
+    if (skill.files.length > 0) {
+      lines.push(chalk.dim(`Companion files: ${skill.files.join(", ")}`));
+    }
+    lines.push("", skill.content);
+    return lines.join("\n");
+  },
+
+  llm(skill) {
+    const lines: string[] = [
+      `## Skill: ${skill.name}`,
+      "",
+      `**Source:** ${skill.sourcePackage} (${skill.folderName})`,
+    ];
+    if (skill.files.length > 0) {
+      lines.push(`**Companion files:** ${skill.files.join(", ")}`);
+    }
+    lines.push("", skill.content);
+    return lines.join("\n");
+  },
+
+  json(skill) {
+    return JSON.stringify(
+      {
+        name: skill.name,
+        description: skill.description,
+        source: skill.sourcePackage,
+        path: skill.sourcePath,
+        files: skill.files,
+        content: skill.content,
+      },
+      null,
+      2,
+    );
+  },
+};
+
+export default formatters;

package/src/domains/skill/helpers/resolveSkillSources.ts

@@ -5,7 +5,6 @@ import {
 } from "../../shared/loaders/index.js";
 import { DEFAULT_PACKAGES } from "../../shared/packages.js";
 import type { SemanticPackage } from "../../shared/semanticPackage.js";
-import { resolveSemanticPackages } from "../../shared/semanticPackage.js";
 
 /** A resolved skill source directory from an installed package. */
 export interface SkillSource {

package/src/domains/skill/index.ts

@@ -2,7 +2,7 @@
 
 import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../shared/context.js";
-import { listCommand } from "./commands/index.js";
+import { listCommand, lookupCommand } from "./commands/index.js";
 
 /**
  * Return all skill command definitions.
@@ -11,9 +11,13 @@ import { listCommand } from "./commands/index.js";
  * @returns An array of CommandDefinitions for the skill subcommands.
  */
 export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx)];
+  return [listCommand(ctx), lookupCommand(ctx)];
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
 export type { SkillListResult } from "./operations/index.js";
-export { discoverSkills, listSkills } from "./operations/index.js";
+export {
+  discoverSkills,
+  listSkills,
+  lookupSkill,
+} from "./operations/index.js";

package/src/domains/skill/mcp/specs.ts

@@ -1,38 +1,19 @@
 /**
- * MCP tool specs for the skill domain.
+ * MCP tool specs for the skill domain — skill_list and skill_lookup,
+ * compiled from the skill read stories in `../stories.ts`. skill_lookup
+ * serves full SKILL.md content so agents can load skills over MCP.
  */
 
+import {
+  compileLookupTool,
+  compileReadTool,
+} from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { listFormatters as skillListFmt } from "../formatters/index.js";
-import { listSkills } from "../operations/index.js";
+import { skillListStory, skillLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "skill_list",
-    description: "List available agent skills from design system packages.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const { skills, sources } = await listSkills(rt.cwd);
-
-      if (condensed) {
-        const text = skillListFmt.llm({ skills, sources, detailed: false });
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: { skills, sources }, meta: { count: skills.length } };
-    },
-  },
+  compileReadTool(skillListStory),
+  compileLookupTool(skillLookupStory),
 ];
 
 export default specs;

package/src/domains/skill/operations/discover.test.ts

@@ -7,38 +7,72 @@ import discoverSkills from "./discover.js";
 
 const TMP_ROOT = join(tmpdir(), `pragma-skill-discover-${Date.now()}`);
 
-/** Test skill sources that mirror the real package layout. */
+/**
+ * Test skill sources that mirror the real loader granularity: each source
+ * is one skill directory (`<package>/skills/<name>`) containing SKILL.md,
+ * as produced by `readPackageDir`.
+ */
 const TEST_SOURCES: SkillSource[] = [
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-audit",
+    ),
     packageName: "@canonical/design-system",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/anatomy-dsl/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/ds-review",
+    ),
+    packageName: "@canonical/design-system",
+  },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/anatomy-dsl/skills/anatomy-author",
+    ),
     packageName: "@canonical/anatomy-dsl",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/pragma-cli/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/pragma-cli/skills/scaffold-story",
+    ),
+    packageName: "@canonical/pragma-cli",
+  },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/pragma-cli/skills/broken-skill",
+    ),
     packageName: "@canonical/pragma-cli",
   },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/no-skill-md",
+    ),
+    packageName: "@canonical/design-system",
+  },
 ];
 
-function writeSkillMd(
-  source: SkillSource,
-  skillName: string,
-  content: string,
-): void {
-  const dir = join(source.dir, skillName);
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "SKILL.md"), content);
+function writeSkillMd(source: SkillSource, content: string): void {
+  mkdirSync(source.dir, { recursive: true });
+  writeFileSync(join(source.dir, "SKILL.md"), content);
+}
+
+function sourceAt(index: number): SkillSource {
+  const source = TEST_SOURCES.at(index);
+  if (!source) throw new Error(`no test source at index ${index}`);
+  return source;
 }
 
 beforeAll(() => {
   mkdirSync(TMP_ROOT, { recursive: true });
 
   writeSkillMd(
-    TEST_SOURCES[0],
-    "design-audit",
+    sourceAt(0),
     `---
 name: design-audit
 description: Audit a component against DS specs
@@ -51,8 +85,7 @@ metadata:
   );
 
   writeSkillMd(
-    TEST_SOURCES[0],
-    "ds-review",
+    sourceAt(1),
     `---
 name: ds-review
 description: Review a PR for DS compliance
@@ -61,8 +94,7 @@ description: Review a PR for DS compliance
   );
 
   writeSkillMd(
-    TEST_SOURCES[2],
-    "scaffold-story",
+    sourceAt(3),
     `---
 name: scaffold-story
 description: Generate a Storybook story from anatomy
@@ -70,20 +102,19 @@ description: Generate a Storybook story from anatomy
 `,
   );
 
-  // Invalid frontmatter — should be skipped with warning
+  // Invalid frontmatter (missing description) — should be skipped with warning
   writeSkillMd(
-    TEST_SOURCES[2],
-    "broken-skill",
+    sourceAt(4),
     `---
 name: broken-skill
 ---
 `,
   );
 
-  // File without SKILL.md — should be skipped
-  const noSkillDir = join(TEST_SOURCES[0].dir, "no-skill-md");
-  mkdirSync(noSkillDir, { recursive: true });
-  writeFileSync(join(noSkillDir, "README.md"), "Not a skill");
+  // Source directory without a SKILL.md — should be skipped
+  const noSkillMd = sourceAt(5);
+  mkdirSync(noSkillMd.dir, { recursive: true });
+  writeFileSync(join(noSkillMd.dir, "README.md"), "Not a skill");
 });
 
 afterAll(() => {
@@ -100,15 +131,15 @@ describe("discoverSkills", () => {
   });
 
   it("skips missing source directories", async () => {
-    // TEST_SOURCES[1] (anatomy-dsl) was not created
+    // TEST_SOURCES[2] (anatomy-dsl) was never created on disk
     const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
     const packages = [...new Set(skills.map((s) => s.sourcePackage))];
     expect(packages).not.toContain("@canonical/anatomy-dsl");
   });
 
-  it("skips folders without SKILL.md", async () => {
+  it("skips source directories without SKILL.md", async () => {
     const skills = await discoverSkills(TMP_ROOT, TEST_SOURCES);
-    const names = skills.map((s) => s.name);
+    const names = skills.map((s) => s.folderName);
     expect(names).not.toContain("no-skill-md");
   });
 
@@ -123,7 +154,7 @@ describe("discoverSkills", () => {
     const audit = skills.find((s) => s.name === "design-audit");
     expect(audit?.sourcePackage).toBe("@canonical/design-system");
     expect(audit?.folderName).toBe("design-audit");
-    expect(audit?.sourcePath).toBe(join(TEST_SOURCES[0].dir, "design-audit"));
+    expect(audit?.sourcePath).toBe(sourceAt(0).dir);
   });
 
   it("preserves frontmatter metadata", async () => {
@@ -135,7 +166,7 @@ describe("discoverSkills", () => {
   it("returns empty array when no sources available", async () => {
     const emptySources: SkillSource[] = [
       {
-        dir: "/nonexistent/path/skills",
+        dir: "/nonexistent/path/skills/some-skill",
         packageName: "@canonical/nope",
       },
     ];

package/src/domains/skill/operations/discover.ts

@@ -1,5 +1,5 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
 import {
   parseFrontmatter,
   resolveSkillSources,
@@ -8,14 +8,18 @@ import {
 import type { DiscoveredSkill } from "../types.js";
 
 /**
- * Discover skills by scanning source package directories for subdirectories
- * containing a valid `SKILL.md` file. Missing source paths and invalid
- * frontmatter are skipped gracefully.
+ * Discover skills from resolved skill source directories.
+ *
+ * Each source directory is one skill folder (`<package>/skills/<name>`)
+ * containing a `SKILL.md` with YAML frontmatter — the granularity
+ * produced by the package loaders' `readPackageDir`. Missing files and
+ * invalid frontmatter are skipped gracefully (invalid frontmatter is
+ * reported on stderr).
  *
  * @param _cwd - Working directory (unused, sources are resolved globally).
  * @param overrideSources - Optional override for skill source definitions.
  * @returns Array of discovered skills with parsed frontmatter.
- * @note Impure
+ * @note Impure — reads SKILL.md files from the filesystem.
  */
 export default async function discoverSkills(
   _cwd: string,
@@ -25,43 +29,30 @@ export default async function discoverSkills(
   const sources = overrideSources ?? resolveSkillSources();
 
   for (const source of sources) {
-    let entries: string[];
+    const skillMdPath = resolve(source.dir, "SKILL.md");
+    let content: string;
     try {
-      entries = await readdir(source.dir);
+      content = await readFile(skillMdPath, "utf-8");
     } catch {
       continue;
     }
 
-    for (const entry of entries) {
-      const entryPath = resolve(source.dir, entry);
-      const entryStat = await stat(entryPath).catch(() => null);
-      if (!entryStat?.isDirectory()) continue;
-
-      const skillMdPath = resolve(entryPath, "SKILL.md");
-      let content: string;
-      try {
-        content = await readFile(skillMdPath, "utf-8");
-      } catch {
-        continue;
-      }
-
-      const frontmatter = parseFrontmatter(content);
-      if (!frontmatter) {
-        process.stderr.write(
-          `Warning: invalid SKILL.md frontmatter in ${skillMdPath}\n`,
-        );
-        continue;
-      }
-
-      skills.push({
-        name: frontmatter.name,
-        description: frontmatter.description,
-        sourcePath: entryPath,
-        sourcePackage: source.packageName,
-        folderName: entry,
-        frontmatter,
-      });
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter) {
+      process.stderr.write(
+        `Warning: invalid SKILL.md frontmatter in ${skillMdPath}\n`,
+      );
+      continue;
     }
+
+    skills.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      sourcePath: source.dir,
+      sourcePackage: source.packageName,
+      folderName: basename(source.dir),
+      frontmatter,
+    });
   }
 
   return skills;

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

@@ -1,4 +1,5 @@
-/** @module Skill operations: discovery and listing with source metadata. */
+/** @module Skill operations: discovery, listing, and content lookup. */
 export { default as discoverSkills } from "./discover.js";
 export type { SkillListResult } from "./list.js";
 export { default as listSkills } from "./list.js";
+export { default as lookupSkill } from "./lookup.js";

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

@@ -7,25 +7,33 @@ import listSkills from "./list.js";
 
 const TMP_ROOT = join(tmpdir(), `pragma-skill-list-${Date.now()}`);
 
+/** Each source is one skill directory, matching the loader granularity. */
 const TEST_SOURCES: SkillSource[] = [
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-audit",
+    ),
     packageName: "@canonical/design-system",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/anatomy-dsl/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/anatomy-dsl/skills/anatomy-author",
+    ),
     packageName: "@canonical/anatomy-dsl",
   },
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/pragma-cli/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/pragma-cli/skills/scaffold-story",
+    ),
     packageName: "@canonical/pragma-cli",
   },
 ];
 
 beforeAll(() => {
-  mkdirSync(TMP_ROOT, { recursive: true });
-
-  const skillDir = join(TEST_SOURCES[0].dir, "design-audit");
+  const skillDir = TEST_SOURCES.at(0)?.dir ?? "";
   mkdirSync(skillDir, { recursive: true });
   writeFileSync(
     join(skillDir, "SKILL.md"),
@@ -45,7 +53,7 @@ describe("listSkills", () => {
   it("returns discovered skills", async () => {
     const { skills } = await listSkills(TMP_ROOT, TEST_SOURCES);
     expect(skills).toHaveLength(1);
-    expect(skills[0].name).toBe("design-audit");
+    expect(skills.at(0)?.name).toBe("design-audit");
   });
 
   it("reports source availability", async () => {

package/src/domains/skill/operations/lookup.test.ts

@@ -0,0 +1,91 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import type { SkillSource } from "../helpers/index.js";
+import lookupSkill from "./lookup.js";
+
+const TMP_ROOT = join(tmpdir(), `pragma-skill-lookup-${Date.now()}`);
+
+/** Each source is one skill directory, matching the loader granularity. */
+const TEST_SOURCES: SkillSource[] = [
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-auditor",
+    ),
+    packageName: "@canonical/design-system",
+  },
+  {
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/code-standards/skills/add-standard",
+    ),
+    packageName: "@canonical/code-standards",
+  },
+];
+
+const AUDITOR_CONTENT = `---
+name: design-auditor
+description: Audit design system coverage
+---
+
+# Design Auditor
+
+Full instructions here.
+`;
+
+beforeAll(() => {
+  const auditor = TEST_SOURCES.at(0)?.dir ?? "";
+  mkdirSync(auditor, { recursive: true });
+  writeFileSync(join(auditor, "SKILL.md"), AUDITOR_CONTENT);
+  writeFileSync(join(auditor, "AUDIT_SPEC.md"), "# Spec");
+
+  const addStandard = TEST_SOURCES.at(1)?.dir ?? "";
+  mkdirSync(addStandard, { recursive: true });
+  writeFileSync(
+    join(addStandard, "SKILL.md"),
+    `---
+name: add-standard
+description: Create a new code standard
+---
+`,
+  );
+});
+
+afterAll(() => {
+  rmSync(TMP_ROOT, { recursive: true, force: true });
+});
+
+describe("lookupSkill", () => {
+  it("returns the skill with full content and companion files", async () => {
+    const skill = await lookupSkill(TMP_ROOT, "design-auditor", TEST_SOURCES);
+    expect(skill.name).toBe("design-auditor");
+    expect(skill.content).toBe(AUDITOR_CONTENT);
+    expect(skill.files).toEqual(["AUDIT_SPEC.md"]);
+    expect(skill.sourcePackage).toBe("@canonical/design-system");
+  });
+
+  it("matches case-insensitively", async () => {
+    const skill = await lookupSkill(TMP_ROOT, "Design-Auditor", TEST_SOURCES);
+    expect(skill.name).toBe("design-auditor");
+  });
+
+  it("reports no companion files when SKILL.md is alone", async () => {
+    const skill = await lookupSkill(TMP_ROOT, "add-standard", TEST_SOURCES);
+    expect(skill.files).toEqual([]);
+  });
+
+  it("throws not-found with suggestions for unknown names", async () => {
+    await expect(
+      lookupSkill(TMP_ROOT, "design-audit", TEST_SOURCES),
+    ).rejects.toMatchObject({
+      code: "ENTITY_NOT_FOUND",
+      suggestions: ["design-auditor"],
+    });
+    await expect(
+      lookupSkill(TMP_ROOT, "nope", TEST_SOURCES),
+    ).rejects.toBeInstanceOf(PragmaError);
+  });
+});

package/src/domains/skill/operations/lookup.ts

@@ -0,0 +1,70 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { PragmaError } from "#error";
+import { suggestNames } from "../../shared/suggestions/index.js";
+import type { SkillSource } from "../helpers/index.js";
+import type { SkillDetailed } from "../types.js";
+import discoverSkills from "./discover.js";
+
+/**
+ * Look up one skill by name or folder name and serve its content.
+ *
+ * Matches case-insensitively against the frontmatter name and the skill's
+ * folder name, then reads the full SKILL.md text plus the names of any
+ * companion files shipped alongside it (e.g. spec documents).
+ *
+ * @param cwd - Working directory.
+ * @param query - Skill name or folder name to look up.
+ * @param overrideSources - Optional override for skill source definitions.
+ * @returns The matched skill with content and companion file names.
+ * @throws PragmaError with code ENTITY_NOT_FOUND and ranked suggestions
+ *   when no skill matches.
+ * @note Impure — reads SKILL.md and the skill directory listing.
+ */
+export default async function lookupSkill(
+  cwd: string,
+  query: string,
+  overrideSources?: SkillSource[],
+): Promise<SkillDetailed> {
+  const skills = await discoverSkills(cwd, overrideSources);
+  const queryLower = query.toLowerCase();
+  const match = skills.find(
+    (skill) =>
+      skill.name.toLowerCase() === queryLower ||
+      skill.folderName.toLowerCase() === queryLower,
+  );
+
+  if (!match) {
+    throw PragmaError.notFound("skill", query, {
+      suggestions: suggestNames(
+        query,
+        skills.map((skill) => skill.name),
+      ),
+      recovery: {
+        message: "List available skills.",
+        cli: "pragma skill list",
+        mcp: { tool: "skill_list" },
+      },
+    });
+  }
+
+  const content = await readFile(
+    resolve(match.sourcePath, "SKILL.md"),
+    "utf-8",
+  );
+  const files = await listCompanionFiles(match.sourcePath);
+
+  return { ...match, content, files };
+}
+
+async function listCompanionFiles(dir: string): Promise<readonly string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name !== "SKILL.md")
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}

package/src/domains/skill/stories.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { skillListStory } from "./stories.js";
+import type { SkillSource } from "./types.js";
+
+const availableSource: SkillSource = {
+  path: "/pkgs/design-system/skills/design-auditor",
+  packageName: "@canonical/design-system",
+  available: true,
+};
+
+const unavailableSource: SkillSource = {
+  path: "/pkgs/missing/skills/gone",
+  packageName: "@canonical/missing",
+  available: false,
+};
+
+describe("skillListStory", () => {
+  it("passes the CLI detailed flag into the formatter input", () => {
+    const data = { skills: [], sources: [] };
+    expect(skillListStory.toOutput(data, { detailed: true }).detailed).toBe(
+      true,
+    );
+    expect(skillListStory.toOutput(data, {}).detailed).toBe(false);
+  });
+
+  it("suggests installing packages when no source is available", () => {
+    const error = skillListStory.emptyError?.(
+      { skills: [], sources: [unavailableSource] },
+      {},
+    );
+    expect(error?.recovery?.message).toBe("Install @canonical packages first");
+  });
+
+  it("reports missing SKILL.md files when sources are available", () => {
+    const error = skillListStory.emptyError?.(
+      { skills: [], sources: [availableSource] },
+      {},
+    );
+    expect(error?.recovery?.message).toBe(
+      "No SKILL.md files found in source packages",
+    );
+  });
+});