@gpambrozio/paseo-skills 0.1.2

package/index.client.tsx

@@ -0,0 +1,27 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+
+import { SkillsPanel } from "./client/panel";
+import { contributePills } from "./client/pill";
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "skills",
+    title: "Skills",
+    icon: "Sparkles",
+    context: "agent",
+    Component: SkillsPanel,
+  });
+  client.addCommandCenterItem({
+    id: "open-skills",
+    title: "Skills",
+    icon: "Sparkles",
+    keywords: ["skill", "skills", "agent skills"],
+    context: "agent",
+    onSelect: ({ openPanel }) => {
+      openPanel("skills");
+    },
+  });
+  // The pill reaches the panel from the composer; the Command Center item is
+  // the keyboard path to the same panel.
+  return contributePills(client);
+}

package/index.server.ts

@@ -0,0 +1,10 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+
+import { createListSkillsHandler, createReadSkillHandler } from "./server/skills";
+import { listSkills, readSkill } from "./shared/skills";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(listSkills, createListSkillsHandler());
+  server.handle(readSkill, createReadSkillHandler());
+  return () => {};
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@gpambrozio/paseo-skills",
+  "version": "0.1.2",
+  "description": "Paseo plugin: lists the skills an agent can use, shows where each comes from, renders its SKILL.md, and invokes it",
+  "license": "MIT",
+  "homepage": "https://github.com/gpambrozio/paseo-plugins/tree/main/skills",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gpambrozio/paseo-plugins.git",
+    "directory": "skills"
+  },
+  "type": "module",
+  "files": [
+    "paseo-plugin.json",
+    "index.client.tsx",
+    "index.server.ts",
+    "client/",
+    "server/",
+    "shared/",
+    "CHANGELOG.md",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@getpaseo/client": "0.8.0",
+    "@getpaseo/plugin": "0.8.0",
+    "@getpaseo/protocol": "0.8.0",
+    "@tanstack/react-query": "^5.102.8",
+    "@types/node": "^26.5.0",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0",
+    "zod": "^4.5.4"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "skills",
+  "description": "Lists the skills an agent can use, renders each SKILL.md, and invokes it",
+  "requirements": {
+    "paseo": ">=0.8.0"
+  }
+}

package/server/resolve/claude.ts

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { dirsUpToRepoRoot } from "./repo-root";
+import { readSkillCandidates, type SkillDirectoryCandidate } from "./skill-directory";
+import type { SkillEntry } from "./skill-entry";
+
+export interface ClaudeResolveOptions {
+  cwd: string;
+  claudeHome: string;
+}
+
+interface InstalledPluginEntry {
+  scope?: string;
+  projectPath?: string;
+  installPath?: string;
+}
+
+function isInside(child: string, parent: string): boolean {
+  const normalizedChild = path.resolve(child);
+  const normalizedParent = path.resolve(parent);
+  return (
+    normalizedChild === normalizedParent ||
+    normalizedChild.startsWith(`${normalizedParent}${path.sep}`)
+  );
+}
+
+/**
+ * The plugin cache keeps every version ever fetched, so the directory listing
+ * cannot tell you what is live. installed_plugins.json can: each entry names the
+ * exact installPath in use. An entry with a projectPath applies only inside that
+ * directory, whatever its `scope` string says — real manifests carry
+ * `scope: "local"` entries that are per-project. An entry with no projectPath
+ * applies everywhere.
+ */
+async function readInstalledPluginDirs(
+  claudeHome: string,
+  cwd: string,
+): Promise<Array<{ pluginName: string; dir: string }>> {
+  const manifestPath = path.join(claudeHome, "plugins", "installed_plugins.json");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch {
+    return [];
+  }
+
+  const plugins = (parsed as { plugins?: Record<string, unknown> } | null)?.plugins;
+  if (!plugins || typeof plugins !== "object") return [];
+
+  const results: Array<{ pluginName: string; dir: string }> = [];
+  for (const [key, value] of Object.entries(plugins)) {
+    if (!Array.isArray(value)) continue;
+    const pluginName = key.split("@")[0] ?? key;
+    for (const entry of value as InstalledPluginEntry[]) {
+      if (!entry || typeof entry.installPath !== "string") continue;
+      // A projectPath scopes the entry to that directory regardless of what
+      // `scope` says — real manifests carry `scope: "local"` entries that are
+      // per-project. An entry with no projectPath applies everywhere.
+      if (typeof entry.projectPath === "string" && !isInside(cwd, entry.projectPath)) continue;
+      results.push({ pluginName, dir: path.join(entry.installPath, "skills") });
+    }
+  }
+  return results;
+}
+
+/**
+ * Precedence: the working directory, then each directory up to the repository
+ * root, then personal, then plugins. Claude loads `.claude/skills` from every
+ * one of those ancestors, so an agent working in a subdirectory still sees the
+ * skills checked in at the repo root. Plugin skills are namespaced
+ * `plugin:skill`, so in practice they never collide with the rest.
+ */
+export async function resolveClaudeSkills(options: ClaudeResolveOptions): Promise<SkillEntry[]> {
+  const [pluginDirs, dirs] = await Promise.all([
+    readInstalledPluginDirs(options.claudeHome, options.cwd),
+    dirsUpToRepoRoot(options.cwd),
+  ]);
+
+  const candidates: SkillDirectoryCandidate[] = dirs.map((dir, index) => ({
+    dir: path.join(dir, ".claude", "skills"),
+    kind: index === 0 ? "project" : "repo",
+    label: index === 0 ? "Project" : "Repository",
+  }));
+
+  candidates.push({
+    dir: path.join(options.claudeHome, "skills"),
+    kind: "personal",
+    label: "Personal",
+  });
+  for (const { pluginName, dir } of pluginDirs) {
+    candidates.push({
+      dir,
+      kind: "plugin",
+      label: pluginName,
+      nameFor: (name) => `${pluginName}:${name}`,
+    });
+  }
+
+  return readSkillCandidates(candidates);
+}

