agents/skills

20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Agent Skills structure and file organization

A skill is a folder containing a SKILL.md file with metadata and instructions. The typical structure includes: SKILL.md (required, contains instructions and metadata), scripts/ (optional, executable code), references/ (optional, documentation), and assets/ (optional, templates and resources).

Progressive disclosure strategy in Agent Skills

Skills manage context efficiently through three phases: Discovery loads only name and description of each available skill at startup; Activation reads full SKILL.md instructions when a task matches a skill's description; Execution follows the instructions and optionally loads referenced files or executes bundled code as needed. This approach keeps agents fast while providing access to more context on demand.

SKILL.md frontmatter requirements

Every SKILL.md file must contain YAML frontmatter with two required fields: name (a short identifier) and description (instructions for when to use this skill). The Markdown body contains the actual skill content with no restrictions on structure.

Sandbox abstraction interface for Agent Skills

The Sandbox interface provides a consistent way to interact with the filesystem across different environments. It requires three methods: readFile(path: string, encoding: 'utf-8'): Promise<string> for reading files; readdir(path: string, opts: { withFileTypes: true }): Promise<{ name: string; isDirectory(): boolean }[]> for listing directory contents; exec(command: string): Promise<{ stdout: string; stderr: string }> for executing commands. This abstraction allows implementation differences depending on environment (Node.js fs, containerized sandbox, cloud storage, etc.).

SkillMetadata interface for discovered skills

Discovered skills are represented with the SkillMetadata interface containing three fields: name (string, the skill identifier), description (string, when to use the skill), and path (string, the filesystem path to the skill directory).

Discovery function for Agent Skills at startup

The discoverSkills function scans skill directories and extracts metadata from each SKILL.md file. It takes a Sandbox and array of directory paths. It iterates through directories looking for subdirectories, reads their SKILL.md files, parses the frontmatter for name and description, tracks seen names to allow project overrides (first occurrence wins), and returns an array of SkillMetadata. It gracefully continues when directories don't exist or skills have invalid SKILL.md files.

Frontmatter parsing for SKILL.md

The parseFrontmatter function extracts and parses YAML frontmatter from skill files using a regex pattern that matches content between opening and closing triple dashes: /^---\r?\n([\s\S]*?)\r?\n---/. It extracts the YAML content in capture group 1 and parses it using a YAML parser. It throws an error if no frontmatter is found.

System prompt construction for discovered skills

The buildSkillsPrompt function takes an array of SkillMetadata and returns a formatted string that instructs the agent about available skills. It lists each skill as '- {name}: {description}' and instructs the agent to use the loadSkill tool when the user's request would benefit from specialized instructions.

stripFrontmatter utility for SKILL.md content

The stripFrontmatter function removes YAML frontmatter from skill content using a regex pattern /^---\r?\n[\s\S]*?\r?\n---\r?\n?/ and returns only the Markdown body. It returns the trimmed content after the frontmatter, or the trimmed original content if no frontmatter is found.

loadSkill tool implementation

The loadSkill tool reads the full SKILL.md and returns its body without frontmatter. It accepts an input schema with a 'name' field (string, the skill name to load). It executes by: looking up the skill in the context's skills array (case-insensitive), returning an error if not found, reading the SKILL.md file using sandbox, stripping the frontmatter, and returning an object with skillDirectory (the skill path) and content (the Markdown body). The tool returns the skill directory path so the agent can construct full paths to bundled resources.

callOptionsSchema for agent configuration

The callOptionsSchema uses Zod to define the options passed to an agent. It requires two fields: sandbox (z.custom<Sandbox>() to provide filesystem/execution abstraction) and skills (z.array of objects with name, description, and path fields). This schema validates and types the options object.

readFile tool for agent filesystem access

The readFile tool reads a file from the filesystem. It accepts an input schema with a path field (string). It executes by extracting the sandbox from context and calling sandbox.readFile(path, 'utf-8'). It requires a description: 'Read a file from the filesystem'.

bash tool for agent command execution

The bash tool executes a bash command. It accepts an input schema with a command field (string). It executes by extracting the sandbox from context and calling sandbox.exec(command). It requires a description: 'Execute a bash command'.

ToolLoopAgent setup for Agent Skills

A ToolLoopAgent is configured with: model (yourModel), tools object containing loadSkill, readFile, and bash tools, callOptionsSchema for type validation, and prepareCall function. The prepareCall function receives { options, ...settings }, merges settings, appends buildSkillsPrompt(options.skills) to instructions, and creates a context object with sandbox and skills.

Agent runtime execution with Agent Skills

To run an agent with skills: create a sandbox using createSandbox with workingDirectory option, discover skills at startup with discoverSkills passing the sandbox and an array of skill directory paths (e.g., '.agents/skills' and '~/.config/agent/skills'), then call agent.run with prompt and options containing sandbox and skills. When the user's request matches a skill description, the agent calls loadSkill, the full instructions load into context, and the agent follows them using bash and readFile tools.

Accessing bundled skill resources via relative paths

Skills can reference files relative to their directory in instructions (e.g., 'templates/config.json' or 'bash scripts/setup.sh'). The agent receives the skill directory path from the loadSkill tool result and prepends it when constructing full paths. No special resource loading mechanism is needed—the agent uses the same readFile and bash tools it uses for everything else.

Agent Skills prerequisites and requirements

To support Agent Skills, an agent needs: filesystem access to discover and load skill files (read files, read directories), a loadSkill tool that reads SKILL.md content into context, and optional command execution capability if skills bundle scripts (such as a full sandbox environment).

Math problem solving agent with Llama 3.1

Example of an agent that solves math problems using Llama 3.1. Imports generateText, tool, isStepCount from 'ai', deepInfra from '@ai-sdk/deepinfra', and mathjs. Defines a calculate tool with description 'A tool for evaluating mathematical expressions' and inputSchema with expression string. Uses stopWhen: isStepCount(5) to limit iterations. The agent reasons step by step and uses the calculator tool multiple times if needed to solve problems like profit calculations.

Natural Language Postgres SQL Agent guide

The AI SDK provides a guide on how to build a Next.js app that lets you talk to a PostgreSQL database in natural language.

Agent Skills guide

The AI SDK provides a guide on how to extend an agent with specialized capabilities loaded at runtime from markdown files.

Give your agent this brain