Create skills

Write a SKILL.md with clear task guidance.

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: Use when answering customer support questions about product policy, refunds, or tone.
---

# Support skill

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	Intent-based routing rule for when the agent should load this skill

Write the description as a Use when… rule. Keystroke advertises attached skills to the agent as a compact catalog of names and descriptions, then the agent loads matching skills with skill_view. The description is the routing signal — describe the situation, not the file contents.

Keep the body short, push detail to references

Skills work by progressive disclosure: the agent loads the short SKILL.md first via skill_view, 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}/. After loading SKILL.md, the agent can open a packed reference with skill_view({ name, file_path }).

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 relative path from SKILL.md.

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.