Provider that imports skills from GitHub repositories at runtime.

Downloads repos as tarballs, caches them to disk, and delegates to Kit.Local for parsing. Ships built-in skills (github:import, github:list, github:remove) so agents can discover and pull skills mid-conversation without restarting.

Configuration

Add Kit.GitHub alongside your other providers:

{:ok, agent} = SkillKit.start_agent("agents/neve",
  skills: [
    {SkillKit.Kit.Local, dir: "./skills"},
    {SkillKit.Kit.GitHub,
      allowed_sources: ["paper-crow/*", "community/tools"],
      api_token: {:env, "GITHUB_TOKEN"},
      cache_dir: "/tmp/skill_kit/github"
    }
  ],
  caller: self()
)

All options are optional:

Token resolution

The api_token option accepts three forms:

api_token: "ghp_abc123"                # string literal
api_token: {:env, "GITHUB_TOKEN"}      # resolved from environment at call time
api_token: nil                         # unauthenticated (public repos only, 60 req/hr)

Reference Format

Repositories are referenced as strings in the format owner/repo[/path][@ref]:

owner/repo              — default branch, root directory
owner/repo@v1.0         — tagged release
owner/repo@main         — specific branch
owner/repo@abc123       — commit SHA
owner/repo/path@main    — subdirectory within a repo

The referenced directory must follow the standard kit layout (skills/*/SKILL.md, optional AGENT.md and agents/*.md).

Built-in Skills

When Kit.GitHub is configured as a provider, three skills are automatically available to the agent:

github:import

Downloads and caches a repository, making its skills immediately available. On success returns a confirmation listing the discovered skills:

Imported paper-crow/nlp-skills@v2.0 — 3 skill(s): nlp:summarize, nlp:translate, nlp:classify

If the repo is already cached, the download is skipped:

paper-crow/nlp-skills@v2.0 already cached. Skills are available.

github:list

Lists all currently imported repositories and their skills. No arguments.

Imported repositories:
- paper-crow/nlp-skills@v2.0: nlp:summarize, nlp:translate, nlp:classify
- community/web-tools: web:scrape, web:search

github:remove

Removes a cached repository from disk.

Allowed Sources

The allowed_sources option controls which repos can be imported:

Pass a single string or a list:

allowed_sources: "paper-crow/*"
allowed_sources: ["paper-crow/*", "community/tools", "my-org/*"]

If an agent attempts to import a repo that doesn't match, the import fails with a clear error message.

Cache Behaviour

Downloaded repos are extracted to {cache_dir}/{owner}/{repo}/{ref}/ on disk. The cache persists across agent restarts.

• Cache hit: If the directory exists, the download is skipped.
• Default ref: When no @ref is specified, the cache key uses "default". Importing the same repo with an explicit ref creates a separate entry.
• Invalidation: Call github:remove then github:import again. There is no automatic TTL or expiration.
• Visibility: The Catalog's "always fresh" model means newly imported repos appear on the very next query — no restart or cache flush needed.

Security

Imported skills are subject to the same authorization as local skills. The agent's SkillKit.Scope filters what imported skills can do — if an imported skill requires a scope the agent doesn't have, it won't be visible.

The allowed_sources config is the trust boundary: it determines which repositories an agent can import from. With "*", any public repo (or private repo with a token) can be imported. Use specific patterns to restrict this.