The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * Discovers fx skills for the `$` picker by scanning the SKILL.md folders fx |
| 3 | * reads (fx 0.0.13, src/builtins/skills.zig), so no `fx acp` session starts |
| 4 | * for a composer menu. |
| 5 | * |
| 6 | * @module provider-fx/server/skills |
| 7 | */ |
| 8 | import type { ServerProviderSkill } from "@t3tools/contracts"; |
| 9 | import * as Effect from "effect/Effect"; |
| 10 | import * as FileSystem from "effect/FileSystem"; |
| 11 | import * as Option from "effect/Option"; |
| 12 | import * as Path from "effect/Path"; |
| 13 | import type * as PlatformError from "effect/PlatformError"; |
| 14 | import * as Stream from "effect/Stream"; |
| 15 | |
| 16 | /** |
| 17 | * fx's menu order: managed `~/.fx/skills`, then the workspace's `.fx/skills` |
| 18 | * and `skills/`, then every compatibility root (`skillGroupRank` in |
| 19 | * src/core/skills/skill_runtime.zig). Symlinked skill folders are followed |
| 20 | * everywhere except the managed root. |
| 21 | */ |
| 22 | type SkillRoot = { |
| 23 | readonly relative: string; |
| 24 | readonly rank: 0 | 1 | 2; |
| 25 | readonly followsLinks?: false; |
| 26 | }; |
| 27 | |
| 28 | const FX_WORKSPACE_ROOTS: ReadonlyArray<SkillRoot> = [ |
| 29 | { relative: ".fx/skills", rank: 1 }, |
| 30 | { relative: "skills", rank: 1 }, |
| 31 | { relative: ".opencode/skills", rank: 2 }, |
| 32 | { relative: ".codex/skills", rank: 2 }, |
| 33 | { relative: ".claude/skills", rank: 2 }, |
| 34 | { relative: ".agents/skills", rank: 2 }, |
| 35 | { relative: ".claw/skills", rank: 2 }, |
| 36 | ]; |
| 37 | const FX_HOME_ROOTS: ReadonlyArray<SkillRoot> = [ |
| 38 | { relative: ".fx/skills", rank: 0, followsLinks: false }, |
| 39 | { relative: ".config/opencode/skills", rank: 2 }, |
| 40 | { relative: ".codex/skills", rank: 2 }, |
| 41 | { relative: ".claude/skills", rank: 2 }, |
| 42 | { relative: ".agents/skills", rank: 2 }, |
| 43 | { relative: ".claw/skills", rank: 2 }, |
| 44 | ]; |
| 45 | |
| 46 | const MAX_FRONTMATTER_BYTES = 64 * 1024; |
| 47 | const MAX_NAME_BYTES = 256; |
| 48 | const BLOCK_DESCRIPTION_STYLES = new Set([">", ">-", "|"]); |
| 49 | const encoder = new TextEncoder(); |
| 50 | const strictDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }); |
| 51 | const lenientDecoder = new TextDecoder("utf-8", { ignoreBOM: true }); |
| 52 | |
| 53 | /** |
| 54 | * fx reads bytes: a BOM means no frontmatter, and invalid UTF-8 in a value |
| 55 | * makes the skill invalid while a literal U+FFFD is fine. So the BOM is kept, |
| 56 | * and a line with invalid UTF-8 ends in a NUL, which the parser rejects. |
| 57 | */ |
| 58 | function decodeSkillFile(bytes: Uint8Array): string { |
| 59 | const lines: Array<string> = []; |
| 60 | for (let start = 0; ;) { |
| 61 | const newline = bytes.indexOf(0x0a, start); |
| 62 | const line = bytes.subarray(start, newline === -1 ? bytes.length : newline); |
| 63 | try { |
| 64 | lines.push(strictDecoder.decode(line)); |
| 65 | } catch { |
| 66 | lines.push(`${lenientDecoder.decode(line)}\u0000`); |
| 67 | } |
| 68 | if (newline === -1) return lines.join("\n"); |
| 69 | start = newline + 1; |
| 70 | } |
| 71 | } |
| 72 | |
| 73 | function concatBytes(chunks: Iterable<Uint8Array>): Uint8Array { |
| 74 | const parts = [...chunks]; |
| 75 | const bytes = new Uint8Array(parts.reduce((total, part) => total + part.length, 0)); |
| 76 | let offset = 0; |
| 77 | for (const part of parts) { |
| 78 | bytes.set(part, offset); |
| 79 | offset += part.length; |
| 80 | } |
| 81 | return bytes; |
| 82 | } |
| 83 | function compareUtf8(left: string, right: string): number { |
| 84 | const a = encoder.encode(left); |
| 85 | const b = encoder.encode(right); |
| 86 | for (let index = 0; index < Math.min(a.length, b.length); index++) { |
| 87 | if (a[index] !== b[index]) return (a[index] ?? 0) - (b[index] ?? 0); |
| 88 | } |
| 89 | return a.length - b.length; |
| 90 | } |
| 91 | |
| 92 | /** fx trims only spaces and tabs. */ |
| 93 | const trimSpaceTab = (value: string) => value.replace(/^[ \t]+|[ \t]+$/g, ""); |
| 94 | |
| 95 | /** fx's `invalidTextCause`: no ASCII control bytes (invalid UTF-8 shows up as one). */ |
| 96 | const hasControlByte = (value: string) => [...value].some((char) => char < " " || char === "\x7f"); |
| 97 | |
| 98 | /** fx's `parseRecognizedValue`: one quoted or bare scalar, no YAML. */ |
| 99 | function recognizedValue(raw: string): string | undefined { |
| 100 | if (raw.startsWith("|") || raw.startsWith(">")) return undefined; |
| 101 | const quoted = /^['"]/.test(raw) || /['"]$/.test(raw); |
| 102 | if (!quoted) return raw; |
| 103 | return raw.length >= 2 && raw[0] === raw.at(-1) ? raw.slice(1, -1) : undefined; |
| 104 | } |
| 105 | |
| 106 | /** |
| 107 | * Reads SKILL.md the way fx 0.0.13 does (`parseSkillFile` in |
| 108 | * src/core/skills/skill_contract.zig): a line-based header, not YAML. No |
| 109 | * frontmatter names the skill by its folder; unreadable frontmatter (no |
| 110 | * closing `---`, missing or repeated `name`, a continued value) skips it. |
| 111 | */ |
| 112 | function parseSkillMetadata( |
| 113 | contents: string, |
| 114 | folderName: string, |
| 115 | ): { readonly name: string; readonly description?: string } | undefined { |
| 116 | const opening = /^---(\r?\n|$)/.exec(contents); |
| 117 | if (opening === null) { |
| 118 | return validSkillName(folderName) ? { name: folderName } : undefined; |
| 119 | } |
| 120 | // fx drops a line's trailing `\r` only before a newline, and bounds the |
| 121 | // file up to the line after the closing `---`. |
| 122 | const lines = contents.slice(opening[0].length).split("\n"); |
| 123 | const unterminated = (index: number) => index === lines.length - 1; |
| 124 | const closing = lines.findIndex( |
| 125 | (line, index) => (unterminated(index) ? line : line.replace(/\r$/, "")) === "---", |
| 126 | ); |
| 127 | if (closing === -1) return undefined; |
| 128 | const throughClosing = opening[0] + lines.slice(0, closing + 1).join("\n"); |
| 129 | const bodyStart = throughClosing.length + (unterminated(closing) ? 0 : 1); |
| 130 | if (encoder.encode(contents.slice(0, bodyStart)).length > MAX_FRONTMATTER_BYTES) { |
| 131 | return undefined; |
| 132 | } |
| 133 | const header = lines.slice(0, closing).map((line) => line.replace(/\r$/, "")); |
| 134 | |
| 135 | let name: string | undefined; |
| 136 | let description: string | undefined; |
| 137 | let sawName = false; |
| 138 | let sawDescription = false; |
| 139 | let previousRecognized = false; |
| 140 | for (let index = 0; index < header.length; index++) { |
| 141 | const line = header[index] ?? ""; |
| 142 | const trimmed = trimSpaceTab(line); |
| 143 | if (trimmed.length === 0 || trimmed.startsWith("#")) continue; |
| 144 | if (previousRecognized && /^[ \t]/.test(line)) return undefined; |
| 145 | previousRecognized = false; |
| 146 | const colon = trimmed.indexOf(":"); |
| 147 | if (colon === -1) continue; |
| 148 | const key = trimSpaceTab(trimmed.slice(0, colon)); |
| 149 | const raw = trimSpaceTab(trimmed.slice(colon + 1)); |
| 150 | if (key === "name") { |
| 151 | if (sawName) return undefined; |
| 152 | sawName = true; |
| 153 | name = recognizedValue(raw); |
| 154 | if (name === undefined) return undefined; |
| 155 | previousRecognized = true; |
| 156 | } else if (key === "description") { |
| 157 | if (sawDescription) return undefined; |
| 158 | sawDescription = true; |
| 159 | if (BLOCK_DESCRIPTION_STYLES.has(raw)) { |
| 160 | // A block description runs over the following space-indented lines; |
| 161 | // fx rejects a tab or a shrinking indent inside it. |
| 162 | // Blank lines stay part of the block (`undefined` below). |
| 163 | const block: Array<string | undefined> = []; |
| 164 | let baseIndent: number | undefined; |
| 165 | for (; index + 1 < header.length; index++) { |
| 166 | const next = header[index + 1] ?? ""; |
| 167 | if (trimSpaceTab(next).length === 0) { |
| 168 | block.push(undefined); |
| 169 | continue; |
| 170 | } |
| 171 | const indent = /^ */.exec(next)?.[0].length ?? 0; |
| 172 | if (next[indent] === "\t") return undefined; |
| 173 | if (indent === 0) break; |
| 174 | if (baseIndent !== undefined && indent < baseIndent) return undefined; |
| 175 | baseIndent ??= indent; |
| 176 | const content = next.slice(baseIndent); |
| 177 | if (hasControlByte(content)) return undefined; |
| 178 | block.push(content); |
| 179 | } |
| 180 | description = decodeBlockDescription(block, raw); |
| 181 | } else { |
| 182 | description = recognizedValue(raw); |
| 183 | if (description === undefined || hasControlByte(description)) return undefined; |
| 184 | previousRecognized = true; |
| 185 | } |
| 186 | } |
| 187 | } |
| 188 | if (name === undefined || !validSkillName(name)) return undefined; |
| 189 | return { name, ...(description ? { description } : {}) }; |
| 190 | } |
| 191 | |
| 192 | /** |
| 193 | * fx's `decode_block_description`: `|` keeps line breaks; `>` and `>-` join |
| 194 | * neighbouring lines with a space and turn a blank line into a break. Only |
| 195 | * `>-` drops the final newline, which the menu trims anyway. |
| 196 | */ |
| 197 | function decodeBlockDescription(lines: ReadonlyArray<string | undefined>, style: string): string { |
| 198 | const lastLine = lines.findLastIndex((line) => line !== undefined); |
| 199 | let text = ""; |
| 200 | for (let index = 0; index <= lastLine; index++) { |
| 201 | const line = lines[index]; |
| 202 | if (index > 0) { |
| 203 | text += style !== "|" && lines[index - 1] !== undefined && line !== undefined ? " " : "\n"; |
| 204 | } |
| 205 | text += line ?? ""; |
| 206 | } |
| 207 | return text.trim(); |
| 208 | } |
| 209 | |
| 210 | /** fx's `invalidSkillNameCause`. */ |
| 211 | function validSkillName(name: string): boolean { |
| 212 | return ( |
| 213 | name.length > 0 && |
| 214 | encoder.encode(name).length <= MAX_NAME_BYTES && |
| 215 | !hasControlByte(name) && |
| 216 | name !== "." && |
| 217 | name !== ".." && |
| 218 | !name.includes("/") && |
| 219 | !name.includes("\\") |
| 220 | ); |
| 221 | } |
| 222 | |
| 223 | /** |
| 224 | * fx scans the workspace roots of each directory from the workspace up to, |
| 225 | * not including, HOME, then its managed root, then the home roots. |
| 226 | */ |
| 227 | function skillRoots(path: Path.Path, cwd: string, home: string) { |
| 228 | const roots: Array<{ |
| 229 | readonly directory: string; |
| 230 | readonly scope: string; |
| 231 | readonly rank: number; |
| 232 | readonly followsLinks: boolean; |
| 233 | }> = []; |
| 234 | for (let current = cwd; current !== home;) { |
| 235 | for (const root of FX_WORKSPACE_ROOTS) { |
| 236 | roots.push({ |
| 237 | directory: path.join(current, root.relative), |
| 238 | scope: "project", |
| 239 | rank: root.rank, |
| 240 | followsLinks: root.followsLinks ?? true, |
| 241 | }); |
| 242 | } |
| 243 | const parent = path.dirname(current); |
| 244 | if (parent === current) break; |
| 245 | current = parent; |
| 246 | } |
| 247 | for (const root of FX_HOME_ROOTS) { |
| 248 | roots.push({ |
| 249 | directory: path.join(home, root.relative), |
| 250 | scope: "user", |
| 251 | rank: root.rank, |
| 252 | followsLinks: root.followsLinks ?? true, |
| 253 | }); |
| 254 | } |
| 255 | return roots; |
| 256 | } |
| 257 | |
| 258 | const skipUnreadable = <A, R>( |
| 259 | path: string, |
| 260 | effect: Effect.Effect<A, PlatformError.PlatformError, R>, |
| 261 | ): Effect.Effect<A | undefined, never, R> => |
| 262 | effect.pipe( |
| 263 | Effect.catchTags({ |
| 264 | PlatformError: (error) => |
| 265 | error.reason._tag === "NotFound" |
| 266 | ? Effect.void.pipe(Effect.as(undefined)) |
| 267 | : Effect.logWarning("fx skill scan skipped an unreadable path.", { |
| 268 | path, |
| 269 | errorTag: error.reason._tag, |
| 270 | }).pipe(Effect.as(undefined)), |
| 271 | }), |
| 272 | ); |
| 273 | |
| 274 | const discoverSkillsInRoot = Effect.fn("discoverFxSkillsInRoot")(function* (input: { |
| 275 | readonly directory: string; |
| 276 | readonly scope: string; |
| 277 | readonly followsLinks: boolean; |
| 278 | }): Effect.fn.Return< |
| 279 | ReadonlyArray<{ readonly skill: ServerProviderSkill; readonly folder: string }>, |
| 280 | never, |
| 281 | FileSystem.FileSystem | Path.Path |
| 282 | > { |
| 283 | const fileSystem = yield* FileSystem.FileSystem; |
| 284 | const path = yield* Path.Path; |
| 285 | const isLink = (target: string) => |
| 286 | Effect.option(fileSystem.readLink(target)).pipe(Effect.map(Option.isSome)); |
| 287 | // fx gives its managed root no read authority: it loads nothing through a |
| 288 | // link to the root or to a folder or SKILL.md inside it (HOME is already |
| 289 | // a real path here, so a linked root changes its real path). |
| 290 | if ( |
| 291 | !input.followsLinks && |
| 292 | (yield* fileSystem.realPath(input.directory).pipe(Effect.option)).pipe( |
| 293 | Option.exists((real) => real !== input.directory), |
| 294 | ) |
| 295 | ) { |
| 296 | return []; |
| 297 | } |
| 298 | const entries = yield* skipUnreadable(input.directory, fileSystem.readDirectory(input.directory)); |
| 299 | const skills: Array<{ readonly skill: ServerProviderSkill; readonly folder: string }> = []; |
| 300 | // fx reads a root's folders in UTF-8 byte order; readDirectory promises none. |
| 301 | for (const entry of [...(entries ?? [])].sort(compareUtf8)) { |
| 302 | if (!input.followsLinks && (yield* isLink(path.join(input.directory, entry)))) continue; |
| 303 | // A stray file (`.DS_Store`, a README) is no skill folder. |
| 304 | const entryInfo = yield* Effect.option(fileSystem.stat(path.join(input.directory, entry))); |
| 305 | if (Option.isNone(entryInfo) || entryInfo.value.type !== "Directory") continue; |
| 306 | const skillPath = path.join(input.directory, entry, "SKILL.md"); |
| 307 | if (!input.followsLinks && (yield* isLink(skillPath))) continue; |
| 308 | const skillInfo = yield* skipUnreadable(skillPath, fileSystem.stat(skillPath)); |
| 309 | if (skillInfo?.type !== "File") continue; |
| 310 | // fx reads only the metadata prefix, so a long body never hides a skill. |
| 311 | const prefix = yield* skipUnreadable( |
| 312 | skillPath, |
| 313 | fileSystem |
| 314 | .stream(skillPath, { bytesToRead: MAX_FRONTMATTER_BYTES + 1 }) |
| 315 | .pipe(Stream.runCollect, Effect.map(concatBytes)), |
| 316 | ); |
| 317 | const metadata = |
| 318 | prefix === undefined ? undefined : parseSkillMetadata(decodeSkillFile(prefix), entry); |
| 319 | if (metadata === undefined) continue; |
| 320 | const folder = yield* skipUnreadable( |
| 321 | skillPath, |
| 322 | fileSystem.realPath(path.join(input.directory, entry)), |
| 323 | ); |
| 324 | skills.push({ |
| 325 | folder: folder ?? path.join(input.directory, entry), |
| 326 | skill: { |
| 327 | name: metadata.name, |
| 328 | path: skillPath, |
| 329 | scope: input.scope, |
| 330 | enabled: true, |
| 331 | ...(metadata.description === undefined ? {} : { description: metadata.description }), |
| 332 | }, |
| 333 | }); |
| 334 | } |
| 335 | return skills; |
| 336 | }); |
| 337 | |
| 338 | /** |
| 339 | * Skills in fx's menu order. Like fx, a folder reached twice (a symlinked |
| 340 | * root) counts once. When two different skills share a name, `$name` lets |
| 341 | * the model choose from fx's catalog, which lists them in scan order; it |
| 342 | * takes the first copy, so that is the one listed here. |
| 343 | */ |
| 344 | export const discoverFxSkills = Effect.fn("discoverFxSkills")(function* (input: { |
| 345 | readonly cwd: string; |
| 346 | readonly environment: NodeJS.ProcessEnv; |
| 347 | }): Effect.fn.Return<ReadonlyArray<ServerProviderSkill>, never, FileSystem.FileSystem | Path.Path> { |
| 348 | // fx reads skills only under a set HOME, and compares HOME and the |
| 349 | // workspace by their real paths. |
| 350 | const configuredHome = input.environment.HOME?.trim(); |
| 351 | if (!configuredHome) return []; |
| 352 | const fileSystem = yield* FileSystem.FileSystem; |
| 353 | const realPath = (target: string) => |
| 354 | fileSystem.realPath(target).pipe(Effect.orElseSucceed(() => target)); |
| 355 | const home = yield* realPath(configuredHome); |
| 356 | const cwd = yield* realPath(input.cwd); |
| 357 | const path = yield* Path.Path; |
| 358 | const seenFolders = new Set<string>(); |
| 359 | // `$review` and `$Review` each load the skill whose name matches the typed |
| 360 | // case, so only an exact repeat of a name is dropped. |
| 361 | const seenNames = new Set<string>(); |
| 362 | const found: Array<{ readonly skill: ServerProviderSkill; readonly rank: number }> = []; |
| 363 | for (const root of skillRoots(path, cwd, home)) { |
| 364 | for (const { skill, folder } of yield* discoverSkillsInRoot(root)) { |
| 365 | if (seenFolders.has(folder)) continue; |
| 366 | seenFolders.add(folder); |
| 367 | if (seenNames.has(skill.name)) continue; |
| 368 | seenNames.add(skill.name); |
| 369 | found.push({ skill, rank: root.rank }); |
| 370 | } |
| 371 | } |
| 372 | return found.sort((left, right) => left.rank - right.rank).map(({ skill }) => skill); |
| 373 | }); |