Create skills - Keystroke

A skill is a folder under src/skills/ containing a SKILL.md and any supporting references. This page covers the format and the conventions that keep a skill useful.

Create the folder

Make a folder named for the skill (the folder name is how you’ll attach it to an agent) and add a SKILL.md:

src/skills/support/
  SKILL.md
  references/
    refund-policy.md

Write SKILL.md

A SKILL.md follows the Agent Skills specification: YAML frontmatter with a name and a description, then a focused body.

src/skills/support/SKILL.md

---
name: support
description: Support playbook for product questions and refund policy.
---

# Support skill

Read this skill when answering customer support questions.

Follow the refund policy in the product guide and keep replies concise.
Escalate billing disputes over $500 to a human.

Frontmatter	What it does
`name`	The skill’s name; match it to the folder name
`description`	A short summary of when the agent should use this skill

The description matters: it’s what an agent uses to decide whether a skill is relevant, so describe the situation it applies to, not just what it contains.

Keep the body short, push detail to references

Skills work by progressive disclosure: the agent reads the short SKILL.md first, then loads deeper material only when the task needs it. Keep SKILL.md to the essentials and put long policies, examples, and edge cases in a references/ folder:

src/skills/support/
  SKILL.md                      # when to use it + the key rules
  references/
    refund-policy.md            # the full policy
    escalation-matrix.md        # detailed procedures

Reference files are a convention, not a fixed structure; name and organize them however reads best. Everything in the skill folder is materialized into the agent’s workspace at /workspace/agent/skills/{slug}/, so the agent can open a reference by path when it decides it needs it. References aren’t the only kind of supporting material. The whole folder is copied verbatim, so a skill can also ship helper scripts the agent runs with its shell tools, or assets like templates and fixtures it reads:

src/skills/report/
  SKILL.md
  references/format.md
  scripts/build-report.ts
  assets/template.html

Point the agent at them by path from SKILL.md.

Point the agent at the skill

A skill is available to an agent once you attach it, but you’ll often nudge the agent toward it in the systemPrompt so it knows the skill exists and when to reach for it:

systemPrompt: "Answer support questions. Use the support skill for policy and tone.",

Next steps

Attach skills to agents

Attach a skill to an agent by folder name.

Skills overview

What project skills are and when to use them.

Import skills

Reuse skills from external registries.

Files

Add static reference documents to a workspace.

​Create the folder

​Write SKILL.md

​Keep the body short, push detail to references

​Point the agent at the skill

​Next steps