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.mdmust begin with---YAML frontmatter containing unique keys and at most10YAML aliases.name: Required lowercase identifier matching^[a-z0-9][a-z0-9-]{0,63}$(1–64characters). All skills selected within a source must have unique names.description: Required non-empty string up to1,024characters (no control characters other than\n,\r,\t).- Only regular Git files (
100644or100755) 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–500chars) selects a repository-relative*.mdfile or a folder containing one or more*/SKILL.mdfiles.fallback_paths(optional,1–100entries, each1–500chars) lists ordered alternative paths checked whensourceis not present or contains noSKILL.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
- 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. - Catalog injection: On every turn, the primary agent receives only the compact catalog (
skill_id,name,description) in its system prompt. - On-demand reading (
read_skill): When a skill is relevant, the model calls the built-inread_skilltool with{ skill_id, path? }to loadSKILL.mdor 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 throughread_skilland must be inspected using permitted sandbox tools. - 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.defaultandnetworkingrules. - 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
| Limit | Default | Notes |
|---|---|---|
| Files per configured source | 200 files | Includes SKILL.md and files in subfolders; excludes directories and unselected repository files. |
| Size per file | 1 MiB | Maximum raw (unencoded) byte size of any single file in a skill source. |
| Total size per configured source | 8 MiB | Maximum 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 size | 1 MiB | Maximum UTF-8 byte length of the session-wide skill catalog prompt injected into the primary agent's system prompt. |
| Max path length | 500 characters | Applies to source, each fallback_paths entry, and every repository-relative file path. |
Max fallback_paths | 100 entries | Ordered fallback paths per configured source (1–100 when provided). |
Max repository URL / ref / credentialId length | 500 / 200 / 128 chars | HTTPS github.com/<owner>/<repo> URL only; credentialId matches ^[A-Za-z0-9_-]{1,128}$. |
| Max repository Git tree entries | 10,000 entries | Total files and directories across the entire GitHub repository's recursive tree. |
See MultiAgentEngine → Skills and Limits & Quotas for the full reference.