OpenWikivercel/ai

Skills

Purpose and Scope

Skills are the AI SDK harness mechanism for packaging reusable instructions so an agent runtime can discover them during a session. The harness documentation defines a skill as an instruction bundle useful for project conventions, workflow guidance, domain-specific procedures, or other repeatable guidance that should not have to be pasted into every prompt. In practice, a skill gives a coding agent a named, model-facing capability description plus deeper content it can consult when needed. This page focuses on the documented harness API surface for making those bundles available to a HarnessAgent.

Sources: content/docs/03-ai-sdk-harnesses/04-skills.mdx

A skill is different from ordinary session instructions because it is intended to be available on demand rather than always occupying the agent’s immediate behavioral prompt. The documentation recommends broad agent behavior and current priorities for instructions, while reusable procedures belong in skills. That distinction matters when you are building long-lived coding-agent sessions: stable rules, checklists, templates, and domain playbooks can remain discoverable without turning every turn into a large prompt. The result is a cleaner separation between the agent’s overall role and the optional knowledge it may need for a specific task.

Relevant Source Files

  • content/docs/03-ai-sdk-harnesses/04-skills.mdx - Defines the public harness skills concept, the HarnessAgent configuration shape, the fields on each skill, guidance for additional files, and the relationship between skills and instructions.

Core Primitives

The central primitive is the skill object passed through the skills setting when constructing a HarnessAgent. The documented fields are name, description, content, and files. The name is a stable identifier, so it should be short, predictable, and safe to refer to across documentation or workflows. The description is a short model-facing summary that helps the runtime understand when the skill is relevant. The content is the full instruction body, and files optionally carries supporting text assets bundled with the skill.

Sources: content/docs/03-ai-sdk-harnesses/04-skills.mdx

The files field is important because many reusable procedures are easier to maintain as references instead of one large instruction string. The source page specifies skill-relative POSIX paths such as reference.md, references/codes.md, and templates/config.json. Those paths can then be mentioned from the skill content so the agent knows which supporting document to read. Treat the file bundle as part of the skill’s portable contract: it should contain text that clarifies the procedure, checklist, template, or domain rules needed for repeatable execution.

Define Skills on a HarnessAgent

To make skills available, construct a HarnessAgent with a harness runtime, a sandbox, and a skills array. The first-party example uses claudeCode as the harness and createVercelSandbox with a Node runtime and an exposed port, then adds a careful-refactors skill. That skill asks the agent to prefer minimal diffs, preserve public APIs, and read a bundled checklist before editing. The important design point is that skills are session-scoped: once attached to the agent, they are available for the lifetime of that session.

Sources: content/docs/03-ai-sdk-harnesses/04-skills.mdx

const agent = new HarnessAgent({
  harness: claudeCode,
  sandbox: createVercelSandbox({
    runtime: 'node24',
    ports: [4000],
  }),
  skills: [
    {
      name: 'careful-refactors',
      description: 'Make small, low-risk code changes.',
      content:
        'Prefer minimal diffs. Preserve public APIs. Before editing, read references/checklist.md and follow it.',
      files: [
        {
          path: 'references/checklist.md',
          content: `# Refactor checklist
 
- Identify the smallest useful change.
- Preserve public APIs.
- Run the narrowest relevant test.`,
        },
      ],
    },
  ],
});

When adapting the example, start by naming the behavior you want the agent to discover. A refactoring skill, for example, should not only say “be careful”; it should encode the operational steps that define careful work in your project. The bundled checklist in the example turns a general preference into a concrete procedure: identify a small useful change, preserve public APIs, and run a narrow relevant test. This pattern works well for repository conventions, release procedures, migration checklists, incident-response playbooks, or framework-specific coding rules.

Skills Versus Instructions

Use skills when the guidance is reusable but not necessarily relevant to every turn. This includes reference material that should be discoverable by the harness runtime but does not need to dominate the agent’s context at all times. Use instructions for broad behavior that should apply continuously, such as the agent’s role, tone, safety limits, current task priorities, or session-wide constraints. A useful rule of thumb is that instructions shape the default agent, while skills provide optional procedures the agent can invoke when a task matches their description.

Sources: content/docs/03-ai-sdk-harnesses/04-skills.mdx

This separation also helps teams avoid overloading a coding agent with every internal convention up front. If your project has ten checklists, each can become a skill with a concise description and supporting files. The agent can still find the relevant procedure, but the session instructions remain focused on the immediate goal. Conversely, if a rule must always be followed regardless of task type, it should not be hidden inside a skill. Put always-on behavior in the main instructions and reserve skills for reusable, discoverable knowledge.

Implementation Details and Edge Cases

Skill-relative file paths should be written as POSIX-style paths, even if the host operating system uses a different separator. The documentation examples use forward-slash paths under the skill bundle, which makes them portable across harness runtimes and sandboxes. Because the skill content is where the agent learns to consult the files, include explicit references to the bundled paths when the additional material matters. A file that is bundled but never named or described may be less useful than a file that is clearly connected to an action step.

The documented skill fields are small, but they imply a clear authoring contract. Keep description short enough to serve as a relevance signal, and keep content specific enough to guide action without requiring the model to infer your process. Use files for longer checklists, templates, examples, and reference documents. If the skill represents a risky workflow, such as a refactor or migration, encode risk controls directly in the content and supporting files. That makes the behavior reproducible across sessions and easier for reviewers to audit.

After defining a skill, read the HarnessAgent documentation to understand the surrounding agent configuration, then review harness tools because tools and skills solve different parts of the agent problem. Tools let the model request actions, while skills provide reusable instructions about how and when to work. Harness adapters are the next step when you need to understand how a particular runtime exposes skills inside a sandboxed coding-agent environment. Together, these pages explain how instructions, tools, skills, adapters, and sandbox configuration form a complete harness session.

Sources: content/docs/03-ai-sdk-harnesses/04-skills.mdx

Ask a question...