Skills 渐进式加载

Agent starts  └─ SkillCatalog: name + description only       └─ model selects load_skill("repository-audit")            └─ full SKILL.md enters active context                 └─ model requests load_skill_resource("references/checklist.md")                      └─ one referenced file enters active context

pnpm add yaml

skills/└── repository-audit/    ├── SKILL.md    ├── references/    │   └── checklist.md    ├── scripts/    │   └── collect-status.ts    └── assets/        └── report-template.md

---name: repository-auditdescription: Audit a repository when the user asks for structure, risks, or readiness.---# Repository audit1. Read `references/checklist.md` before inspecting the repository.2. Collect evidence with read-only tools.3. Report findings by severity and cite file paths.

export interface SkillSummary {  name: string;  description: string;  root: string;  entryPath: string;}export interface ActiveSkill {  name: string;  instructions: string;  loadedResources: Record<string, string>;}export interface SkillState {  catalog: SkillSummary[];  activeSkills: Record<string, ActiveSkill>;}export interface AgentState {  skills: SkillState;}export interface ContextKindMap {  skill_catalog: true;  skill_instructions: true;  skill_resource: true;}export interface ToolContext {  skills: SkillState;  maxSkillBytes: number;  emit(event: { type: string; [key: string]: unknown }): void;}

import { open, readdir, realpath } from "node:fs/promises";import { join, relative, sep } from "node:path";import { parse } from "yaml";import { z } from "zod";const metadataSchema = z.object({  name: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),  description: z.string().min(12).max(500),});async function readFrontmatter(entryPath: string): Promise<string> {  const handle = await open(entryPath, "r");  try {    const buffer = Buffer.alloc(16_384);    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);    const prefix = buffer.toString("utf8", 0, bytesRead);    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(prefix);    if (!match?.[1]) throw new Error(`invalid skill frontmatter: ${entryPath}`);    return match[1];  } finally {    await handle.close();  }}function assertInside(root: string, target: string): void {  const path = relative(root, target);  if (path === ".." || path.startsWith(`..${sep}`)) {    throw new Error("skill path escapes its catalog root");  }}export async function discoverSkills(skillsDirectory: string): Promise<SkillSummary[]> {  const catalogRoot = await realpath(skillsDirectory);  const entries = await readdir(catalogRoot, { withFileTypes: true });  const catalog: SkillSummary[] = [];  for (const entry of entries) {    if (!entry.isDirectory()) continue;    const root = await realpath(join(catalogRoot, entry.name));    assertInside(catalogRoot, root);    const entryPath = await realpath(join(root, "SKILL.md"));    assertInside(root, entryPath);    const metadata = metadataSchema.parse(parse(await readFrontmatter(entryPath)));    if (metadata.name !== entry.name) throw new Error("skill folder and name must match");    catalog.push({ ...metadata, root, entryPath });  }  return catalog.sort((left, right) => left.name.localeCompare(right.name));}

export function skillCatalogAsContextSource(catalog: SkillSummary[]): ContextSource {  const content = catalog    .map(({ name, description }) => `<skill name="${escapeXml(name)}">${escapeXml(description)}</skill>`)    .join("\n");  return {    id: "available-skills",    kind: "skill_catalog",    label: "Available skills",    content,    priority: 90,  };}

export async function activateSkill(  name: string,  state: SkillState,  maxSkillBytes: number,): Promise<ActiveSkill> {  const cached = state.activeSkills[name];  if (cached) return cached;  const summary = state.catalog.find((skill) => skill.name === name);  if (!summary) throw new Error(`unknown skill: ${name}`);  const source = await readFile(summary.entryPath, "utf8");  if (Buffer.byteLength(source) > maxSkillBytes) throw new Error("skill_too_large");  const { metadata, body } = parseSkillDocument(source);  if (metadata.name !== summary.name) throw new Error("skill metadata changed after discovery");  const active = { name, instructions: body.trim(), loadedResources: {} };  state.activeSkills[name] = active;  return active;}export const loadSkillTool = defineTool({  name: "load_skill",  description: "Load the complete instructions for one available skill before using it.",  schema: z.object({ name: z.string() }),  effect: "read",  execute: async ({ name }, context) => {    const skill = await activateSkill(name, context.skills, context.maxSkillBytes);    context.emit({ type: "skill_loaded", name });    return { name, instructions: skill.instructions };  },});

