Skills

A skill is an on-demand procedure following the SKILL.md convention: the harness advertises each skill by its description, and the model loads the full content only when the task calls for it. Skills are how you give an agent a multi-step workflow without carrying it in the always-on instructions.

Authoring forms

Three forms cover every case.

Form	Reach for it when
agent/skills/<name>.md	Flat markdown. Optional description frontmatter; the first body line is the fallback.
agent/skills/<name>/SKILL.md plus siblings	A packaged directory with reference files (references/…). Requires description frontmatter.
agent/skills/<name>.ts	Generated content, with defineSkill from @cursor/july/skills.

Flat markdown:

---
description: Use when a pull request needs a structured approval checklist.
---

# PR review checklist

1. Call `inspect_pr` and confirm required checks passed.
2. Summarize the PR title, author, and remaining risks.
3. Call `approve_pr` only after an explicit request; it requires approval.

TypeScript, when the content must be generated or carry inline sibling files:

import { defineSkill } from "@cursor/july/skills";

export default defineSkill({
  description: "Research unfamiliar topics before answering.",
  markdown: "Gather evidence first, then answer with the key facts.",
  files: { "references/checklist.md": "# Checklist\n\n- Find sources.\n" },
});

How skills reach the model

On the local runtime, skills land in the session workspace at .cursor/skills/<name>/SKILL.md, and the harness advertises and loads them natively. On the cloud runtime, skills aren't materialized. The VM only sees skills that exist in the cloud repo itself, and validate warns about the combination.

Instructions, skills, or tools?

Instructions are always in context: identity, tool-choice rules, the output contract. Keep them short. Skills load when relevant: procedures, checklists, house style. Reach for a skill when the model needs to follow something but only sometimes needs it loaded. Tools are typed, executable behavior: anything that must be correct every time belongs in tool code, not in prose the model might paraphrase.

A good skill description is a routing rule, not a title. Say when to use it, like "Use when a pull request needs a structured approval checklist," because the description is all the model sees before deciding to load it.

What's next

Continue with these pages:

• Instructions: what stays always-on
• Tools: when prose needs to become code
• Project layout: where skills sit in the tree