skills-mcp

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { RemoteSkill, SkillsMcpStatus } from '../types'
5
6const skills = atom({ plugin: 'skills-mcp', key: 'skills' } as const, [] as RemoteSkill[])
7const status = atom({ plugin: 'skills-mcp', key: 'status' } as const, {} as SkillsMcpStatus)
8
9const SECTION_ID = 'skills-mcp:index'
10const STORE_KEY = 'skills-mcp:index'
11/** `skill://<skill-path>/SKILL.md`, the skill's name the path's last segment (SEP-2640). */
12const SKILL_MD = /^skill:\/\/(?:.+\/)?([a-z0-9][a-z0-9-]*)\/SKILL\.md$/
13/**
14 * The pre-v1 SEP-2640 index a server may still publish. Claude Code caches resources/list, but
15 * reads go to the server, so polling it sees skills added since connect.
16 */
17const INDEX_URI = 'skill://index.json'
18
19type ListedResource = { uri: string; name: string; description?: string; server: string }
20/** Either pre-v1 shape: `url` + `frontmatter` (as servers shipped it), or top-level `name` / `description`. */
21type IndexEntry = { url: string; name?: string; description?: string; frontmatter?: { name?: string; description?: string } }
22
23function errorText(err: unknown): string {
24  return err instanceof Error ? err.message : String(err)
25}
26
27/** Labels skills `server:name` where two servers share a name. */
28function labelled(found: readonly Omit<RemoteSkill, 'label'>[]): RemoteSkill[] {
29  const servers = new Map<string, Set<string>>()
30  for (const s of found) servers.set(s.name, (servers.get(s.name) ?? new Set()).add(s.server))
31  return found.map(s => ({ ...s, label: (servers.get(s.name)?.size ?? 0) > 1 ? `${s.server}:${s.name}` : s.name }))
32}
33
34/** The skills among a server's listed resources. */
35function fromListing(resources: readonly ListedResource[]) {
36  return resources.flatMap(r => {
37    const name = SKILL_MD.exec(r.uri)?.[1]
38    return name ? [{ name, description: r.description ?? '', uri: r.uri, server: r.server }] : []
39  })
40}
41
42/** Skills Claude Code already loads natively (as `<server>:<name>`) are left to it. */
43async function withoutNative($: EngineInterface, list: RemoteSkill[]): Promise<RemoteSkill[]> {
44  const commands = new Set((await $.command.list()).map(c => c.name))
45  return list.filter(s => !commands.has(`${s.server}:${s.name}`))
46}
47
48/** A server's live index, or undefined when it publishes none or the read fails. */
49async function readIndex($: EngineInterface, server: string) {
50  const ran = await $.tool.call({ tool: 'ReadMcpResourceTool', server, uri: INDEX_URI })
51  if (ran.deny !== undefined || ran.isError || ran.result.error) return undefined
52  const index = JSON.parse(ran.result.contents.map(c => c.text ?? '').join('')) as { skills?: IndexEntry[] }
53  return (index.skills ?? []).flatMap(e => {
54    const name = e.frontmatter?.name ?? e.name ?? SKILL_MD.exec(e.url)?.[1]
55    const description = e.frontmatter?.description ?? e.description ?? ''
56    return name && SKILL_MD.test(e.url) ? [{ name, description, uri: e.url, server }] : []
57  })
58}
59
60/** Whether this session has read the servers once: the first read replaces the cached index unannounced. */
61let hasRead = false
62
63async function refresh($: EngineInterface, server: string): Promise<RemoteSkill[]> {
64  try {
65    const ran = await $.tool.call({ tool: 'ListMcpResourcesTool', ...(server ? { server } : {}) })
66    if (ran.deny !== undefined) throw new Error(ran.deny)
67    if (ran.isError) throw new Error(String(ran.result ?? 'ListMcpResourcesTool failed'))
68    const listed = ran.result as ListedResource[]
69    const found = []
70    for (const name of new Set(listed.map(r => r.server))) {
71      const own = listed.filter(r => r.server === name)
72      // The listing is as of connect; a server's index is read live, so new skills show at once.
73      const live = own.some(r => r.uri === INDEX_URI) ? await readIndex($, name) : undefined
74      found.push(...(live ?? fromListing(own)))
75    }
76    const fresh = await withoutNative($, labelled(found))
77    const previous = await read($, skills)
78    // The index rides in the system prompt: write it only when it changed, so the prompt cache holds.
79    if (JSON.stringify(previous) !== JSON.stringify(fresh)) {
80      await update($, skills, () => fresh)
81      await $.store.set(STORE_KEY, fresh)
82      if (hasRead) await announce($, previous, fresh)
83    }
84    hasRead = true
85    await update($, status, () => ({ refreshedAt: Date.now() }))
86    $.ui.status(fresh.length ? `${fresh.length} MCP skills` : undefined)
87    return fresh
88  } catch (err) {
89    await update($, status, s => ({ ...s, error: errorText(err) }))
90    return read($, skills)
91  }
92}
93
94/**
95 * Tells the person (a toast) and the model (a note in the conversation, read from its next
96 * request, mid-turn included) what came and went. The note matters where a managed plugin keeps
97 * user mods out of the system prompt, and it shows the change the moment it lands.
98 */
99async function announce($: EngineInterface, before: readonly RemoteSkill[], after: readonly RemoteSkill[]) {
100  const had = new Map(before.map(s => [s.label, s]))
101  const has = new Map(after.map(s => [s.label, s]))
102  const added = after.filter(s => !had.has(s.label))
103  const removed = before.filter(s => !has.has(s.label))
104  const edited = after.filter(s => had.has(s.label) && had.get(s.label)?.description !== s.description)
105  if (added.length + removed.length + edited.length === 0) return
106
107  $.ui.toast(`MCP skills: ${[...added.map(s => `+${s.label}`), ...removed.map(s => `-${s.label}`), ...edited.map(s => `~${s.label}`)].join(' ')}`)
108  const line = (s: RemoteSkill) => `- ${s.label}: ${s.description} (server: ${s.server}, uri: ${s.uri})`
109  const text = [
110    'The MCP skills available changed just now.',
111    ...(added.length ? ['Added:', ...added.map(line)] : []),
112    ...(edited.length ? ['Changed:', ...edited.map(line)] : []),
113    ...(removed.length ? [`Removed (no longer available): ${removed.map(s => s.label).join(', ')}`] : []),
114    'To use one, read its SKILL.md with ReadMcpResourceTool (server and uri above) before the task, then follow it.',
115  ].join('\n')
116  await $.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } })
117}
118
119/** Seeds the index from the last session's, so the first turn has it before the servers answer. */
120async function seed($: EngineInterface) {
121  const cached = await $.store.get(STORE_KEY)
122  if (Array.isArray(cached) && (await read($, skills)).length === 0) {
123    await update($, skills, () => cached as RemoteSkill[])
124  }
125}
126
127function indexSection(list: readonly RemoteSkill[]): string {
128  return [
129    '# Skills served over MCP',
130    "MCP servers serve these Agent Skills as resources. When a task matches a skill's",
131    'description, read its SKILL.md with ReadMcpResourceTool (the server and uri below)',
132    'before starting, then follow it. Paths a skill mentions are relative to its folder:',
133    'for skill://<path>/SKILL.md, `references/x.md` is skill://<path>/references/x.md, read',
134    'the same way; ReadMcpResourceDirTool lists a folder. This index is kept current for',
135    'you: do not list resources to look for skills. The person can also run one as /<name>.',
136    '',
137    ...list.map(s => `- ${s.label}: ${s.description} (server: ${s.server}, uri: ${s.uri})`),
138  ].join('\n')
139}
140
141export const register: Register = (on, options) => {
142  const server = String(options.server ?? '')
143  const refreshMs = Number(options.refreshSeconds ?? 2) * 1000
144
145  on('session.start', async ($, e, next) => {
146    await $.command.register({
147      name: 'skills-mcp',
148      description: 'Re-read the skills MCP servers serve',
149    })
150    await seed($)
151    void refresh($, server)
152    if (refreshMs > 0) $.clock.every(refreshMs, () => void refresh($, server))
153    return next(e)
154  })
155
156  on('command.run', { command: 'skills-mcp' }, async $ => {
157    const list = await refresh($, server)
158    const { error } = await read($, status)
159    if (error) return { text: `Could not read the MCP skill index: ${error}` }
160    if (list.length === 0) return { text: 'No connected MCP server serves skill:// resources.' }
161    return { text: [`${list.length} MCP skills:`, ...list.map(s => `  ${s.label}  ${s.description}`)].join('\n') }
162  })
163
164  on('prompt.compose', async ($, e, next) => {
165    const composed = await next(e)
166    const list = await read($, skills)
167    if (list.length === 0 || e.traits.includes('bare')) return composed
168    return { sections: [...composed.sections, { id: SECTION_ID, text: indexSection(list), scope: 'session' as const }] }
169  })
170}
171

1/** One skill an MCP server serves, found as a `skill://<path>/SKILL.md` resource. */
2export type RemoteSkill = {
3  /** The skill's name: the last segment of its path. */
4  name: string
5  /** What the model and the person call it: `name`, or `server:name` when two servers serve one name. */
6  label: string
7  description: string
8  /** The SKILL.md resource's URI. */
9  uri: string
10  /** The MCP server serving it, as /mcp lists it. */
11  server: string
12}
13
14export type SkillsMcpStatus = {
15  /** When the index was last read from the servers, as ms since the epoch. */
16  refreshedAt?: number
17  error?: string
18}
19
20declare module 'claude-code' {
21  interface PluginState {
22    'skills-mcp': {
23      skills: RemoteSkill[]
24      status: SkillsMcpStatus
25    }
26  }
27}
28