@darklake.ai/fathom-skill

TypeScript SDK for writing Fathom skills. Typed Ctx, fetch + secret helpers, manifest types — small package, no runtime dependencies.

Install

npm install @darklake.ai/fathom-skill

What it gives you

The skill protocol is JSON-over-stdio (Fathom's runner ships your input on stdin, expects {ok, result} on stdout). Every skill needs the same Ctx shape for accessing secrets and the egress proxy, plus the same set of credential-attach descriptors for OAuth / Bearer / Basic auth. This package is the typed version of all of that — no more copy-pasting type Ctx = … at the top of every skill.

Example

// my-skill/index.ts
import { requireFetch, requireSecret, type Ctx } from "@darklake.ai/fathom-skill";

export async function search(
  params: { query: string },
  ctx: Ctx,
): Promise<{ hits: string[] }> {
  const fetch = requireFetch(ctx);
  const res = await fetch(
    `https://api.example.com/search?q=${encodeURIComponent(params.query)}`,
    {
      attach: [{ type: "bearer", secret: "EXAMPLE_API_KEY" }],
    },
  );
  return JSON.parse(res.body);
}

The attach entry tells Fathom's egress proxy to look up EXAMPLE_API_KEY in the vault and attach it as Authorization: Bearer <value> — the raw secret never touches your code.

Credential attaches

import type {
  BearerAttach,
  HeaderAttach,
  BasicAttach,
  GoogleOauthAttach,
} from "@darklake.ai/fathom-skill";

| Type | What it does | |---|---| | bearer | Authorization: Bearer <secret> | | header | Arbitrary header with optional template (Bot ${secret} etc.) | | basic | Authorization: Basic base64(user:pass) | | google-oauth | Refresh-token rotation; injects fresh access token |

Manifest type

If you generate or lint your skill.manifest.yaml programmatically:

import type { SkillManifest } from "@darklake.ai/fathom-skill";

const manifest: SkillManifest = {
  name: "my-skill",
  version: "1.0.0",
  author: "[email protected]",
  signature: "ed25519:builtin",
  permissions: {
    network: ["GET https://api.example.com/*"],
    secrets: ["EXAMPLE_API_KEY"],
  },
  tools: [
    {
      name: "search",
      function: "search",
      description: "Search the example API for a query.",
    },
  ],
};

Reference

• Ctx — runtime context (optional getSecret + fetch).
• requireFetch(ctx) / requireSecret(ctx, name) — narrow Ctx to a non-optional shape, throws with a useful message if the runtime didn't provide it.
• EgressAttach union — BearerAttach | HeaderAttach | BasicAttach | GoogleOauthAttach.
• SkillManifest, SkillPermissions, SkillTool — mirror of skill.manifest.yaml.

See also

• @darklake.ai/fathom — typed client for the Fathom gateway (for code that calls your skills via the agent, not skills themselves).
• Fathom source + bundled skills — real skill examples you can copy.

License

MIT — see LICENSE.