package/server/resolve/codex.ts

@@ -0,0 +1,50 @@
+import path from "node:path";
+
+import { dirsUpToRepoRoot } from "./repo-root";
+import { readSkillCandidates, type SkillDirectoryCandidate } from "./skill-directory";
+import type { SkillEntry } from "./skill-entry";
+
+export interface CodexResolveOptions {
+  cwd: string;
+  /** `$CODEX_HOME` or `~/.codex`. Only the legacy `skills` directory is read from it. */
+  codexHome: string;
+  /** `~/.agents`, the documented home for user-scoped skills. */
+  agentsHome: string;
+  /** `/etc/codex/skills`, the admin scope. */
+  adminSkillsDir: string;
+}
+
+/**
+ * Follows Codex's documented search path: `.agents/skills` in every directory
+ * from cwd up to the repository root, then `$HOME/.agents/skills`, then
+ * `/etc/codex/skills`.
+ *
+ * `.codex/skills` is read alongside each `.agents/skills` and at `$CODEX_HOME`
+ * because that is where Paseo's own orchestration sync writes and where older
+ * Codex builds looked. It sits second within each scope, so when a name lives
+ * in both the documented directory wins.
+ *
+ * Codex's bundled system skills have no path on disk and stay invisible here.
+ */
+export async function resolveCodexSkills(options: CodexResolveOptions): Promise<SkillEntry[]> {
+  const dirs = await dirsUpToRepoRoot(options.cwd);
+
+  const candidates: SkillDirectoryCandidate[] = dirs.flatMap((dir, index) => {
+    const scope =
+      index === 0
+        ? { kind: "project" as const, label: "Project" }
+        : { kind: "repo" as const, label: "Repository" };
+    return [
+      { dir: path.join(dir, ".agents", "skills"), ...scope },
+      { dir: path.join(dir, ".codex", "skills"), ...scope },
+    ];
+  });
+
+  candidates.push(
+    { dir: path.join(options.agentsHome, "skills"), kind: "personal", label: "Personal" },
+    { dir: path.join(options.codexHome, "skills"), kind: "personal", label: "Personal" },
+    { dir: options.adminSkillsDir, kind: "admin", label: "Admin" },
+  );
+
+  return readSkillCandidates(candidates);
+}

