Skip to main content

Use a Skill

Agent skills let you package reusable instructions, reference files, and helper scripts in a GitHub repository and mount them into an agent's session sandbox at /skills/<repo-name>.

1. Structure your skill in GitHub​

Each skill directory (or standalone *.md file) must contain a SKILL.md file starting with YAML frontmatter that defines a lowercase name and a description:

document-skills/
└── skills/
├── pdf/
│ ├── SKILL.md
│ └── references/
│ └── extraction-checklist.md
└── docx/
└── SKILL.md

Example skills/pdf/SKILL.md:

---
name: pdf
description: Read, create, merge, split, and rotate PDFs.
---

Install `pypdf` with `python -m pip install pypdf` if missing.
Read the supplied file with `PdfReader` before summarizing; use `PdfWriter` for edits.
Save outputs under `/workspace` and verify them before attaching.

Frontmatter and file requirements​

  • SKILL.md must begin with --- YAML frontmatter containing unique keys and at most 10 YAML aliases.
  • name: Required lowercase identifier matching ^[a-z0-9][a-z0-9-]{0,63}$ (1–64 characters). All skills selected within a source must have unique names.
  • description: Required non-empty string up to 1,024 characters (no control characters other than \n, \r, \t).
  • Only regular Git files (100644 or 100755) are allowed. Symlinks, submodules, and special files are rejected.

2. Attach the skill to a primary agent​

Configure metadata.runtimeDetails.skills on your MultiAgentEngine primary agent. Every GitHub skill source requires a GitHub integration credentialId (for both public and private repositories):

import { MultiAgentEngine, createAgentModelConfigFromRef } from '@culvii/kit';

function createDocumentAgent() {
return new MultiAgentEngine({
id: 'document-agent',
name: 'Document Agent',
role: 'primary',
systemPrompt: 'Help the user inspect and transform uploaded documents.',
model: createAgentModelConfigFromRef('anthropic/claude-sonnet-4-5', 'my-anthropic-credential'),
permissions: {
default: {
read_file: 'approve',
write_file: 'approve',
exec_process: 'ask',
attach_output_file: 'approve',
},
},
metadata: {
runtimeDetails: {
networking: {
type: 'limited',
allow_package_managers: true,
},
skills: [
{
type: 'github_repository',
url: 'https://github.com/org/document-skills',
source: 'skills/pdf',
credentialId: 'my-github-credential',
ref: 'main',
fallback_paths: ['skills/default'],
},
],
},
},
secondaryAgents: [],
});
}

createDocumentAgent();

How source and fallback_paths resolve​

  • source (required, 1–500 chars) selects a repository-relative *.md file or a folder containing one or more */SKILL.md files.
  • fallback_paths (optional, 1–100 entries, each 1–500 chars) lists ordered alternative paths checked when source is not present or contains no SKILL.md. Only the first matching path is imported.
  • Multiple sources from the same GitHub repository share /skills/<repo-name>. Identical overlapping files are copied once; conflicting file contents or file-vs-directory collisions are rejected.
  • Two sources from different repositories that share the same lowercase <repo-name> are rejected as a mount collision.

3. How the agent uses skills at runtime​

  1. Session start: When a new session is created, the platform resolves ref (default 'HEAD') to an exact commit SHA, validates all selected files against the size and file-count limits, and writes them to /skills/<repo-name> inside the session sandbox snapshot.
  2. Catalog injection: On every turn, the primary agent receives only the compact catalog (skill_id, name, description) in its system prompt.
  3. On-demand reading (read_skill): When a skill is relevant, the model calls the built-in read_skill tool with { skill_id, path? } to load SKILL.md or any UTF-8 text resource owned by that skill (verified by SHA-256 hash against the session snapshot). Binary files in a skill cannot be read through read_skill and must be inspected using permitted sandbox tools.
  4. Untrusted guidance: Skill instructions do not grant tool permissions, credentials, or network access. Any commands or package installations the skill recommends still require the primary agent's configured permissions.default and networking rules.
  5. Updating skills: Skills are pinned to the session snapshot at creation time. Adding, removing, or refreshing skills requires starting a new session (restarting a direct session preserves the original snapshotted skills).

4. Skill limits​

LimitDefaultNotes
Files per configured source200 filesIncludes SKILL.md and files in subfolders; excludes directories and unselected repository files.
Size per file1 MiBMaximum raw (unencoded) byte size of any single file in a skill source.
Total size per configured source8 MiBMaximum combined raw (unencoded) byte size across all selected files under one source entry; separate entries in skills each get their own 200-file and 8 MiB budget.
Combined catalog prompt size1 MiBMaximum UTF-8 byte length of the session-wide skill catalog prompt injected into the primary agent's system prompt.
Max path length500 charactersApplies to source, each fallback_paths entry, and every repository-relative file path.
Max fallback_paths100 entriesOrdered fallback paths per configured source (1–100 when provided).
Max repository URL / ref / credentialId length500 / 200 / 128 charsHTTPS github.com/<owner>/<repo> URL only; credentialId matches ^[A-Za-z0-9_-]{1,128}$.
Max repository Git tree entries10,000 entriesTotal files and directories across the entire GitHub repository's recursive tree.

See MultiAgentEngine → Skills and Limits & Quotas for the full reference.