{"_id":"@darklake.ai/fathom-skill","name":"@darklake.ai/fathom-skill","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@darklake.ai/fathom-skill","version":"0.1.0","description":"TypeScript SDK for writing Fathom skills — typed Ctx, fetch+secrets helpers, manifest types.","license":"MIT","author":{"name":"darklake.ai"},"homepage":"https://github.com/darklake-ai/fathom-skill-ts","repository":{"type":"git","url":"git+https://github.com/darklake-ai/fathom-skill-ts.git"},"bugs":{"url":"https://github.com/darklake-ai/fathom-skill-ts/issues"},"keywords":["fathom","darklake","agent","skill","plugin","ai","llm"],"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","lint":"tsc --noEmit","prepublishOnly":"npm run lint && npm run test && npm run build"},"publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.3.0","typescript":"^5.6.0","vitest":"^2.1.0"},"_id":"@darklake.ai/fathom-skill@0.1.0","gitHead":"473abdac5955fbce86555960c2f072ccd6d6919d","_nodeVersion":"23.7.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-pFL3Z9y8ROiaATGHzQbLOXms0nT2JJuIx+A73egw3HcLDxQv/8cckuVMup47Itw66lAphsE5CGTUO1I1Zs1wqQ==","shasum":"f78105c8410daff8247cf44ef9f2e91b5e54df43","tarball":"https://registry.npmjs.org/@darklake.ai/fathom-skill/-/fathom-skill-0.1.0.tgz","fileCount":9,"unpackedSize":22554,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDKuyyHz3WY0XUhzocfzu3TQRai8yclAxQH4GQAd8VjDgIhAOGFfub3tC695iLoW0afSyAp8l7sYQWWN9nsJEZktzsg"}]},"_npmUser":{"name":"darklake.ai.z","email":"noreply@darklake.ai"},"directories":{},"maintainers":[{"name":"darklake.ai.z","email":"noreply@darklake.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fathom-skill_0.1.0_1779669878086_0.3202759941525828"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T00:44:37.923Z","0.1.0":"2026-05-25T00:44:38.228Z","modified":"2026-05-25T00:44:38.415Z"},"maintainers":[{"name":"darklake.ai.z","email":"noreply@darklake.ai"}],"description":"TypeScript SDK for writing Fathom skills — typed Ctx, fetch+secrets helpers, manifest types.","homepage":"https://github.com/darklake-ai/fathom-skill-ts","keywords":["fathom","darklake","agent","skill","plugin","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/darklake-ai/fathom-skill-ts.git"},"author":{"name":"darklake.ai"},"bugs":{"url":"https://github.com/darklake-ai/fathom-skill-ts/issues"},"license":"MIT","readme":"# @darklake.ai/fathom-skill\n\nTypeScript SDK for writing [Fathom](https://github.com/darklake-ai/fathom)\nskills. Typed `Ctx`, fetch + secret helpers, manifest types — small\npackage, no runtime dependencies.\n\n## Install\n\n```sh\nnpm install @darklake.ai/fathom-skill\n```\n\n## What it gives you\n\nThe skill protocol is JSON-over-stdio (Fathom's runner ships your\ninput on stdin, expects `{ok, result}` on stdout). Every skill needs\nthe same `Ctx` shape for accessing secrets and the egress proxy, plus\nthe same set of credential-attach descriptors for OAuth / Bearer /\nBasic auth. This package is the typed version of all of that — no\nmore copy-pasting `type Ctx = …` at the top of every skill.\n\n## Example\n\n```ts\n// my-skill/index.ts\nimport { requireFetch, requireSecret, type Ctx } from \"@darklake.ai/fathom-skill\";\n\nexport async function search(\n  params: { query: string },\n  ctx: Ctx,\n): Promise<{ hits: string[] }> {\n  const fetch = requireFetch(ctx);\n  const res = await fetch(\n    `https://api.example.com/search?q=${encodeURIComponent(params.query)}`,\n    {\n      attach: [{ type: \"bearer\", secret: \"EXAMPLE_API_KEY\" }],\n    },\n  );\n  return JSON.parse(res.body);\n}\n```\n\nThe `attach` entry tells Fathom's egress proxy to look up\n`EXAMPLE_API_KEY` in the vault and attach it as `Authorization: Bearer\n<value>` — the raw secret never touches your code.\n\n## Credential attaches\n\n```ts\nimport type {\n  BearerAttach,\n  HeaderAttach,\n  BasicAttach,\n  GoogleOauthAttach,\n} from \"@darklake.ai/fathom-skill\";\n```\n\n| Type | What it does |\n|---|---|\n| `bearer` | `Authorization: Bearer <secret>` |\n| `header` | Arbitrary header with optional template (`Bot ${secret}` etc.) |\n| `basic` | `Authorization: Basic base64(user:pass)` |\n| `google-oauth` | Refresh-token rotation; injects fresh access token |\n\n## Manifest type\n\nIf you generate or lint your `skill.manifest.yaml` programmatically:\n\n```ts\nimport type { SkillManifest } from \"@darklake.ai/fathom-skill\";\n\nconst manifest: SkillManifest = {\n  name: \"my-skill\",\n  version: \"1.0.0\",\n  author: \"you@example.com\",\n  signature: \"ed25519:builtin\",\n  permissions: {\n    network: [\"GET https://api.example.com/*\"],\n    secrets: [\"EXAMPLE_API_KEY\"],\n  },\n  tools: [\n    {\n      name: \"search\",\n      function: \"search\",\n      description: \"Search the example API for a query.\",\n    },\n  ],\n};\n```\n\n## Reference\n\n- `Ctx` — runtime context (optional `getSecret` + `fetch`).\n- `requireFetch(ctx)` / `requireSecret(ctx, name)` — narrow `Ctx` to a non-optional shape, throws with a useful message if the runtime didn't provide it.\n- `EgressAttach` union — `BearerAttach | HeaderAttach | BasicAttach | GoogleOauthAttach`.\n- `SkillManifest`, `SkillPermissions`, `SkillTool` — mirror of `skill.manifest.yaml`.\n\n## See also\n\n- [`@darklake.ai/fathom`](https://www.npmjs.com/package/@darklake.ai/fathom) — typed client for the Fathom gateway (for code that *calls* your skills via the agent, not skills themselves).\n- [Fathom source + bundled skills](https://github.com/darklake-ai/fathom/tree/main/skills) — real skill examples you can copy.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-987a1bbd5998d8527083415f275bc605"}