package/server/resolve/frontmatter.ts

@@ -0,0 +1,88 @@
+export interface ParsedSkillDocument {
+  frontmatter: Record<string, string>;
+  body: string;
+}
+
+function unquote(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function isIndented(line: string): boolean {
+  return /^[ \t]/.test(line);
+}
+
+/**
+ * Reads the leading `---` block of a SKILL.md.
+ *
+ * Supports the flat `key: value` pairs most skills use, plus `>` folded and `|`
+ * literal block scalars, which real skills do use for long descriptions. Lines
+ * that are indented belong to a nested structure, not the top level: they are
+ * skipped rather than trimmed into a top-level key, so a nested `metadata.name`
+ * cannot overwrite the skill's own name.
+ *
+ * A file whose fence is missing or unterminated is reported as all body with no
+ * frontmatter, which callers treat as "not a skill".
+ */
+export function parseFrontmatter(raw: string): ParsedSkillDocument {
+  const normalized = raw.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { frontmatter: {}, body: raw };
+  }
+
+  const lines = normalized.split("\n");
+  let closingIndex = -1;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index]!.trim() === "---") {
+      closingIndex = index;
+      break;
+    }
+  }
+  if (closingIndex === -1) {
+    return { frontmatter: {}, body: raw };
+  }
+
+  const frontmatter: Record<string, string> = {};
+  let index = 1;
+  while (index < closingIndex) {
+    const line = lines[index]!;
+    index += 1;
+    if (isIndented(line)) continue;
+
+    const separator = line.indexOf(":");
+    if (separator === -1) continue;
+    const key = line.slice(0, separator).trim();
+    if (key.length === 0) continue;
+    const rest = line.slice(separator + 1).trim();
+
+    if (/^[>|][-+]?$/.test(rest)) {
+      const continuation: string[] = [];
+      while (index < closingIndex && (isIndented(lines[index]!) || lines[index]!.trim() === "")) {
+        continuation.push(lines[index]!.trim());
+        index += 1;
+      }
+      while (continuation.length > 0 && continuation[continuation.length - 1] === "") {
+        continuation.pop();
+      }
+      frontmatter[key] =
+        rest[0] === ">"
+          ? continuation.filter((entry) => entry !== "").join(" ")
+          : continuation.join("\n");
+      continue;
+    }
+
+    frontmatter[key] = unquote(rest);
+  }
+
+  const body = lines
+    .slice(closingIndex + 1)
+    .join("\n")
+    .replace(/^\n+/, "");
+  return { frontmatter, body };
+}

package/server/resolve/repo-root.ts

