Skip to main content

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

​
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. GitSkillLoader lets you distribute skills via Git rather than copying directories around or publishing npm packages.

​
Quick start

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

FormatExample
https://github.com/owner/repo.gitthe canonical form
https://github.com/owner/repotrailing .git is added if missing
git@github.com:owner/repo.gitSSH form — uses your SSH keys
git+https://...strips the git+ prefix
Self-hosted GitLab / Gitea / Bitbucketany 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

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: 
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: 
rm -rf .agentium-skill-cache

​
Using a loaded skill in an Agent

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: 
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 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