"note": "Heuristic false-green LEADS, not findings. A finding requires a demonstrated reproduction (surviving mutation via mutation-runner). Do not treat a candidate as a confirmed false green. Coverage-theater leads may include tests that delegate their assertion to a custom helper the classifier does not recognise; verify before acting.",

  "sourceDigest": "sha256:dd810dd48c5bdbc9becd7fcc01dd41a4ca2abf0b2d6f6a545907247f6e3e8361",

  "summary": {

    "filesScanned": 2430,

    "filesScanned": 2431,

    "candidateCount": 16,

    "byMode": {

      "false_green_coverage_theater": 15,

{

  "schemaVersion": "1",

  "repository": "OpenAgentsInc/openagents",

  "sourceDigest": "sha256:30573ab546f371af545bfe2cfedba47c5ec547e2acc61c8d9ce115761d3f7d4a",

  "sourceDigest": "sha256:78a1326f50e5901e25bd56e2bed33f1635fcb75d3dbb89b8bfd8ef4558d00fd3",

  "surfaces": [

    {

      "id": "app:@openagentsinc/acceptance-runner",

      "oracles": [

        {

          "type": "test",

          "ref": "packages/openagents-cli (30 tracked test files)"

          "ref": "packages/openagents-cli (31 tracked test files)"

        },

        {

          "type": "behavior-contract",

import { backendIds } from "./coder-backends.js";

import { OllamaReplySource, isOllamaModelFlag, parseOllamaModelFlag } from "./coder-ollama.js";

import { openThread, ThreadUnavailable, type ThreadReplySource } from "./coder-thread.js";

import { delegateTool } from "./coder-tools.js";

import { delegateTool, skillTool } from "./coder-tools.js";

import { discoverSkills } from "./coder-skills.js";

import { describeWorkspace } from "./coder-workspace.js";

import { ComputerClient } from "./computer-client.js";

import { ComputerUp } from "./computer-up.js";

      // remember a slash command. A turn that needs three agents asks for them

      // mid-sentence, and `/delegate` stays as the way to launch a fan-out

      // without spending a turn to ask for one.

      if (setup !== undefined) {

        source.useTools?.([delegateTool(setup.delegation)]);

      // Skills do not depend on delegation: a session with no credential still

      // reads this repository's conventions, it just cannot hand work to a

      // child. A session with neither declares no tools at all.

      const skills = discoverSkills();

      const tools = [

        ...(skills.length === 0 ? [] : [skillTool(skills)]),

        ...(setup === undefined ? [] : [delegateTool(setup.delegation)]),

      ];

      if (tools.length > 0) {

        source.useTools?.(tools);

      }

      // Delegation is off rather than quietly running children on the

/**

 * The skills a session can read.

 *

 * A skill is a directory holding a `SKILL.md`: YAML front matter naming it and

 * saying when it applies, then a body of instructions. The format is shared

 * with the other agents that read this repository, so the same file serves all

 * of them and none of them owns it.

 *

 * Skills are offered by name and description, not by body. Eight skills across

 * this machine and this repository are some 46 KB, more than a local model's

 * context should spend on instructions it will not use, and the total grows

 * with every skill anyone adds. So the catalog is small and constant, and a

 * body is read only when the model asks for one -- which is what the front

 * matter's `description` is for: it is the sentence the model chooses on.

 *

 * The catalog rides in the `skill` tool's description rather than in a system

 * prompt. The local lane composes its own prompt; the thread lane's is the

 * server's. A tool description reaches both.

 */

import { readdirSync, readFileSync, statSync } from "node:fs";

import { homedir } from "node:os";

import { join } from "node:path";

/** Where skills live, nearest first. A repository skill wins its name. */

const SKILL_DIRECTORIES = (cwd: string, home: string): ReadonlyArray<string> => [

  join(cwd, ".agents", "skills"),

  join(home, ".agents", "skills"),

];

/** How much of one skill body is handed back. */

const BODY_LIMIT = 32_000;

export interface CoderSkill {

  /** The name the model asks for, from the front matter. */

  readonly name: string;

  /** When to use it, from the front matter. One sentence, shown in the catalog. */

  readonly description: string;

  /** The instructions, front matter removed. */

  readonly body: string;

  /** Where it was read from, so a reader can open it. */

  readonly path: string;

}

/**

 * Read `name` and `description` out of YAML front matter.

 *

 * Deliberately not a YAML parser. These are two bounded scalar fields at the

 * top of a known file, and a dependency that can parse anchors and merge keys

 * is a dependency that can also do something surprising with a file anyone may

 * drop in a skills directory.

 */

const frontMatter = (source: string): { name?: string; description?: string } => {

  if (!source.startsWith("---")) return {};

  const end = source.indexOf("\n---", 3);

  if (end < 0) return {};

  const fields: { name?: string; description?: string } = {};

  const lines = source.slice(3, end).split("\n");

  for (const [at, line] of lines.entries()) {

    const match = /^(name|description):\s*(.*)$/.exec(line);

    if (match === null) continue;

    const key = match[1] as "name" | "description";

    const inline = match[2]!.trim();

    // `>` and `|` say the value is the indented block beneath, which is how a

    // description longer than a line is written. Taking the marker as the value

    // is how `stripe-directory` came to describe itself as ">-".

    if (inline === "" || /^[>|][-+]?$/.test(inline)) {

      const block: string[] = [];

      for (const next of lines.slice(at + 1)) {

        if (!/^\s/.test(next) || next.trim() === "") break;

        block.push(next.trim());

      }

      // A folded block is one paragraph; a literal one keeps its line breaks.

      if (block.length > 0) fields[key] = block.join(inline.startsWith("|") ? "\n" : " ");

      continue;

    }

    // A quoted scalar is the same string without its quotes.

    fields[key] = inline.replace(/^["'](.*)["']$/, "$1");

  }

  return fields;

};

/** The body after the front matter, or the whole file when there is none. */

const withoutFrontMatter = (source: string): string => {

  if (!source.startsWith("---")) return source.trim();

  const end = source.indexOf("\n---", 3);

  if (end < 0) return source.trim();

  return source.slice(source.indexOf("\n", end + 1) + 1).trim();

};

/**

 * Every skill readable from this directory, nearest source winning its name.

 *

 * A directory that is missing, unreadable, or holds no `SKILL.md` contributes

 * nothing. A skills directory is optional, and a session whose repository has

 * none is a session with no skills, not a session that failed to start.

 */

export function discoverSkills(

  cwd: string = process.cwd(),

  // Taken rather than read so a test can point at a directory it made. A

  // function that always reads the real home directory can only be tested on a

  // machine that happens to have the right skills in it.

  home: string = homedir(),

): ReadonlyArray<CoderSkill> {

  const found = new Map<string, CoderSkill>();

  for (const directory of SKILL_DIRECTORIES(cwd, home)) {

    let entries: ReadonlyArray<string>;

    try {

      entries = readdirSync(directory);

    } catch {

      continue;

    }

    for (const entry of entries) {

      const path = join(directory, entry, "SKILL.md");

      let source: string;

      try {

        if (!statSync(path).isFile()) continue;

        source = readFileSync(path, "utf8");

      } catch {

        continue;

      }

      const { name, description } = frontMatter(source);

      // A skill with no name cannot be asked for, and one with no description

      // gives the model nothing to choose on. Both are required.

      if (name === undefined || description === undefined) continue;

      if (found.has(name)) continue;

      found.set(name, { name, description, body: withoutFrontMatter(source), path });

    }

  }

  // Sorting a fresh array built from the map, so nothing shared is mutated.

  // eslint-disable-next-line unicorn/no-array-sort -- the spread is the copy

  return [...found.values()].sort((left, right) => left.name.localeCompare(right.name));

}

/** The catalog line for one skill, as the model reads it. */

export const catalogEntry = (skill: CoderSkill): string =>

  `- \`${skill.name}\`: ${skill.description}`;

/** What a skill hands back when it is read. */

export const renderSkill = (skill: CoderSkill): string => {

  const body =

    skill.body.length > BODY_LIMIT

      ? `${skill.body.slice(0, BODY_LIMIT)}\n\n[truncated; the rest is in ${skill.path}]`

      : skill.body;

  return `Skill \`${skill.name}\` (${skill.path}):\n\n${body}`;

};

 */

import type { CoderDelegation } from "./coder-session.js";

import { catalogEntry, renderSkill, type CoderSkill } from "./coder-skills.js";

import { describePrompt, MAX_DELEGATE_COUNT } from "./coder-delegate.js";

import type { DelegationOutcome } from "./coder-delegate.js";

function clip(text: string, limit: number): string {

  return text.length <= limit ? text : `${text.slice(0, limit)}\n…[truncated]`;

}

/**

 * The skill tool: read one of this session's skills.

 *

 * The catalog is the description rather than a system prompt, so the same tool

 * carries it on the local lane, where the client writes the prompt, and on the

 * thread lane, where the server does. Bodies are not sent until asked for: the

 * catalog is a line each, and the skills on one machine already run to tens of

 * kilobytes.

 *

 * Returned as text rather than thrown for a name that does not match, and the

 * text lists what does: a model that misremembers a name can correct itself on

 * the next call, and cannot correct a turn that died.

 */

export function skillTool(skills: ReadonlyArray<CoderSkill>): CoderTool {

  const catalog = skills.map((skill) => catalogEntry(skill)).join("\n");

  return {

    name: "skill",

    description:

      "Read one of this repository's skills: a written procedure for a kind of work, with the " +

      "conventions, commands, and rules it needs. Call it before doing work a skill covers, and " +

      "follow what it says over your own habits. Skills available:\n" +

      catalog,

    parameters: {

      type: "object",

      properties: {

        name: {

          type: "string",

          enum: skills.map((skill) => skill.name),

          description: "The skill to read.",

        },

      },

      required: ["name"],

      additionalProperties: false,

    },

    run: (args) => {

      const name = typeof args["name"] === "string" ? args["name"].trim() : "";

      const skill = skills.find((candidate) => candidate.name === name);

      if (skill === undefined) {

        return Promise.resolve(

          `There is no \`${name}\` skill. This session has: ${skills

            .map((candidate) => `\`${candidate.name}\``)

            .join(", ")}.`,

        );

      }

      return Promise.resolve(renderSkill(skill));

    },

  };

}

import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";

import { tmpdir } from "node:os";

import { join } from "node:path";

import { describe, expect, it } from "vitest";

import { discoverSkills } from "../src/coder-skills.js";

import { skillTool } from "../src/coder-tools.js";

/** A repository with the given skills under `.agents/skills`. */

const workspace = (skills: Record<string, string>): string => {

  const root = mkdtempSync(join(tmpdir(), "coder-skills-"));

  for (const [name, source] of Object.entries(skills)) {

    const directory = join(root, ".agents", "skills", name);

    mkdirSync(directory, { recursive: true });

    writeFileSync(join(directory, "SKILL.md"), source);

  }

  return root;

};

/** A home directory with no skills in it, so a test reads only its workspace. */

const EMPTY_HOME = mkdtempSync(join(tmpdir(), "coder-skills-home-"));

const SKILL = `---

name: house-style

description: How this repository writes prose.

---

# House style

Use sentence case.

`;

describe("discovering skills", () => {

  it("reads the name, the description, and the body without its front matter", () => {

    const [skill] = discoverSkills(workspace({ "house-style": SKILL }), EMPTY_HOME);

    expect(skill).toMatchObject({

      name: "house-style",

      description: "How this repository writes prose.",

    });

    expect(skill?.body).toBe("# House style\n\nUse sentence case.");

    // The body is what the front matter is not, so neither leaks into the other.

    expect(skill?.body).not.toContain("description:");

  });

  it("takes the name from the front matter, not from the directory", () => {

    const [skill] = discoverSkills(workspace({ "some-folder": SKILL }), EMPTY_HOME);

    expect(skill?.name).toBe("house-style");

  });

  it("skips a directory with no SKILL.md rather than failing", () => {

    const root = workspace({ "house-style": SKILL });

    mkdirSync(join(root, ".agents", "skills", "empty"), { recursive: true });

    expect(discoverSkills(root, EMPTY_HOME).map((skill) => skill.name)).toEqual(["house-style"]);

  });

  it("skips a skill missing a name or a description", () => {

    const root = workspace({

      nameless: "---\ndescription: No name.\n---\n\nBody.",

      quiet: "---\nname: quiet\n---\n\nBody.",

      "house-style": SKILL,

    });

    // One cannot be asked for and the other gives nothing to choose on.

    expect(discoverSkills(root, EMPTY_HOME).map((skill) => skill.name)).toEqual(["house-style"]);

  });

  it("reads a description written as a folded block, not the block marker", () => {

    const root = workspace({

      folded: [

        "---",

        "name: folded",

        "description: >-",

        "  Use when the reader wants one sentence",

        "  spread over two lines.",

        "---",

        "",

        "Body.",

      ].join("\n"),

    });

    // Taking `>-` as the value is how a skill came to describe itself as ">-".

    expect(discoverSkills(root, EMPTY_HOME)[0]?.description).toBe(

      "Use when the reader wants one sentence spread over two lines.",

    );

  });

  it("keeps the line breaks of a literal block", () => {

    const root = workspace({

      literal: ["---", "name: literal", "description: |", "  One.", "  Two.", "---", "", "Body."].join(

        "\n",

      ),

    });

    expect(discoverSkills(root, EMPTY_HOME)[0]?.description).toBe("One.\nTwo.");

  });

  it("is empty for a repository with no skills directory", () => {

    expect(discoverSkills(mkdtempSync(join(tmpdir(), "coder-skills-")), EMPTY_HOME)).toEqual([]);

  });

  it("strips the quotes from a quoted description", () => {

    const root = workspace({

      quoted: '---\nname: quoted\ndescription: "Quoted, with a comma."\n---\n\nBody.',

    });

    expect(discoverSkills(root, EMPTY_HOME)[0]?.description).toBe("Quoted, with a comma.");

  });

});

describe("the skill tool", () => {

  const skills = discoverSkills(workspace({ "house-style": SKILL }), EMPTY_HOME);

  const tool = skillTool(skills);

  it("carries the catalog in its description, so both lanes read it", () => {

    // The local lane writes its own prompt and the thread lane's is the

    // server's. A tool description is the one place that reaches both.

    expect(tool.description).toContain("`house-style`: How this repository writes prose.");

    // The body is not in the catalog. That is the point of the catalog.

    expect(tool.description).not.toContain("Use sentence case.");

  });

  it("offers only the names it found, so a model cannot ask for another", () => {

    expect((tool.parameters["properties"] as Record<string, { enum: string[] }>)["name"]?.enum).toEqual([

      "house-style",

    ]);

  });

  it("hands back the body when asked", async () => {

    const output = await tool.run({ name: "house-style" }, new AbortController().signal);

    expect(output).toContain("Use sentence case.");

    expect(output).toContain("house-style");

  });

  it("answers an unknown name with what it does have, rather than throwing", async () => {

    const output = await tool.run({ name: "nope" }, new AbortController().signal);

    // A model that misremembers can correct itself; it cannot correct a turn

    // that died.

    expect(output).toContain("There is no `nope` skill");

    expect(output).toContain("`house-style`");

  });

});