@@ -0,0 +1,43 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Walks up from cwd looking for a `.git` entry. Matches a file as well as a
+ * directory so worktrees and submodules resolve. Stops at the filesystem root.
+ */
+export async function findRepoRoot(cwd: string): Promise<string | null> {
+  let current = path.resolve(cwd);
+  for (;;) {
+    try {
+      await stat(path.join(current, ".git"));
+      return current;
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return null;
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Every directory from cwd up to the repository root, cwd first. Both providers
+ * scan their skills directory in each of these, not only in cwd — a skill
+ * checked in at the repo root is available to an agent working in a
+ * subdirectory. Outside a repository the walk has nowhere to stop, so it yields
+ * cwd alone rather than climbing to the filesystem root.
+ */
+export async function dirsUpToRepoRoot(cwd: string): Promise<string[]> {
+  const start = path.resolve(cwd);
+  const repoRoot = await findRepoRoot(start);
+  if (!repoRoot || repoRoot === start) return [start];
+
+  const dirs = [start];
+  let current = start;
+  while (current !== repoRoot) {
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    dirs.push(parent);
+    current = parent;
+  }
+  return dirs;
+}

package/server/resolve/reported.ts

@@ -0,0 +1,80 @@
+/**
+ * The session's own view of what it can run, as reported by the provider rather
+ * than found on disk. This is the only way to see skills bundled inside an agent
+ * binary, which live on no scannable path.
+ *
+ * Deliberately free of Node imports and of any `@getpaseo/client` type, so it
+ * compiles into either bundle and does not depend on the daemon's SDK version.
+ */
+
+export interface ReportedCommand {
+  name: string;
+  description: string;
+  argumentHint: string;
+  kind?: "command" | "skill";
+}
+
+export interface ReportedSkill {
+  name: string;
+  description: string;
+  argumentHint: string;
+}
+
+export interface CommandsResult {
+  commands: ReportedCommand[];
+  error: string | null;
+}
+
+interface CommandsCapableHandle {
+  commands(): Promise<CommandsResult>;
+}
+
+/**
+ * The `paseo` object comes from the daemon's bundled client, not from this
+ * project's node_modules, so the method may be absent no matter what the types
+ * say. Structural detection keeps the plugin working on a daemon that predates
+ * `agent.commands()` instead of throwing at runtime.
+ */
+export function supportsCommands(handle: unknown): handle is CommandsCapableHandle {
+  return typeof (handle as Partial<CommandsCapableHandle> | null)?.commands === "function";
+}
+
+export interface ReportedSplit {
+  skills: ReportedSkill[];
+  commands: ReportedSkill[];
+}
+
+/**
+ * Reported entries that filesystem discovery did not already find, split into
+ * skills and session controls on the `kind` the provider assigned.
+ *
+ * `kind` is optional and is the provider's own judgement, not ground truth.
+ * Claude derives it from a hardcoded denylist of root-only commands and calls
+ * everything else a skill, so plenty of session controls land in the skills
+ * bucket. There is no better signal available: Claude's built-ins are compiled
+ * into its binary, so nothing on disk can confirm the split.
+ *
+ * An entry with no `kind` counts as a skill. Bucketing unclassified entries as
+ * commands would empty the skills section for any provider that omits the field.
+ */
+export function selectReported(
+  commands: readonly ReportedCommand[],
+  discoveredNames: readonly string[],
+): ReportedSplit {
+  const seen = new Set(discoveredNames);
+  const split: ReportedSplit = { skills: [], commands: [] };
+  for (const command of commands) {
+    if (seen.has(command.name)) continue;
+    seen.add(command.name);
+    const bucket = command.kind === "command" ? split.commands : split.skills;
+    bucket.push({
+      name: command.name,
+      description: command.description,
+      argumentHint: command.argumentHint,
+    });
+  }
+  const byName = (a: ReportedSkill, b: ReportedSkill) => a.name.localeCompare(b.name);
+  split.skills.sort(byName);
+  split.commands.sort(byName);
+  return split;
+}

package/server/resolve/skill-directory.ts

@@ -0,0 +1,93 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { parseFrontmatter } from "./frontmatter";
+import { dedupeByName, makeSkillId, type SkillEntry, type SkillSourceKind } from "./skill-entry";
+
+export interface SkillDirectoryCandidate {
+  dir: string;
+  kind: SkillSourceKind;
+  label: string;
+  /** Plugin skills are invoked as `plugin:skill`; everything else keeps its name. */
+  nameFor?: (frontmatterName: string) => string;
+}
+
+/**
+ * Reads a provider's whole search path. Candidates arrive in precedence order
+ * and the first copy of a name wins, so a project skill shadows a personal one
+ * without either being listed twice.
+ *
+ * The same directory can be named twice — a repository rooted at `$HOME` puts
+ * `~/.claude/skills` in both the repo walk and the personal scope — so a
+ * directory is read once, under the first scope that reached it.
+ */
+export async function readSkillCandidates(
+  candidates: SkillDirectoryCandidate[],
+): Promise<SkillEntry[]> {
+  const seen = new Set<string>();
+  const unique = candidates.filter((candidate) => {
+    const resolved = path.resolve(candidate.dir);
+    if (seen.has(resolved)) return false;
+    seen.add(resolved);
+    return true;
+  });
+
+  const groups = await Promise.all(
+    unique.map((candidate) =>
+      readSkillsFromDirectory(candidate.dir, candidate.kind, candidate.label, candidate.nameFor),
+    ),
+  );
+  return dedupeByName(groups.flat()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Scans one `skills` directory. Each direct child directory (or symlink to one)
+ * holding a SKILL.md is a skill. A missing directory is normal, not an error.
+ * An entry whose frontmatter lacks name or description is skipped, matching the
+ * providers — listing it would show a skill the agent cannot actually see.
+ */
+export async function readSkillsFromDirectory(
+  dir: string,
+  kind: SkillSourceKind,
+  label: string,
+  nameFor: (frontmatterName: string) => string = (name) => name,
+): Promise<SkillEntry[]> {
+  let dirEntries;
+  try {
+    dirEntries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const candidates = dirEntries.filter((entry) => entry.isDirectory() || entry.isSymbolicLink());
+  const results = await Promise.all(
+    candidates.map(async (entry): Promise<SkillEntry | null> => {
+      const skillPath = path.join(dir, entry.name, "SKILL.md");
+      let raw: string;
+      try {
+        raw = await readFile(skillPath, "utf8");
+      } catch {
+        return null;
+      }
+      const { frontmatter } = parseFrontmatter(raw);
+      const rawName = frontmatter.name;
+      const description = frontmatter.description;
+      if (!rawName || !description) return null;
+      const name = nameFor(rawName);
+      const userInvocable = frontmatter["user-invocable"] !== "false";
+      return {
+        id: makeSkillId(kind, dir, name),
+        name,
+        description,
+        source: { kind, label, dir },
+        path: skillPath,
+        userInvocable,
+        status: "discovered",
+      };
+    }),
+  );
+
+  return results
+    .filter((entry): entry is SkillEntry => entry !== null)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/server/resolve/skill-entry.ts

@@ -0,0 +1,39 @@
+/**
+ * Scopes, not directories. Both providers scan several directories per scope —
+ * Codex reads `.agents/skills` and legacy `.codex/skills` in the same walk — so
+ * a kind names where a skill applies, and `SkillSource.dir` names where it is.
+ */
+export type SkillSourceKind = "project" | "repo" | "personal" | "admin" | "plugin";
+
+export interface SkillSource {
+  kind: SkillSourceKind;
+  label: string;
+  dir: string;
+}
+
+export interface SkillEntry {
+  id: string;
+  name: string;
+  description: string;
+  source: SkillSource;
+  path: string;
+  userInvocable: boolean;
+  status: "discovered";
+}
+
+export function makeSkillId(kind: SkillSourceKind, dir: string, name: string): string {
+  return `${kind}:${dir}:${name}`;
+}
+
+/**
+ * First name wins. Callers pass directories in precedence order, so a project
+ * skill shadows a personal one of the same name without either being reported
+ * twice.
+ */
+export function dedupeByName(entries: SkillEntry[]): SkillEntry[] {
+  const byName = new Map<string, SkillEntry>();
+  for (const entry of entries) {
+    if (!byName.has(entry.name)) byName.set(entry.name, entry);
+  }
+  return [...byName.values()];
+}

package/server/sdk-types.ts

@@ -0,0 +1,24 @@
+/**
+ * A tripwire for the one hazard `skipLibCheck: true` hides.
+ *
+ * When `@getpaseo/client` fails to resolve, TypeScript does not complain: every
+ * Paseo API type silently degrades to `any` and `tsc` still exits 0, so a clean
+ * typecheck stops proving that any host call in this plugin is type-checked at
+ * all. `noImplicitAny` catches part of it — but only where our code destructures
+ * an SDK value. A handler that merely passes `paseo` through type-checks just as
+ * happily against `any`.
+ *
+ * The directive below is the check, and it fails in both directions:
+ *
+ * - types resolved   → the indexed access errors → the directive is used → pass
+ * - types degraded   → the access is `any`, no error → TS2578 "Unused
+ *                      '@ts-expect-error' directive" → fail
+ *
+ * This replaces the throwaway file the root CLAUDE.md used to ask contributors
+ * to write by hand. It is type-only, so it contributes nothing to either bundle.
+ */
+import type { PaseoAgentHandle } from "@getpaseo/client";
+
+// @ts-expect-error - Must stay an error. See above: if this member ever stops
+// erroring, the SDK types are `any` and nothing here is really being checked.
+export type SdkTypesResolved = PaseoAgentHandle["thisMemberDoesNotExist"];