const allowedResourceRoots = new Set(["references", "assets"]);export async function loadSkillResource(input: {  skillName: string;  resourcePath: string;  state: SkillState;  maxResourceBytes: number;}): Promise<{ path: string; content: string }> {  const active = input.state.activeSkills[input.skillName];  if (!active) throw new Error("skill_not_active");  const summary = input.state.catalog.find((skill) => skill.name === input.skillName);  if (!summary) throw new Error("unknown_skill");  const firstSegment = input.resourcePath.split(/[\\/]/)[0];  if (!firstSegment || !allowedResourceRoots.has(firstSegment)) {    throw new Error("resource_type_not_loadable");  }  const target = await realpath(join(summary.root, input.resourcePath));  assertInside(summary.root, target);  if (!/\.(md|txt|json|ya?ml)$/i.test(target)) throw new Error("binary_resource_denied");  const info = await stat(target);  if (info.size > input.maxResourceBytes) throw new Error("skill_resource_too_large");  const content = await readFile(target, "utf8");  active.loadedResources[input.resourcePath] = content;  return { path: input.resourcePath, content };}export const loadSkillResourceTool = defineTool({  name: "load_skill_resource",  description: "Load one text reference or asset from an already active skill.",  schema: z.object({    skillName: z.string(),    resourcePath: z.string().min(1),  }),  effect: "read",  execute: async (input, context) => {    const resource = await loadSkillResource({ ...input, state: context.skills, maxResourceBytes: 32_000 });    context.emit({ type: "skill_resource_loaded", ...input });    return resource;  },});

START  DISCOVER metadata once → state.skills.catalogEACH LOOP  ASSEMBLE goal + plan + available skill summaries           + full instructions of activeSkills           + explicitly loaded resources  DECIDE    text                     → normal completion gate    load_skill               → activate one SKILL.md    load_skill_resource      → expand one referenced file    ordinary tool call       → execute under the active Skill instructions  OBSERVE    persist skill_loaded / skill_resource_loaded events    rebuild context for the next turn

const skillSources: ContextSource[] = [  skillCatalogAsContextSource(state.skills.catalog),  ...Object.values(state.skills.activeSkills).map((skill) => ({    id: `skill:${skill.name}`,    kind: "skill_instructions" as const,    label: skill.name,    content: skill.instructions,    priority: 96,  })),  ...Object.values(state.skills.activeSkills).flatMap((skill) =>    Object.entries(skill.loadedResources).map(([path, content]) => ({      id: `skill-resource:${skill.name}:${path}`,      kind: "skill_resource" as const,      label: `${skill.name}/${path}`,      content,      priority: 94,    })),  ),];const request = buildModelRequest({  task: state.task,  cwd: state.cwd,  toolNames: options.tools.names(),  sources: [...state.contextSources, ...skillSources],});

it("does not expose skill instructions before activation", async () => {  const catalog = await discoverSkills(fixtureSkillsRoot);  const source = skillCatalogAsContextSource(catalog);  expect(source.content).toContain("repository-audit");  expect(source.content).toContain("Audit a repository");  expect(source.content).not.toContain("Read `references/checklist.md`");});it("loads only the selected skill and requested resource", async () => {  const state = await createSkillFixtureState();  const active = await activateSkill("repository-audit", state, 64_000);  expect(active.instructions).toContain("references/checklist.md");  expect(state.activeSkills["release-notes"]).toBeUndefined();  const resource = await loadSkillResource({    skillName: "repository-audit",    resourcePath: "references/checklist.md",    state,    maxResourceBytes: 32_000,  });  expect(resource.content).toContain("Repository structure");});