Git-installable skills

Agentium supports two different skill mechanisms. GitSkillLoader loads an executable package with skill.json and a JavaScript module. Instruction-only SKILL.md discovery uses a separate manager; see skills overview. A repository containing only SKILL.md is not a valid executable package for this loader.

Quick start

This host helper loads an administrator-selected source and returns an Agent. It contacts Git and imports the package’s code, so review and pin the source before running it.

import { Agent, GitSkillLoader, type ModelProvider } from "@agentium/core";

export async function createSkilledAgent(model: ModelProvider, trustedSource: string) {
  const loader = new GitSkillLoader({ cacheDir: ".agentium-skill-cache" });
  const skill = await loader.load(trustedSource);
  return new Agent({ name: "skilled-assistant", model, register: false, skills: [skill] });
}

The caller runs the Agent and closes it in finally. Supply a real source owned by your organization, for example git+https://git.example.com/team/skills.git?subdir=packages/orders#v1.0.0. The example URL is a format illustration, not a downloadable fixture.

Package layout

orders/
  skill.json
  index.js
  instructions.md

skill.json

{
  "name": "orders",
  "description": "Order lookup tools",
  "version": "1.0.0",
  "main": "index.js",
  "instructions": "instructions.md"
}

The module exports getTools(), a tools array, or a supported default tool factory/array. Each entry must satisfy ToolDef. Declare runtime dependencies in the package and make them available in the host environment: the Git loader clones and imports; it does not run an npm install or build step. The returned Skill contains name, description, version, tools, optional instructions, and optional metadata. There is no script field.

URL formats accepted

Use git+https://... or git+ssh://.... The loader also recognizes HTTPS GitHub URLs ending in .git. A #ref suffix selects the branch, tag, or commit; ?subdir=... selects a directory containing skill.json.

`ref` selection

The default ref is main, or the constructor’s defaultRef. It is not automatically discovered from the remote. Pin an immutable commit when reproducibility matters; a branch or tag can move upstream.

Cache layout

An explicit cacheDir persists clones across runs; without one, the loader creates a temporary directory. Cache directories are keyed by sanitized repository URL and ref. Subdirectories of the same repository/ref share its clone. Existing clones are reused without fetching updates. There is no force option; refresh a reviewed deployment by selecting a new pinned ref or managing its cache while no process uses it.

Using a loaded skill in an Agent

Pass skills: [skill], or supported source strings, to the Agent. SkillManager is a standalone loader coordinator constructed with an array of sources; its dynamic method is addSkill(). Do not pass a manager as AgentConfig.skills.

Multi-skill bundles

For a host-owned curated list, call Promise.all(sources.map(source => loader.load(source))) and pass the resulting array as skills. Load only sources the host has authorized; the model must not select arbitrary Git repositories to import.

Execution boundary

Imported skill modules run inside the host process. A local subprocess wrapper does not provide operating-system isolation. If code requires isolation, choose an explicitly configured sandbox and keep the host’s credential and filesystem boundaries clear. To verify a package, first load a local reviewed fixture through LocalSkillLoader, inspect its tool names, and exercise those tools with deterministic inputs. Then verify the pinned Git packaging path separately. A successful clone alone does not establish that its tools are safe or correctly configured.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Git-installable skills

Quick start

Package layout

URL formats accepted

`ref` selection

Cache layout

Using a loaded skill in an Agent

Multi-skill bundles

Execution boundary

​Quick start

​Package layout

​URL formats accepted

​ref selection

​Cache layout

​Using a loaded skill in an Agent

​Multi-skill bundles

​Execution boundary

Quick start

Package layout

URL formats accepted

`ref` selection

Cache layout

Using a loaded skill in an Agent

Multi-skill bundles

Execution boundary