@gpambrozio/paseo-skills 0.1.2

package/client/panel.tsx

@@ -0,0 +1,542 @@
+import { type PluginAgentPanelProps, useAgent, usePaseo, useRpc } from "@getpaseo/plugin/client";
+import { copyText, useToast } from "@getpaseo/plugin/client/react-native";
+import { useQuery } from "@tanstack/react-query";
+import { useCallback, useMemo, useState } from "react";
+import {
+  ActivityIndicator,
+  Platform,
+  Pressable,
+  ScrollView,
+  Text,
+  TextInput,
+  View,
+} from "react-native";
+import type { z } from "zod";
+
+import { useSkillsQuery } from "./skills-query";
+import { readSkill, ReportedSkillSchema, SkillEntrySchema } from "../shared/skills";
+
+type Skill = z.infer<typeof SkillEntrySchema>;
+type ReportedSkill = z.infer<typeof ReportedSkillSchema>;
+
+type Selection = { kind: "discovered"; id: string } | { kind: "reported"; name: string };
+
+// Menlo does not exist on Android, where an unknown family silently falls back
+// to the default proportional font.
+const MONO = Platform.select({ ios: "Menlo", default: "monospace" });
+
+// Groups render in resolver-precedence order, not in whatever order the
+// alphabetically-sorted skill list happens to introduce them.
+const SOURCE_ORDER: ReadonlyArray<Skill["source"]["kind"]> = [
+  "project",
+  "repo",
+  "personal",
+  "admin",
+  "plugin",
+];
+
+function groupBySource(skills: Skill[]): Array<{ label: string; skills: Skill[] }> {
+  const groups = new Map<string, { kind: Skill["source"]["kind"]; skills: Skill[] }>();
+  for (const skill of skills) {
+    const existing = groups.get(skill.source.label);
+    if (existing) existing.skills.push(skill);
+    else groups.set(skill.source.label, { kind: skill.source.kind, skills: [skill] });
+  }
+  return [...groups]
+    .sort(([labelA, groupA], [labelB, groupB]) => {
+      const rank = SOURCE_ORDER.indexOf(groupA.kind) - SOURCE_ORDER.indexOf(groupB.kind);
+      return rank !== 0 ? rank : labelA.localeCompare(labelB);
+    })
+    .map(([label, group]) => ({ label, skills: group.skills }));
+}
+
+function detailStyles(theme: PluginAgentPanelProps["theme"], padding: number) {
+  return {
+    screen: { flex: 1, backgroundColor: theme.colors.surface0 },
+    content: { padding },
+    back: { color: theme.colors.accent, marginBottom: padding },
+    name: { color: theme.colors.foreground, fontSize: 18, marginBottom: 4 },
+    description: { color: theme.colors.foregroundMuted, marginBottom: padding },
+    path: { color: theme.colors.foregroundMuted, fontSize: 12, fontFamily: MONO },
+    copy: { color: theme.colors.accent, marginTop: 4, marginBottom: padding },
+    argsInput: {
+      color: theme.colors.foreground,
+      borderWidth: 1,
+      borderColor: theme.colors.foregroundMuted,
+      borderRadius: 8,
+      paddingHorizontal: 12,
+      paddingVertical: 8,
+      marginBottom: 8,
+    },
+    invoke: {
+      backgroundColor: theme.colors.accent,
+      borderRadius: 8,
+      paddingVertical: 10,
+      alignItems: "center" as const,
+      marginBottom: padding,
+    },
+    invokeLabel: { color: theme.colors.accentForeground, fontSize: 15 },
+    body: { color: theme.colors.foreground, fontFamily: MONO, fontSize: 12 },
+    error: { color: theme.colors.statusDanger, marginBottom: padding },
+    notInvocable: { color: theme.colors.foregroundMuted, marginBottom: padding },
+  };
+}
+
+type DetailStyles = ReturnType<typeof detailStyles>;
+
+/**
+ * Owns the arguments field and the send. The re-entrancy guard lives here rather
+ * than in each detail screen: a double tap on a slow connection would otherwise
+ * invoke the skill twice on the user's live agent.
+ *
+ * `onInvoked` is deliberately not `onBack`. Both used to be the same callback,
+ * which meant a successful invoke left the user on the Skills tab watching the
+ * list — the turn it had just started was one tab away, with nothing saying so.
+ */
+function useInvoke(agentId: string, onInvoked: () => void) {
+  const paseo = usePaseo();
+  const [args, setArgs] = useState("");
+  const [invokeError, setInvokeError] = useState<string | null>(null);
+  const [isInvoking, setIsInvoking] = useState(false);
+
+  async function invoke(name: string) {
+    if (isInvoking) return;
+    setIsInvoking(true);
+    setInvokeError(null);
+    const trimmed = args.trim();
+    try {
+      await paseo.agents.ref(agentId).send(trimmed ? `/${name} ${trimmed}` : `/${name}`);
+      onInvoked();
+    } catch (error) {
+      setInvokeError(error instanceof Error ? error.message : String(error));
+      setIsInvoking(false);
+    }
+  }
+
+  return { args, setArgs, invoke, invokeError, isInvoking };
+}
+
+/** The arguments field, error line, and Invoke button, shared by both detail screens. */
+function InvokeControls({
+  styles,
+  theme,
+  name,
+  controls,
+}: {
+  styles: DetailStyles;
+  theme: PluginAgentPanelProps["theme"];
+  name: string;
+  controls: ReturnType<typeof useInvoke>;
+}) {
+  return (
+    <>
+      <TextInput
+        style={styles.argsInput}
+        value={controls.args}
+        onChangeText={controls.setArgs}
+        placeholder="Arguments (optional)"
+        placeholderTextColor={theme.colors.foregroundMuted}
+        autoCorrect={false}
+      />
+      {controls.invokeError ? <Text style={styles.error}>{controls.invokeError}</Text> : null}
+      <Pressable
+        style={styles.invoke}
+        disabled={controls.isInvoking}
+        onPress={() => void controls.invoke(name)}
+      >
+        <Text style={styles.invokeLabel}>{controls.isInvoking ? "Sending…" : "Invoke"}</Text>
+      </Pressable>
+    </>
+  );
+}
+
+function SkillDetail({
+  theme,
+  layout,
+  agentId,
+  skillId,
+  userInvocable,
+  onBack,
+  onInvoked,
+}: {
+  theme: PluginAgentPanelProps["theme"];
+  layout: PluginAgentPanelProps["layout"];
+  agentId: string;
+  skillId: string;
+  userInvocable: boolean;
+  onBack: () => void;
+  onInvoked: () => void;
+}) {
+  const callReadSkill = useRpc(readSkill);
+  const toast = useToast();
+  const controls = useInvoke(agentId, onInvoked);
+
+  const query = useQuery({
+    queryKey: ["skill", agentId, skillId],
+    queryFn: () => callReadSkill({ agentId, skillId }),
+    retry: false,
+  });
+
+  const padding = layout.compact ? 12 : 20;
+  const styles = useMemo(() => detailStyles(theme, padding), [theme, padding]);
+
+  return (
+    <ScrollView style={styles.screen} contentContainerStyle={styles.content}>
+      <Pressable onPress={onBack}>
+        <Text style={styles.back}>← All skills</Text>
+      </Pressable>
+      {query.isPending ? (
+        <ActivityIndicator color={theme.colors.foregroundMuted} />
+      ) : query.isError ? (
+        <Text style={styles.error}>{(query.error as Error).message}</Text>
+      ) : (
+        <>
+          <Text style={styles.name}>{query.data.name}</Text>
+          <Text style={styles.description}>{query.data.description}</Text>
+          <Text style={styles.path} selectable>
+            {query.data.path}
+          </Text>
+          <Pressable
+            onPress={() => {
+              // The path is `selectable` above, so a platform that denies
+              // programmatic copying still leaves long-press and OS Copy.
+              const path = query.data.path;
+              void copyText(path).then(
+                () => toast.show("Path copied", { variant: "success" }),
+                () => toast.error("Could not copy. Select the path and use Copy."),
+              );
+            }}
+          >
+            <Text style={styles.copy}>Copy path</Text>
+          </Pressable>
+          {userInvocable ? (
+            <InvokeControls
+              styles={styles}
+              theme={theme}
+              name={query.data.name}
+              controls={controls}
+            />
+          ) : (
+            <Text style={styles.notInvocable}>
+              This skill is model-invoked only. The agent can use it, but it cannot be run as a
+              command.
+            </Text>
+          )}
+          <Text style={styles.body}>{query.data.body}</Text>
+        </>
+      )}
+    </ScrollView>
+  );
+}
+
+/**
+ * Detail for an entry the session reported. There is no `SKILL.md` behind it, so
+ * there is no path, no body, and no `skills.read` call — but the description
+ * renders in full here rather than clipped to two lines, and the agent can still
+ * be asked to run it.
+ */
+function ReportedDetail({
+  theme,
+  layout,
+  agentId,
+  entry,
+  onBack,
+  onInvoked,
+}: {
+  theme: PluginAgentPanelProps["theme"];
+  layout: PluginAgentPanelProps["layout"];
+  agentId: string;
+  entry: ReportedSkill;
+  onBack: () => void;
+  onInvoked: () => void;
+}) {
+  const controls = useInvoke(agentId, onInvoked);
+  const padding = layout.compact ? 12 : 20;
+  const styles = useMemo(() => detailStyles(theme, padding), [theme, padding]);
+
+  return (
+    <ScrollView style={styles.screen} contentContainerStyle={styles.content}>
+      <Pressable onPress={onBack}>
+        <Text style={styles.back}>← All skills</Text>
+      </Pressable>
+      <Text style={styles.name}>{entry.name}</Text>
+      {entry.argumentHint ? <Text style={styles.path}>{entry.argumentHint}</Text> : null}
+      <Text style={[styles.description, { marginTop: 8 }]} selectable>
+        {entry.description}
+      </Text>
+      <InvokeControls styles={styles} theme={theme} name={entry.name} controls={controls} />
+      <Text style={styles.notInvocable}>
+        The agent reported this itself. It has no SKILL.md on disk, so there is nothing further to
+        show.
+      </Text>
+    </ScrollView>
+  );
+}
+
+function listStyles(theme: PluginAgentPanelProps["theme"], padding: number) {
+  return {
+    screen: { flex: 1, backgroundColor: theme.colors.surface0 },
+    content: { padding },
+    search: {
+      color: theme.colors.foreground,
+      backgroundColor: theme.colors.surface0,
+      borderWidth: 1,
+      borderColor: theme.colors.foregroundMuted,
+      borderRadius: 8,
+      paddingHorizontal: 12,
+      paddingVertical: 8,
+      marginBottom: padding,
+    },
+    groupLabel: {
+      color: theme.colors.foregroundMuted,
+      fontSize: 12,
+      textTransform: "uppercase" as const,
+      marginTop: padding,
+      marginBottom: 6,
+    },
+    row: { paddingVertical: 10 },
+    name: { color: theme.colors.foreground, fontSize: 15 },
+    hint: { color: theme.colors.foregroundMuted, fontSize: 13, fontFamily: MONO },
+    description: { color: theme.colors.foregroundMuted, fontSize: 13, marginTop: 2 },
+    groupNote: { color: theme.colors.foregroundMuted, fontSize: 12, marginBottom: 6 },
+    message: { color: theme.colors.foregroundMuted },
+    error: { color: theme.colors.statusDanger },
+    groupError: { color: theme.colors.statusDanger, fontSize: 13, marginBottom: 6 },
+  };
+}
+
+type ListStyles = ReturnType<typeof listStyles>;
+
+export function SkillsPanel({ theme, layout, agentId, navigation }: PluginAgentPanelProps) {
+  // Only a liveness check — the panel reads everything else off the query, whose
+  // own hook is what tracks `cwd`.
+  const agentCwd = useAgent(agentId, (snapshot) => snapshot.cwd);
+  const [search, setSearch] = useState("");
+  // Discovered entries are addressed by their stable id; reported ones have no id
+  // and are addressed by name, which the server guarantees is unique across both
+  // reported buckets.
+  const [selected, setSelected] = useState<Selection | null>(null);
+
+  const query = useSkillsQuery(agentId);
+
+  /**
+   * Invoking sent a message to the user's live agent, so the agent's own tab is
+   * where the result appears — leaving the user on the Skills tab hides the
+   * thing they just asked for. `openAgent` runs the app's own `navigateToAgent`
+   * against this host, which is the same call `github-board` makes after a send.
+   *
+   * The selection is cleared first, so the panel is back on its list when the
+   * user returns to this tab rather than on the detail of a skill already run.
+   *
+   * `navigation` is typed optional because hosts before 0.7.0-beta.3 passed
+   * nothing; this plugin requires Paseo >=0.8.0 and each app checks that against
+   * its own version before evaluating this bundle, so every client that can run
+   * this code passes it. The `undefined` branch is the old behaviour — back to
+   * the list, still on this tab — rather than a broken one.
+   */
+  const handleInvoked = useCallback(
+    function handleInvoked() {
+      setSelected(null);
+      navigation?.openAgent({ agentId });
+    },
+    [agentId, navigation],
+  );
+
+  const padding = layout.compact ? 12 : 20;
+  const styles = useMemo(() => listStyles(theme, padding), [theme, padding]);
+
+  const term = search.trim().toLowerCase();
+
+  const matches = (skill: { name: string; description: string }) =>
+    term.length === 0 ||
+    skill.name.toLowerCase().includes(term) ||
+    skill.description.toLowerCase().includes(term);
+
+  const filtered = useMemo(
+    () => (query.data?.skills ?? []).filter(matches),
+    [query.data, term],
+  );
+
+  const filteredReportedSkills = useMemo(
+    () => (query.data?.reported.skills ?? []).filter(matches),
+    [query.data, term],
+  );
+
+  const filteredReportedCommands = useMemo(
+    () => (query.data?.reported.commands ?? []).filter(matches),
+    [query.data, term],
+  );
+
+  if (selected?.kind === "discovered") {
+    const entry = (query.data?.skills ?? []).find((skill) => skill.id === selected.id);
+    return (
+      <SkillDetail
+        theme={theme}
+        layout={layout}
+        agentId={agentId}
+        skillId={selected.id}
+        userInvocable={entry?.userInvocable ?? true}
+        onBack={() => setSelected(null)}
+        onInvoked={handleInvoked}
+      />
+    );
+  }
+
+  if (selected?.kind === "reported") {
+    const reportedEntry = [
+      ...(query.data?.reported.skills ?? []),
+      ...(query.data?.reported.commands ?? []),
+    ].find((entry) => entry.name === selected.name);
+    // A refetch can drop an entry the session no longer reports. Fall back to the
+    // list rather than rendering a detail screen for something that is gone.
+    if (!reportedEntry) {
+      setSelected(null);
+      return null;
+    }
+    return (
+      <ReportedDetail
+        theme={theme}
+        layout={layout}
+        agentId={agentId}
+        entry={reportedEntry}
+        onBack={() => setSelected(null)}
+        onInvoked={handleInvoked}
+      />
+    );
+  }
+
+  if (agentCwd == null) {
+    return (
+      <View style={[styles.screen, { padding }]}>
+        <Text style={styles.message}>This agent is no longer available.</Text>
+      </View>
+    );
+  }
+
+  if (query.isPending) {
+    return (
+      <View style={[styles.screen, { padding }]}>
+        <ActivityIndicator color={theme.colors.foregroundMuted} />
+      </View>
+    );
+  }
+
+  if (query.isError) {
+    return (
+      <View style={[styles.screen, { padding }]}>
+        <Text style={styles.error}>{(query.error as Error).message}</Text>
+      </View>
+    );
+  }
+
+  const reported = query.data?.reported;
+  // Every provider reaches this screen. A provider whose skill directories
+  // nobody has documented still reports what its session loaded, so the panel
+  // renders that and says where it came from rather than refusing outright.
+  const scanned = query.data?.scanned ?? false;
+
+  return (
+    <ScrollView style={styles.screen} contentContainerStyle={styles.content}>
+      <TextInput
+        style={styles.search}
+        value={search}
+        onChangeText={setSearch}
+        placeholder="Search skills"
+        placeholderTextColor={theme.colors.foregroundMuted}
+        autoCorrect={false}
+        autoCapitalize="none"
+      />
+      {scanned ? null : (
+        <Text style={styles.groupNote}>
+          Skill files are only scanned for Claude and Codex. Everything below is what the{" "}
+          {query.data?.provider ?? "provider"} session reported.
+        </Text>
+      )}
+      {filtered.length === 0 &&
+      filteredReportedSkills.length === 0 &&
+      filteredReportedCommands.length === 0 &&
+      reported?.error == null ? (
+        <Text style={styles.message}>
+          {term.length > 0 ? "No skills match that search." : "No skills found."}
+        </Text>
+      ) : null}
+      {groupBySource(filtered).map((group) => (
+        <View key={group.label}>
+          <Text style={styles.groupLabel}>{group.label}</Text>
+          {group.skills.map((skill) => (
+            <Pressable
+              key={skill.id}
+              style={styles.row}
+              onPress={() => setSelected({ kind: "discovered", id: skill.id })}
+            >
+              <Text style={styles.name}>{skill.name}</Text>
+              <Text style={styles.description} numberOfLines={2}>
+                {skill.description}
+              </Text>
+            </Pressable>
+          ))}
+        </View>
+      ))}
+      {reported?.error ? (
+        <View>
+          <Text style={styles.groupLabel}>Reported by the agent</Text>
+          <Text style={styles.groupError}>{reported.error}</Text>
+        </View>
+      ) : null}
+      {filteredReportedSkills.length > 0 ? (
+        <ReportedGroup
+          styles={styles}
+          label="Built-in skills"
+          note="Loaded by the running session. These have no SKILL.md to read."
+          entries={filteredReportedSkills}
+          onSelect={(name) => setSelected({ kind: "reported", name })}
+        />
+      ) : null}
+      {filteredReportedCommands.length > 0 ? (
+        <ReportedGroup
+          styles={styles}
+          label="Built-in commands"
+          note="Session controls the agent reported, not skills."
+          entries={filteredReportedCommands}
+          onSelect={(name) => setSelected({ kind: "reported", name })}
+        />
+      ) : null}
+    </ScrollView>
+  );
+}
+
+/**
+ * Rows open a reduced detail screen: no path and no body, but the full
+ * description and an Invoke button.
+ */
+function ReportedGroup({
+  styles,
+  label,
+  note,
+  entries,
+  onSelect,
+}: {
+  styles: ListStyles;
+  label: string;
+  note: string;
+  entries: ReportedSkill[];
+  onSelect: (name: string) => void;
+}) {
+  return (
+    <View>
+      <Text style={styles.groupLabel}>{label}</Text>
+      <Text style={styles.groupNote}>{note}</Text>
+      {entries.map((entry) => (
+        <Pressable key={entry.name} style={styles.row} onPress={() => onSelect(entry.name)}>
+          <Text style={styles.name}>
+            {entry.name}
+            {entry.argumentHint ? <Text style={styles.hint}> {entry.argumentHint}</Text> : null}
+          </Text>
+          <Text style={styles.description} numberOfLines={2}>
+            {entry.description}
+          </Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+}

package/client/pill.tsx

@@ -0,0 +1,116 @@
+import {
+  type PluginButtonIconProps,
+  type PluginButtonRegistration,
+  type PluginClientContext,
+} from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useEffect } from "react";
+
+import { countEntries, useSkillsQuery } from "./skills-query";
+
+/** What the pill reads before the count is known, and the accessible name throughout. */
+const TITLE = "Skills";
+
+/**
+ * Paseo draws the pill from a plain description — an icon, a label and a press
+ * behaviour — so the count cannot come from a render. It comes from here: the
+ * icon is the one part of the description that *is* a component, so it runs the
+ * query and pushes the answer back into the label.
+ *
+ * That indirection buys the property the count needs. `contributePills`
+ * registers a pill for every agent on the host, but the host only mounts one
+ * when that agent's composer is on screen, so the scan stays bounded to the
+ * agents the user is looking at rather than to every agent that exists.
+ *
+ * The label is deliberately `Skills` until the query answers — a pill that
+ * reads `Skills 0` for a second on every mount is worse than one that reads
+ * `Skills` and then gains a number.
+ */
+function createPillIcon(agentId: string, pill: { current?: PluginButtonRegistration }) {
+  return function SkillsPillIcon({ size, color }: PluginButtonIconProps) {
+    const query = useSkillsQuery(agentId);
+    const label = query.data ? `${TITLE} ${countEntries(query.data)}` : TITLE;
+
+    // Updating an already-removed registration is a documented no-op, so an
+    // agent that goes away mid-query needs no teardown here.
+    useEffect(() => {
+      pill.current?.update({ label });
+    }, [pill, label]);
+
+    return <Icon name="Sparkles" size={size} color={color} />;
+  };
+}
+
+/**
+ * One pill per agent, opening that agent's Skills panel.
+ *
+ * The client entry runs once per installation per connected app, so this owns
+ * the whole set: it seeds from the agents that already exist, follows the update
+ * stream for the rest, and removes every registration on teardown.
+ */
+export function contributePills(client: PluginClientContext) {
+  const pills = new Map<string, PluginButtonRegistration>();
+
+  function addPill(agentId: string, workspaceId: string) {
+    // Agent updates fire on every turn of every agent. Nothing in the pill
+    // depends on the snapshot, so re-registering would only unmount the icon
+    // and refire its query — and Paseo rejects a duplicate id outright.
+    if (pills.has(agentId)) return;
+
+    // The icon needs the registration that is about to be created from it, so
+    // it reaches the registration through this box rather than through a prop.
+    const pill: { current?: PluginButtonRegistration } = {};
+    pill.current = client.addComposerPill({
+      id: "skills",
+      workspaceId,
+      agentId,
+      button: {
+        title: TITLE,
+        label: TITLE,
+        icon: createPillIcon(agentId, pill),
+        behavior: {
+          kind: "action",
+          onPress() {
+            client.openPanel("skills", { workspaceId, agentId });
+          },
+        },
+      },
+    });
+    pills.set(agentId, pill.current);
+  }
+
+  function removePill(agentId: string) {
+    pills.get(agentId)?.remove();
+    pills.delete(agentId);
+  }
+
+  const unsubscribe = client.paseo.agents.subscribe((update) => {
+    if (update.kind === "remove") {
+      removePill(update.agentId);
+      return;
+    }
+    const { id, workspaceId } = update.agent;
+    if (workspaceId) addPill(id, workspaceId);
+  });
+
+  // `subscribe` only reports change. Without this seed, an agent that was
+  // already sitting idle when the app connected would have no pill until it
+  // next did something.
+  client.paseo.agents
+    .list()
+    .then((result) => {
+      // A `for…of` body would capture the loop binding, not the entry.
+      result.entries.forEach(({ agent }) => {
+        if (agent.workspaceId) addPill(agent.id, agent.workspaceId);
+      });
+    })
+    .catch((error: unknown) => {
+      console.error("skills: could not seed composer pills", error);
+    });
+
+  return () => {
+    unsubscribe();
+    pills.forEach((pill) => pill.remove());
+    pills.clear();
+  };
+}

package/client/skills-query.tsx

@@ -0,0 +1,29 @@
+import { useAgent, useRpc } from "@getpaseo/plugin/client";
+import { useQuery } from "@tanstack/react-query";
+import type { z } from "zod";
+
+import { listSkills } from "../shared/skills";
+
+type SkillsResult = z.infer<(typeof listSkills)["output"]>;
+
+/**
+ * The panel and the composer pill ask the same question, so they share a query
+ * key and answer each other's cache: opening the panel from a pill that has
+ * already counted costs no second scan. `cwd` is in the key because a rebased or
+ * moved workspace changes what discovery finds.
+ */
+export function useSkillsQuery(agentId: string) {
+  const cwd = useAgent(agentId, (snapshot) => snapshot.cwd);
+  const callListSkills = useRpc(listSkills);
+  return useQuery({
+    queryKey: ["skills", agentId, cwd],
+    queryFn: () => callListSkills({ agentId }),
+    enabled: cwd != null,
+    retry: false,
+  });
+}
+
+/** Everything the panel lists, which is what the pill's badge promises. */
+export function countEntries(data: SkillsResult): number {
+  return data.skills.length + data.reported.skills.length + data.reported.commands.length;
+}