Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* A learned skill's SKILL.md (design 2.1, spec 6), written and read.
*
* Only `name` and `description` sit at the top level; everything of Trail's
* is under `metadata` as flat quoted strings, and `metadata.trail` is the one
* mark that makes a file Trail's. Sections are always Run, Check it worked,
* If it fails, Don't use for.
*
* Every value is written on one line: text a person or an agent wrote (a
* repo name, an error line) can't open a line of its own, so it can't start
* a `[trail]` line, a heading or a step. Reading goes through phase 0's
* guarded front-matter reader (no anchors, aliases or code fences), and a
* file without `metadata.trail` is never read for steps: Trail never reads
* or edits another skill's steps.
*/
import { createHash } from 'node:crypto';
import type { GatedKind, JobClass } from '../trace/types.js';
import type { CompiledSkill, ParsedSkill, Scope, SkillMeta, SkillStep } from './types.js';
import { flatLine } from '../notes/flatten.js';
import { matter } from '../util/front-matter.js';
import { gatedKind } from './risk.js';
import { metaToParams } from './params.js';
export const GATED_PREFIX = "Can't be undone (Claude Code asks the person first): ";
export const WAIT_NOTE = '(a wait: run it in the background if it may take over 2 minutes)';
export const BG_NOTE = '(in the background)';
export const NO_CHECK = 'No check ran in the run this came from.';
export const NOTHING_FAILED = 'Nothing failed in the run this came from.';
/** D59b: a check read with a deploy status tool (`check-tool`), not run as a command. */
export const TOOL_CHECK = 'Check the deployment the same way the run did: ';
const META_ORDER: ReadonlyArray<keyof SkillMeta> = [
'trail', 'scope', 'applies', 'job', 'asks', 'status-asks', 'params', 'needs', 'ready', 'check-first', 'before-you-start', 'confirm-before', 'check', 'check-shows', 'check-tool', 'version',
];
/** Values that are commands or command lists: kept as typed, only made one line. */
const COMMAND_KEYS = new Set<string>(['params', 'needs', 'ready', 'check-first', 'confirm-before', 'check']);
const BREAKS = /\r\n|[\n\r\u000b\u000c\u0085\u2028\u2029]/g;
const HIDDEN = /[\p{Cf}\ufe00-\ufe0f\u{e0100}-\u{e01ef}\u0000-\u0008\u000e-\u001f\u007f-\u0084\u0086-\u009f]/gu;
const MARKER = /^\s*(?:\[(?:trail|graft|trail-code)\]\s*)+/i;
/** A command on one line: breaks become spaces, hidden characters go; spaces inside it are kept. */
export function oneLine(text: string): string {
return String(text ?? '').replace(HIDDEN, '').replace(BREAKS, ' ').replace(/\t/g, ' ').replace(MARKER, '').trim();
}
/** Prose on one line; three dashes in a row would end the front matter for some readers. */
const prose = (text: unknown, max = 1024) => flatLine(text, max).replace(/-{3,}/g, '--');
/**
* A command as a double-quoted YAML string. Three dashes in a row end the front matter for some readers,
* so a dash inside such a run is written `\u002d`, which YAML reads back as `-`: the command stays as typed.
*/
const quoted = (cmd: string) => JSON.stringify(cmd).replace(/-{3,}/g, (m) => `-${'\\u002d'.repeat(m.length - 2)}-`);
/** The step in a code span whose fence is longer than any backtick run inside it. */
function codeSpan(cmd: string): string {
const longest = Math.max(0, ...[...cmd.matchAll(/`+/g)].map((m) => m[0].length));
if (!longest) return `\`${cmd}\``;
const fence = '`'.repeat(longest + 1);
return `${fence} ${cmd} ${fence}`;
}
export function renderSkillMd(c: CompiledSkill): string {
const meta = c.meta as unknown as Record<string, string | undefined>;
const keys = [...META_ORDER, ...Object.keys(meta).filter((k) => !(META_ORDER as readonly string[]).includes(k))];
const front = ['---', `name: ${c.name}`, `description: ${JSON.stringify(prose(c.description))}`, 'metadata:'];
for (const k of keys) {
const v = meta[k];
if (v === undefined || v === null || String(v) === '') continue;
front.push(` ${k}: ${COMMAND_KEYS.has(k) ? quoted(oneLine(String(v))) : JSON.stringify(prose(v))}`);
}
front.push('---');
const run = c.steps.map((s) => {
const note = s.wait ? ` ${WAIT_NOTE}` : s.bg ? ` ${BG_NOTE}` : '';
return `${s.n}. ${s.gated ? GATED_PREFIX : ''}${codeSpan(oneLine(s.cmd))}${note}`;
});
let check: string;
const shows = c.checkShows ? prose(c.checkShows, 200) : '';
const phrase = /\s/.test(shows);
if (!c.check) check = NO_CHECK;
else if (c.meta['check-tool']) check = `${TOOL_CHECK}${prose(c.check, 300)}${shows ? `; it shows ${shows}` : ''}.`;
else if (c.checkIsStep) {
const n = [...c.steps].reverse().find((s) => s.cmd === c.check)?.n;
const lead = n ? `Step ${n}, ${codeSpan(oneLine(c.check))}, is the check` : `${codeSpan(oneLine(c.check))} is the check`;
check = shows ? `${lead}: ${shows}.` : `${lead}.`;
} else if (!shows) check = `${codeSpan(oneLine(c.check))} works.`;
else check = `${codeSpan(oneLine(c.check))} shows ${phrase ? shows : codeSpan(shows)}.`;
const fails = c.ifFails.map((l) => prose(l, 200)).filter(Boolean);
const before = beforeYouStart(c.meta);
return [
...front,
`# ${prose(c.title, 160)}`,
'',
...(before.length ? ['## Before you start', ...before.map((l) => `- ${l}`), ''] : []),
'## Run',
...run,
'',
'## Check it worked',
check,
'',
'## If it fails',
...(fails.length ? fails.map((l) => `- ${l}`) : [NOTHING_FAILED]),
'',
"## Don't use for",
prose(c.dontUse, 300),
'',
].join('\n');
}
/** D116 item 5: the lines of `metadata.before-you-start`, each one flat line. */
export function beforeYouStart(meta: Pick<SkillMeta, 'before-you-start'>): string[] {
return String(meta['before-you-start'] ?? '').split(' | ').map((l) => prose(l, 200)).filter(Boolean).slice(0, 3);
}
export function skillHash(text: string): string {
return `sha256:${createHash('sha256').update(String(text ?? '')).digest('hex')}`;
}
/** The command in a Run line's first code span, and what follows it (CommonMark code spans). */
function readSpan(rest: string): { cmd: string; after: string } | null {
const open = /`+/.exec(rest);
if (!open) return null;
const len = open[0].length;
const from = open.index + len;
const close = new RegExp(`(?<!\`)\`{${len}}(?!\`)`, 'g');
close.lastIndex = from;
const m = close.exec(rest);
if (!m) return null;
let cmd = rest.slice(from, m.index);
if (cmd.length > 1 && cmd.startsWith(' ') && cmd.endsWith(' ') && cmd.trim()) cmd = cmd.slice(1, -1);
return { cmd, after: rest.slice(m.index + len) };
}
const isMap = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date);
const SCOPES = new Set<Scope>(['personal', 'repo', 'team']);
const JOBS = new Set<JobClass>(['release', 'ship', 'pr-green', 'sweep', 'run-local', 'report', 'tests']);
const section = (heading: string) => heading.toLowerCase().replace(/[\u2019']/g, "'").replace(/\s+/g, ' ').trim();
/** Through phase 0's matter(): null on `refused` (anchors, aliases, non-scalars) or when there is no `metadata.trail` key. */
export function parseSkillMd(text: string, folderName: string): ParsedSkill | null {
const src = String(text ?? '');
let fm;
try {
fm = matter(src, { scalars: ['name', 'description'] });
} catch {
return null;
}
if (fm.refused) return null;
const data = fm.data as Record<string, unknown>;
const raw = data.metadata;
if (!isMap(raw)) return null;
const strings: Record<string, string> = {};
for (const [k, v] of Object.entries(raw)) {
if (v === null || v === undefined) continue;
if (typeof v === 'object' && !(v instanceof Date)) return null;
strings[k] = v instanceof Date ? v.toISOString().slice(0, 10) : String(v);
}
if (!strings.trail?.trim()) return null;
const meta: Record<string, string> = {};
for (const k of [...META_ORDER, ...Object.keys(strings)]) if (strings[k] !== undefined && meta[k] === undefined) meta[k] = strings[k]!;
if (!SCOPES.has(meta.scope as Scope)) meta.scope = 'personal';
if (meta.job !== undefined && !JOBS.has(meta.job as JobClass)) delete meta.job;
meta.asks ??= '';
meta.version ??= '1';
const confirm = new Set((meta['confirm-before'] ?? '').split(' ; ').map((s) => s.trim()).filter(Boolean));
const steps: SkillStep[] = [];
const ifFails: string[] = [];
const dontUse: string[] = [];
let where = '';
for (const line of String(fm.content ?? '').split(/\r?\n/)) {
const h = /^##\s+(.+?)\s*#*\s*$/.exec(line);
if (h) { where = section(h[1]!); continue; }
if (where === 'run') {
const m = /^\s*\d+\.\s+(.*)$/.exec(line);
if (!m) continue;
let rest = m[1]!;
const prefixed = /^can[\u2019']t be undone\b[^`]*?:\s*/i.exec(rest);
if (prefixed) rest = rest.slice(prefixed[0].length);
const span = readSpan(rest);
if (!span || !span.cmd.trim()) continue;
const cmd = span.cmd;
const kind: GatedKind | null = gatedKind(cmd);
const gated = kind ?? (prefixed || confirm.has(cmd) ? 'deploy' : null);
steps.push({ n: steps.length + 1, cmd, gated, bg: /\(in the background\)/i.test(span.after), wait: /\(a wait\b/i.test(span.after) });
} else if (where === 'if it fails') {
const m = /^\s*[-*]\s+(.+)$/.exec(line);
if (m) ifFails.push(m[1]!.trim());
} else if (where === "don't use for" && line.trim()) dontUse.push(line.trim());
}
return {
name: typeof data.name === 'string' && data.name.trim() ? data.name : folderName,
description: typeof data.description === 'string' ? data.description : '',
meta: meta as unknown as SkillMeta,
steps,
check: meta.check?.trim() ? meta.check : null,
checkShows: meta['check-shows']?.trim() ? meta['check-shows'] : null,
ifFails,
dontUse: dontUse.join(' '),
params: metaToParams(meta.params),
hash: skillHash(src),
};
}