fathom-skill 0.1.0

Python SDK for writing Fathom skills — typed Ctx, fetch+secrets helpers, manifest types.

fathom-skill

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

Install

pip install fathom-skill

Requires Python 3.10+ and the Fathom gateway at v0.8.0 or later (earlier gateways only run Node skills).

Quick start

# my-skill/index.py
from fathom_skill import Ctx, require_fetch, require_secret


async def search(params: dict, ctx: Ctx) -> dict:
    fetch = require_fetch(ctx)
    res = await fetch(
        f"https://api.example.com/search?q={params['query']}",
        attach=[{"type": "bearer", "secret": "EXAMPLE_API_KEY"}],
    )
    return {"body": res["body"]}

# my-skill/skill.manifest.yaml
name: my-skill
version: "1.0.0"
author: [e-mail]
signature: ed25519:builtin
language: python                  # tells Fathom to run via runner.py
permissions:
  network:
    - GET https://api.example.com/*
  secrets:
    - EXAMPLE_API_KEY
tools:
  - name: search
    function: search
    description: Search the example API for a query.

Drop this directory into your Fathom skills/ folder. The agent loads it on next start.

Sync skills

Functions don't have to be async. The runner detects sync vs async via inspect.iscoroutinefunction and dispatches accordingly:

def echo(params: dict, ctx: Ctx) -> dict:
    return params

If your skill makes HTTP calls via ctx.fetch you need async def because fetch is awaitable. Pure-compute skills can stay sync.

Credential attaches

from fathom_skill import BearerAttach, HeaderAttach, BasicAttach, GoogleOauthAttach

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 typing

from fathom_skill import SkillManifest

manifest: SkillManifest = {
    "name": "my-skill",
    "version": "1.0.0",
    "author": "[e-mail]",
    "signature": "ed25519:builtin",
    "language": "python",
    "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 protocol with optional get_secret + fetch.
• require_fetch(ctx) / require_secret(ctx, name) — narrow to non-optional, raise with a useful message if the runtime didn't provide it.
• EgressAttach union — BearerAttach | HeaderAttach | BasicAttach | GoogleOauthAttach.
• SkillManifest, SkillPermissions, SkillTool — typed mirror of skill.manifest.yaml.

See also

• fathom-sdk — Python client for the Fathom gateway (for calling the agent from your code, distinct from skills which are invoked by the agent).
• @darklake.ai/fathom-skill — the sibling SDK for TypeScript skills.

License

MIT — see LICENSE.