Skip to content

skills.md

Latest commit

 

History

History
58 lines (34 loc) · 3.85 KB

skills.md

File metadata and controls

58 lines (34 loc) · 3.85 KB
Raw

Skills Design

English | 简体中文

This document describes the goals, direction, and boundaries of the tinyagent Skills module.

Goals

Skills give the Agent strictly validated, auditable, progressively loaded text instructions and related resources. They extend how the model works, but do not load plugin code, modify the Tool Registry, or acquire extra permissions through metadata.

The module aims to:

  • discover Skills explicitly from built-in directories and the Workspace skills/ directory;
  • strictly validate names, frontmatter, bodies, resources, and filesystem types;
  • include only an index in context by default and load full bodies on demand;
  • let the user explicitly activate a Skill for one request;
  • freeze a consistent view of Skills within a Session.

Directory and format

A Workspace Skill lives at skills/<name>/SKILL.md; only immediate children of skills/ are discovered. The name must match its directory and use lowercase kebab-case with a maximum length of 64 characters.

Frontmatter must contain name and description, and the body cannot be empty. Optional fields are always, version, author, license, compatibility, allowed-tools, and metadata. allowed-tools and metadata are currently informational only; they do not change tool permissions, environment variables, or execution behavior.

A valid Workspace Skill overrides a built-in Skill with the same name. An invalid override is isolated and tinyagent falls back to the valid built-in version, so one damaged file cannot also remove a bundled capability.

Progressive loading

For an ordinary Skill, only its name and description enter the system index; its source path is not exposed. When the model considers the Skill relevant, it uses the built-in read-only read_skill(name) tool to load the complete body from the frozen snapshot. The call passes through the unified Tool Runtime and is audited in Session messages and the CLI tool lifecycle.

Users can explicitly activate a Skill in their original text with an exact, case-sensitive $name reference, for example:

Use $release-notes to prepare notes for this release.

Use $$release-notes to escape a reference. Unknown, incorrectly cased, and duplicate references do not cause repeated activation. After direct injection, the model should not call read_skill for the same Skill. The body of an always: true Skill always enters the system prompt and is not injected again for a $name reference.

The index, always-on bodies, and content returned by read_skill are frozen on the Session's first provider request. A new Session, explicit resume, or new Runtime reads file changes. This prevents system instructions from drifting halfway through a conversation.

Persistence semantics

A body activated with $name is used only to construct that turn's provider message. It does not replace the original user text or enter long-term SQLite history or summaries. Calls to read_skill and their results are persisted as ordinary Assistant/Tool messages because they are auditable actions initiated by the model.

Security validation

Parsing uses strict safe YAML and rejects:

  • duplicate keys, unknown top-level fields, custom tags, and incorrect field types;
  • malformed frontmatter fences, empty bodies, and oversized files;
  • symbolic links and special files in the Skill root, directory, SKILL.md, or resources;
  • names that differ from the directory or violate the kebab-case definition.

An invalid Skill does not prevent ordinary conversation, but skills validate returns a non-zero status and doctor reports degraded health.

Boundaries

A Skill is validated text and resources, not a Python plugin, Shell-script installer, or permission declaration. Reading a Skill does not automatically register tools, inject secrets, execute its code, or expand Workspace and MCP permissions.