AgentKit Studio
Guides

Bind a skill

Write a valid SKILL.md, scan and import a local skill, then bind it to an agent.

A skill is a reusable set of operating instructions plus bundled files. This page goes from "write a valid SKILL.md" to "the agent reads it during a session".

Prerequisites

  • A directory containing SKILL.md. The filename must use exactly this spelling; matching is case-insensitive but the prefix must match.
  • At most 4 directory levels deep, counted from the scan root.
  • Dot-prefixed hidden files are skipped, except .well-known.
  • If the skill directory contains .py / .sh / .js / .ts / .ps1 scripts, or the body mentions network addresses, the import is flagged for human review.

Steps

Write SKILL.md

SKILL.md declares its identity in YAML frontmatter; the body is the instructions the agent reads.

---
name: release-notes
description: Draft release notes from commit history
version: 1.0.0
disable-model-invocation: false
user-invocable: true
---

# Generate release notes

1. Read the `git log` commits and group them by type.
2. Emit three sections: Added / Fixed / Breaking changes.
3. State the blast radius for every entry instead of just a title.
FieldRequiredDefaultNotes
nameYes—Becomes the directory slug: lowercased, non-alphanumerics to -, at most 64 characters
descriptionYes—One line describing what the skill does
versionNo1.0.0Participates in the resource ID
disable-model-invocationNo—When true, the model cannot invoke it; only the user can
user-invocableNo—When false, the user cannot trigger it manually

name determines the directory

name becomes the directory name under ~/.agentkit/studio/skills/<slug>. A name made only of symbols fails with SKILL_NAME_INVALID because no valid slug can be generated.

Open the scan dialog

Go to Resource library → pick Skill → click Scan local skills in the top-right corner.

Where to look

The Scan local skills button and the source filter dropdown on the Skill tab.

Choose scan directories

Leaving Scan directories (comma-separated) empty uses four default directories:

~/skills
~/.agents/skills
~/.codex/skills
~/.claude/skills

To scan elsewhere, enter absolute paths separated by commas, then click Scan.

Scanning only reads files and never executes a script. Every directory containing SKILL.md is a candidate, up to 4 levels deep.

Each candidate row shows the display name, path, version, file count, and one of three statuses:

StatusMeaning
ImportableThe directory is valid and no directory with the same name exists
InstalledThe destination directory already exists; importing overwrites
InvalidSKILL.md is missing or the frontmatter failed to parse; hover for diagnostics

Candidates with scripts or network markers additionally show contains scripts or network markers, human review required.

Where to look

The scan result list with all three statuses and the risk marker.

Preview, then import

Click Preview on a row to read that skill's full file tree and file contents. This is the only chance to verify content before importing — importing copies the files into the local skill store.

Check the candidates you want and click Import selected skills.

  • A successful import produces a resource ID of the form skill-<slug>-<version>.
  • A conflicting entry needs a re-scan before it is overwritten.
  • Importing only means "files are saved locally" — it does not mean script dependencies work, and does not mean the agent has been verified to execute it.

Where to look

The skill preview dialog with the directory tree and file content pane.

Bind it to an agent

Open Agents → select the target agent → Edit → Bind capabilities step → Skills block → click Bind and check one or more skills.

  • Multi-select is supported; the result is written to bindings.skills[].
  • A repeated resource ID is loaded only once.
  • Continue to Policy and confirmation and the summary shows N Skill.

Where to look

The Skills block in the Bind capabilities step with multi-select cards and the "N selected" counter.

Optional: bind a cloud Skill Center

Cloud skills live outside the local store and go through Platform resources → Skill Center:

  1. In the same step, find the Skill Center dropdown under Platform resources.
  2. Select a cloud Skill Space. Without a cloud connection the dropdown only offers "connect to the cloud first".
  3. The resulting configuration is selectionMode: discovery, includePublic: false, executionMode: outer-agent.

Cloud skills are downloaded and unpacked by the Host when a session starts. The archive must contain SKILL.md, otherwise you get SKILL_MANIFEST_MISSING.

What the runtime sees

After a successful binding, the agent's system context gains an index (src/skill-files.mjs:7):

已绑定的 Skill 文件:
- release-notes: 从提交记录生成发布说明草稿
  SKILL.md: "~/.agentkit/studio/skills/release-notes/SKILL.md"
  资源目录: "~/.agentkit/studio/skills/release-notes"

Key conventions:

  • Relative script paths are relative to the skill's resource directory, not the current workspace. This is the most common source of confusion.
  • The prompt requires the agent to execute the bound script rather than substitute freshly written code.
  • When a file or dependency is unavailable, the agent must report it honestly instead of pretending it succeeded.
  • The body is truncated at 12000 characters, and the index is injected first.

What success looks like

  • The skill appears under Installed / Connected in the resource library with source Local import.
  • Clicking View files shows the directory tree and lets you read each file.
  • The skill is checked in the agent's Bind capabilities step.
  • A message matching the skill description produces a reply that cites concrete rules from SKILL.md.

Common errors

Error codeCauseFix
SKILL_MANIFEST_INVALIDSKILL.md has no frontmatter, is missing name / description, or has invalid YAMLAdd both required fields inside --- fences
SKILL_NAME_INVALIDname cannot produce a valid slugUse letters, digits, and hyphens, for example release-notes
SKILL_MANIFEST_MISSINGThe cloud skill archive has no SKILL.mdRepackage so the file exists at the root or in a subdirectory
SKILL_ALREADY_EXISTSA skill with the same name is installedPreview and overwrite, or change name
SKILL_CANDIDATE_NOT_FOUNDThe candidate was cleaned upRe-scan; discovery sessions expire after 30 minutes
SKILL_DISCOVERY_TOKEN_INVALIDThe scan result expiredClick Scan again
SKILL_DISCOVERY_PATH_INVALIDThe candidate directory is not in this scan's recordsRe-scan before importing; do not reuse an old dialog
SKILL_NOT_INSTALLEDThe bound skill does not exist locallyImport it first, or unbind it from the agent
SKILL_BINDING_INVALIDThe binding ID is empty or has surrounding whitespaceSelect from the resource library instead of typing
SKILL_LOAD_AUTHORITY_CHANGEDSkill authority changed while loadingStart a new session
SKILL_PREVIEW_PATH_INVALIDThe preview path escapes the skill directoryOnly preview files listed in the tree
SKILL_SPACE_NOT_FOUNDThe cloud Skill Space is missing or inaccessibleCheck the cloud connection and the space ID
RESOURCE_ADAPTER_MISSINGA bound resource has no resolvable adapterVerify the Host loaded the matching resource adapter
What you want to knowWhere to go
The skill-to-resource binding modelResources and bindings
Scan, import, and storage implementationsrc/skill-discovery.mjs
Runtime skill projection and cloud unpackingsrc/skill-files.mjs
Binding and load orderingsrc/skill-bindings.mjs
The five skills/* operationsControl protocol
Binding MCP servers and knowledge basesBind an MCP server, Bind knowledge bases and Memory

On this page