Inference Gateway

Appearance

Agent Skills ​

Agent Skills are reusable, model-readable instruction folders that the Inference Gateway CLI (infer) loads on demand. Each skill is a directory with a SKILL.md playbook; the agent reads the body only when the skill is relevant, so a skill costs only its one-line metadata until it is actually used (and nothing at all when disabled).

The CLI uses the same on-disk format as Claude Code, Gemini CLI, and OpenAI Codex CLI, so a folder authored for any of those tools drops into .infer/skills/ - or the cross-tool .agents/skills/ open standard - unchanged. To browse or publish skills in the shared index, see the Skills Catalog.

Skills are enabled by default (since cli#618) - discovered skills are injected into every run's system prompt as lightweight metadata. Turn them off with agent.skills.enabled: false (or INFER_AGENT_SKILLS_ENABLED=false).

How skills work ​

When skills are enabled, three things happen across every run mode (chat, infer agent, channels, and scheduled runs):

  1. Discovery is always injected. The system prompt gains an AVAILABLE SKILLS: block listing each discovered skill's name, scope, description, and the absolute path to its SKILL.md. Only this metadata is added - the bodies are not loaded at startup.
  2. Explicit invocation activates a skill deterministically. When you invoke a skill by name (see Activation), the CLI injects an ACTIVE SKILL pointer telling the agent to read that skill's SKILL.md and follow it. This removes the old guesswork where activation depended on the model opportunistically deciding to read a file.
  3. The body is read on demand. Only the skill's metadata is ever injected. The SKILL.md body (and any references/*.md) stays progressive-disclosure - the agent reads it with the Read tool when it actually needs it, kept reachable by the sandbox carve-out.

On-disk layout ​

A skill is a directory containing a SKILL.md file, optionally alongside supporting material the model reads or executes once the skill is active:

text
.infer/skills/            # also scanned: .agents/skills/ and ~/.infer/skills/
└── pdf-helper/
    ├── SKILL.md          # required - the playbook + frontmatter
    ├── references/       # optional - long supporting docs, read on demand
    ├── scripts/          # optional - helper scripts the model runs via Bash
    └── assets/           # optional - templates, fixtures, images

The same <name>/SKILL.md folder layout applies under every root. The CLI scans three locations, in precedence order (highest first):

ScopePathPrecedenceNotes
Project-local.infer/skills/<name>/SKILL.mdHighestChecked into the project; overrides a same-named skill in any other scope
Open standard.agents/skills/<name>/SKILL.mdMiddleThe shared .agents/ convention, so community skill folders work without modification
User-global~/.infer/skills/<name>/SKILL.mdLowestPersonal defaults available across every project

.agents/skills/ is an emerging open standard adopted across agent tooling (Claude Code, Gemini CLI, OpenAI Codex CLI, and others). The CLI scans it as a middle-precedence location so a skill folder published by a community author works unchanged, without copying it into .infer/skills/.

When the same name exists in more than one scope, the higher-precedence copy wins: a project .infer/skills/ skill overrides an .agents/skills/ skill, which in turn overrides a user-global ~/.infer/skills/ skill - useful for overriding a shared or personal default with a per-project variant.

The SKILL.md contract ​

SKILL.md is a markdown file with a YAML frontmatter block at the top:

markdown
---
name: pdf-helper
description: Extract text from PDFs. Use when the user asks to read, summarise, or analyse a PDF file.
---

# PDF Helper

1. Use the Bash tool to invoke `pdftotext input.pdf -` and capture stdout.
2. If the PDF is image-only, fall back to `tesseract` for OCR.

Frontmatter rules, validated at discovery time and re-validated after every install:

FieldRule
nameRequired. ≤64 chars, lowercase letters / digits / hyphens only. Must equal the directory name. Must not contain infer, claude, anthropic, gemini, or openai.
descriptionRequired. Non-empty, ≤1024 chars. This is the routing signal the model uses to decide when a skill is relevant - make it actionable (say what it does and when to use it).

Unknown frontmatter keys (for example Anthropic's allowed-tools: or Gemini's disabled:) are tolerated and ignored, so cross-vendor skills validate without edits.

Built-in skills ​

The CLI ships a small set of built-in skills embedded in the binary. On infer init they are seeded into the user-global ~/.infer/skills/ - the same directory the skills loader scans - only if absent ("seed-if-absent"). Once on disk they are ordinary user-scope skills: discovered, shown by infer skills list, and injected as lightweight metadata exactly like a skill you authored there yourself. Because seeding never overwrites an existing folder, your edits survive every later infer init.

The first built-in is the tmux starter skill:

SkillWhat it teaches the agent
tmuxDrive interactive terminal programs - TUIs, REPLs, pagers, a debugger, or another CLI's chat UI - that the plain Bash tool cannot script, by running them inside tmux and scripting them with send-keys / capture-pane. It prefers to add a pane to the tmux session you already have open so the work stays visible, and only falls back to a detached session in a headless, CI, or piped run.

Customizing a built-in ​

A built-in is just a user-scope skill, so you tune it with the same knobs as any other skill - there is no special "built-in" mode:

GoalHow
Edit in placeChange ~/.infer/skills/tmux/SKILL.md. A later infer init never re-seeds over your edit.
Override per projectAdd a .infer/skills/tmux/ (or .agents/skills/tmux/) folder; it shadows the built-in for that repo (first match wins).
Disable itAdd the name to agent.skills.disabled_skills.
Reset to the shipped defaultRun infer init --overwrite to re-seed it.

Refreshing a built-in after a CLI upgrade. A plain infer init will not re-seed over an already-initialized ~/.infer, so a newer built-in shipped by a CLI upgrade does not land automatically. To pick it up today, either replace the one ~/.infer/skills/<name>/SKILL.md by hand, or run infer init --overwrite - the latter also refreshes the other shipped ~/.infer defaults, so reach for it when you want a clean baseline rather than a single-skill update. (Moving seeding to load-time is a tracked CLI follow-up.)

Enabling and disabling ​

Skills are enabled by default. To turn them off (or back on) use the config file, the config set command, or an environment variable:

yaml
# .infer/config.yaml (project) or ~/.infer/config.yaml (user)
agent:
  skills:
    enabled: true # default - set to false to turn skills off
    max_chars: 4000 # cap on the rendered AVAILABLE SKILLS block (0 disables the cap)
    disabled_skills: [] # optional list of skill names to skip
bash
# Disable for this project's .infer/config.yaml
infer config set agent.skills.enabled false

# Or disable globally in ~/.infer/config.yaml
infer config set agent.skills.enabled false --userspace

# Or disable for a single run via environment variable
INFER_AGENT_SKILLS_ENABLED=false infer chat
SettingTypeDefaultDescription
agent.skills.enabledbooltrueMaster switch. Also enables the sandbox carve-out.
agent.skills.max_charsint4000Cap on the rendered AVAILABLE SKILLS block. 0 disables the cap.
agent.skills.disabled_skillsstring[][]Skill names to discover but never inject or activate.

The matching environment variable INFER_AGENT_SKILLS_ENABLED takes precedence over the config file. To keep skills off everywhere, set agent.skills.enabled: false in your user config (~/.infer/config.yaml).

When max_chars is set (default 4000), skills whose full entry would exceed the budget are listed by name only in the AVAILABLE SKILLS block - their descriptions and paths are omitted. These skills remain fully invocable via /<name> or the "use the <name> skill" phrase; the agent reads the full SKILL.md on demand through the sandbox carve-out. Set max_chars: 0 to disable the cap and render every skill's full entry.

The matching environment variable INFER_AGENT_SKILLS_MAX_CHARS overrides the config value.

Managing skills ​

bash
# List discovered skills (works regardless of agent.skills.enabled)
infer skills list
infer skills list --format json

# Install (three accepted forms)
infer skills install pdf-helper                                              # by name, from the Skills Catalog index
infer skills install acme/internal-comms                                     # owner/repo GitHub shorthand
infer skills install https://github.com/anthropics/skills/tree/main/skills/pdf  # full directory URL

# Install flags
infer skills install pdf-helper --user        # install to ~/.infer/skills instead of ./.infer/skills
infer skills install pdf-helper --overwrite   # replace an existing skill folder of the same name

# Uninstall by directory name
infer skills uninstall pdf-helper
infer skills uninstall internal-comms --user  # remove from the user scope

# The same operations from inside chat
> /skills list
> /skills install acme/internal-comms
> /skills uninstall pdf-helper

infer skills list works whether or not the feature is enabled, so you can verify discovery (and see validation errors for skipped skills) before turning skills on.

A bare <name> resolves through the public Skills Catalog index. The owner/repo and full-URL forms install straight from GitHub - the URL must point at a directory (https://github.com/<owner>/<repo>/tree/<ref>/<path>); URLs at /blob/ (a file) or the repo root are rejected with a clear error.

Installer notes:

  • infer skills install writes to ./.infer/skills/ by default, or to ~/.infer/skills/ with --user. It never installs into .agents/skills/ - that location is for skill folders you vendor yourself or that another agent tool drops in, and the CLI discovers them there read-only (see On-disk layout).
  • Frontmatter is re-validated after download against the same rules used at discovery - a half-installed skill is never left on disk. Without --overwrite, an existing folder is left untouched and the install fails fast.
  • Unauthenticated GitHub requests are limited to 60 per hour per IP (easily exhausted on shared CI runners). Set GITHUB_TOKEN (or GH_TOKEN, matching the gh CLI) to raise the limit to 5,000/hour and to install from private repositories the token can access.
  • Refs containing a literal / (such as feature/foo branches) are not supported - use a tag, the default branch, or a single-segment branch.
  • Uninstall takes the on-disk directory name, regex-validated before any filesystem operation, so it cannot traverse outside the skills directory. There is no confirmation prompt (it matches npm uninstall / brew uninstall).

Activation ​

Discovery puts every skill's metadata in the system prompt, but activation is explicit and deterministic. The CLI scans your messages for an invocation and, on a match, injects an ACTIVE SKILL pointer - the invoked skill's description and absolute SKILL.md path - instructing the agent to read that file and follow it.

Two triggers activate a skill, in any run mode (chat, infer agent, channels, scheduled runs):

TriggerExampleWhere it works
/<name> slash invocation/pdf-helperChat input
"use the <name> skill" phrase (case-insensitive)use the pdf-helper skillAny mode - chat, infer agent, channels, scheduled runs

Typing /pdf-helper for a known installed skill is now routed to the agent and flags the skill active, rather than dead-ending as an "Unknown shortcut".

Activation behavior:

  • Only metadata is injected. The pointer carries the skill's description and path - never the full body. The SKILL.md body stays progressive-disclosure and is read on demand with the Read tool, reachable thanks to the sandbox carve-out.
  • More than one skill can be activated in a single message (for example /pdf-helper /git-helper, or naming two skills in prose).
  • Repeated invocations are de-duplicated across the conversation, and tokens that don't match a known skill are ignored.
  • Only your messages are scanned - a skill name appearing in an assistant reply does not self-activate the skill.

/skills <cmd> and /<name> are different things. /skills list|install|uninstall manages skills; /<name> (a bare skill name) activates an already-installed skill for the current turn.

Skills sandbox carve-out ​

A skill's instructions only reach the model through the Read tool (progressive disclosure). But user-scope skills live in ~/.infer/skills, which is outside the default Read sandbox:

yaml
tools:
  sandbox:
    directories: ['.', '/tmp', '.infer/tmp'] # default

Without a carve-out, Read ~/.infer/skills/<name>/SKILL.md is denied as "outside configured sandbox directories", so the skill never loads. This is exactly what broke the @infer CI bot, which installs to the user scope with infer skills install <skill> --user --overwrite and then runs the agent outside the project directory.

The carve-out: when agent.skills.enabled is true, the Read sandbox automatically grants read access to ./.infer/skills and ~/.infer/skills (and everything under them). Installed SKILL.md and references/*.md are therefore reachable even when the agent runs outside the project directory, such as in CI.

How it relates to tools.sandbox.directories ​

The carve-out is automatic and additive - you do not add the skills directories to tools.sandbox.directories yourself:

AspectConfigured tools.sandbox.directoriesSkills carve-out
Default value['.', '/tmp', '.infer/tmp']./.infer/skills and ~/.infer/skills
How it is grantedExplicit - you list each directoryImplicit - applied only when agent.skills.enabled
AccessGoverns Read tool access generallyRead-only, scoped to the skills directories
When skills disabledUnchangedNot applied (Read of ~/.infer/skills is denied)

Two guarantees still hold on top of the carve-out:

  • tools.sandbox.protected_paths wins. Protected patterns are checked first, so a file like *.env or .infer/config.yaml under the skills tree stays denied even though the directory is carved out.
  • Lookalike siblings are not granted. Only the exact ./.infer/skills and ~/.infer/skills directories (and their descendants) are allowed - a sibling such as ~/.infer/skills-backup is not.

If you set tools.sandbox.directories: [], sandboxing is disabled entirely and the carve-out is moot. See the CLI security model for the full sandbox and protected-paths picture.

Security ​

A skill can instruct the model to run shell commands, read files, or call external APIs. Treat a skill like any other piece of executable content - only install skills from trusted sources. The CLI's normal tool-approval system still gates each Write/Edit/Delete/Bash call, but a malicious skill could craft a plausible-looking command. The name validator rejecting vendor strings (claude, anthropic, gemini, openai, infer) makes impersonating an official skill harder, but it is not a substitute for reviewing what you install.