Attach skills to agents

Attach skills to agents by name.

You attach a skill to an agent by listing its folder name in the agent’s skills array. Keystroke materializes the attached skills into the agent’s workspace before each prompt runs, advertises them in the system prompt, and exposes skill_view so the agent can load them on demand.

Attach by folder name

The skills option on defineAgent() takes the folder names of skills under src/skills/:

src/agents/support.ts

import { defineAgent } from "@keystrokehq/keystroke/agent";

export default defineAgent({
  slug: "support",
  name: "Support",
  description: "Answers support questions using the support skill.",
  systemPrompt: "Answer support questions with clear, concise replies.",
  model: "openai/gpt-5.6-sol",
  skills: ["support"],
});

For skills: ["support"], Keystroke expects a folder at src/skills/support/ with a SKILL.md. If no such folder exists, the agent fails to build with an “unknown skill” error; the name and the folder must match.

You do not need to nudge the agent with skill paths in systemPrompt. Attached skills are listed automatically, and the agent loads relevant ones with skill_view.

Attach more than one

List as many skills as the agent needs:

skills: ["support", "billing", "escalation"],

Each is materialized into the workspace under its own folder, so they don’t collide. Only skills listed here are advertised or loadable for that agent.

Where skills land at runtime

Attached skills are written into the agent’s workspace at /workspace/agent/skills/{slug}/ before the prompt runs. Keystroke also injects an <available_skills> catalog into the system prompt and registers skill_view. The agent loads SKILL.md first, then pulls in packed references/ (or other files) on demand. Seeding is idempotent: the files are written once per session and the agent’s own edits during a run are preserved.

Skills and files together

An agent can use both skills and files. Skills give it instructions it loads on demand; files give it context documents to read. A typical support agent uses both:

import { defineSandbox } from "@keystrokehq/keystroke/sandbox";

export default defineAgent({
  slug: "support",
  name: "Support",
  description: "Answers using product files and the support skill.",
  systemPrompt: "Answer support questions using product context and attached skills.",
  model: "openai/gpt-5.6-terra",
  skills: ["support"],
  sandbox: defineSandbox({ files: "support" }),
});

Next steps

Create skills

Write a SKILL.md with clear task guidance.

Attach files to agents

Add static context documents alongside skills.

Build agents

Configure models, tools, skills, and files.

Import skills

Reuse skills from external registries.