> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Git-Installable Skills

> Load and pin skills directly from Git repositories

# Git-Installable Skills

## What's a "skill"?

An Agentium **skill** is a bundle of:

* A `SKILL.md` with description + usage instructions
* Optional executable scripts (`scripts/foo.ts`)
* Optional supporting files (templates, references, prompts)

The agent loads the skill at boot, sees the `SKILL.md` in its system prompt, and can invoke the scripts as tools. See [Skills overview](/skills/overview).

`GitSkillLoader` lets you distribute skills via Git rather than copying directories around or publishing npm packages.

## Quick start

```typescript theme={null}
import { GitSkillLoader } from "@agentium/core";

const loader = new GitSkillLoader({
  cacheDir: ".agentium-skill-cache",  // optional, defaults to os.tmpdir()/agentium-skill-cache
});

const skill = await loader.load({
  url: "https://github.com/agentiumOS/skill-example.git",
  ref: "v1.0.0",                  // branch, tag, or commit SHA
  subdir: "skills/my-skill",      // optional - path inside the repo
});

console.log(skill.name);    // from SKILL.md frontmatter
console.log(skill.script);  // path to the entry script inside the cache
```

## URL formats accepted

| Format                                 | Example                             |
| -------------------------------------- | ----------------------------------- |
| `https://github.com/owner/repo.git`    | the canonical form                  |
| `https://github.com/owner/repo`        | trailing `.git` is added if missing |
| `git@github.com:owner/repo.git`        | SSH form — uses your SSH keys       |
| `git+https://...`                      | strips the `git+` prefix            |
| Self-hosted GitLab / Gitea / Bitbucket | any URL `git clone` accepts         |

The cache is keyed by `(url, ref, subdir)` hash, so the same logical skill at different refs lives in different cache directories.

## `LoadSkillOptions`

```typescript theme={null}
interface LoadSkillOptions {
  url: string;       // required - any URL acceptable by git clone
  ref?: string;      // branch, tag, or commit. Defaults to the repo's default branch.
  subdir?: string;   // optional path inside the repo where SKILL.md lives
  force?: boolean;   // skip cache check, always re-clone
}
```

### `ref` selection

* `ref` omitted → uses the remote default branch (usually `main`).
* `ref: "main"` → tracks `main` (re-cloned on `force: true` or first miss).
* `ref: "v1.0.0"` → pinned to a tag — recommended for production. Tags are immutable in well-managed repos.
* `ref: "<commit-sha>"` → maximally pinned. Recommended when you can't trust the upstream tag policy.

### `subdir`

When a repo contains multiple skills (a monorepo of skills), point at the one you want:

```typescript theme={null}
await loader.load({
  url: "https://github.com/agentiumOS/skills.git",
  ref: "v2",
  subdir: "math/calculus",
});
```

The loader reads `<repo>/math/calculus/SKILL.md` as the skill entry.

### `force: true`

Bypasses the cache check. Useful in CI to verify the cache layer works.

## Cache layout

```
<cacheDir>/
  <sha1(url:ref:subdir)>/
    .git/
    SKILL.md
    scripts/
      main.ts
    ... (the rest of the repo or subdir)
```

The cache directory is created on first use. Delete it to force re-clones:

```bash theme={null}
rm -rf .agentium-skill-cache
```

## Using a loaded skill in an Agent

```typescript theme={null}
import { Agent, GitSkillLoader, openai, SkillManager } from "@agentium/core";

const loader = new GitSkillLoader();
const skill = await loader.load({
  url: "https://github.com/agentiumOS/skill-jq.git",
  ref: "v1.0.0",
});

const manager = new SkillManager();
manager.register(skill);

const agent = new Agent({
  name: "json-bot",
  model: openai("gpt-4o"),
  skills: manager,
});
```

The agent now has the skill's tools wired in and the SKILL.md is injected into the system prompt automatically.

## Multi-skill bundles

For a curated set of skills, load them in parallel:

```typescript theme={null}
const refs = [
  { url: "https://github.com/agentiumOS/skill-jq.git", ref: "v1.0.0" },
  { url: "https://github.com/agentiumOS/skill-sql.git", ref: "v0.3.2" },
  { url: "https://github.com/your-org/internal-skills.git", subdir: "billing", ref: "main" },
];

const skills = await Promise.all(refs.map((r) => loader.load(r)));
const manager = new SkillManager();
for (const s of skills) manager.register(s);
```

## Security considerations

Loading code from a Git URL is loading code. If the LLM controls the URL, you're shipping arbitrary remote code execution.

Hard rules:

* **Don't accept Git URLs from the LLM or end user as tool inputs.** Skill URLs should be hardcoded or come from a trusted admin config.
* **Pin to a tag or SHA in production.** A branch ref can change under you.
* **Vendor skills you don't control.** If you depend on a public skill, fork it to your own org and pin a tag of your fork. Update on your schedule.
* **Run skills with the same isolation you'd run untrusted tools.** Combine with [`SandboxAgent`](/features/sandbox-agent) for hard isolation.
* **Audit the cache directory** before deploying. `find .agentium-skill-cache -name "*.sh" -exec cat {} \;` should not surprise you.

## Roadmap

* **Signature verification:** require a detached signature from a known maintainer key before accepting a skill.
* **Skill registry:** a community index (à la npm) for discovery.
* **Auto-update:** "pin to v1.\* and notify when a v1.0.5 is published".

## See also

* [Skills overview](/skills/overview) — what skills are and how SKILL.md works
* [`SandboxAgent`](/features/sandbox-agent) — for executing skill code safely
* [Multi-Tenant](/features/multi-tenant) — per-tenant skill configuration