I wrote an article a few months ago about using markdown files as living context for agentic coding (Agentic Coding in 2025), I am over-the-moon excited that a similar method has now become an open standard in 2026!

If you've been coding with agents for some time, you may have recongized the same pattern that I have overtime: document once, reference everywhere. That approach has now crystallized into an open standard! Agent Skills. Cursor and Claude Code both support it. This post is a technical walkthrough of skills, how they relate to rules and AGENTS.md, and how to author skills locally—including using the built-in create-skill (skill-creator) skill. Creating custom skills per applicaiton has provided me with amazing results.

What Are Agent Skills?

Agent Skills are portable, version-controlled packages that teach AI agents how to perform domain-specific tasks. They can include:

• Instructions (markdown in SKILL.md)
• Executable scripts (in a scripts/ directory)
• Reference docs (in references/)
• Static assets (templates, configs in assets/)

The format was originally developed by Anthropic, released as an open standard, and is documented at agentskills.io. Cursor adopted it; you can read the official docs at Cursor → Context → Skills.

Why Skills Instead of Ad-Hoc Markdown?

Skills are the standardized evolution of “many markdown files as references”: same idea, with a clear contract and better agent integration.

The Cursor Context Stack: Rules, AGENTS.md, Skills, References, Scripts

Cursor gives you several ways to feed persistent context to the agent. They work together; skills sit alongside (and sometimes replace) rules and AGENTS.md.

1. AGENTS.md

• What it is: A single markdown file in the project root (or subdirectories) with agent instructions.
• Format: Plain markdown, no frontmatter or globs.
• Use case: Simple, readable project-level instructions without the overhead of multiple rule files.

Example (Cursor Rules docs):

# Project Instructions
 
## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns
 
## Architecture
- Follow the repository pattern
- Keep business logic in service layers

Cursor supports AGENTS.md in the project root and in subdirectories.

2. Project Rules (.cursor/rules/)

• What they are: Markdown (.md) or frontmatter-enabled (.mdc) files in .cursor/rules/, version-controlled and scoped to the codebase.
• Control: Each rule can be Always Apply, Apply Intelligently, Apply to Specific Files (globs), or Apply Manually (@-mention).
• Use case: Domain knowledge, project-specific workflows, style/architecture decisions.

Rule types (from Cursor Rules):

Example .cursor/rules/api-guidelines.mdc:

---
description: "API design and validation standards for this project"
globs: "**/*.ts"
alwaysApply: false
---
 
# API Guidelines
- Use REST resource naming from PROJECT_PATTERNS.md
- Validate request bodies with Zod
- Return 4xx with structured error payloads

3. Agent Skills (SKILL.md + optional dirs)

• What they are: Folders containing at minimum a SKILL.md file; optionally scripts/, references/, assets/.
• Scope: Project (.cursor/skills/ or .claude/skills/) or user-global (~/.cursor/skills/ or ~/.claude/skills/).
• Use case: Procedural “how-to” and domain expertise; better than rules for dynamic context discovery and step-by-step workflows (Cursor Skills).

Skill directories (from Cursor Skills):

Important: Do not create skills inside ~/.cursor/skills-cursor/; that directory is reserved for Cursor’s built-in skills (e.g. create-skill, create-rule).

4. References (inside a skill)

• What they are: Extra documentation under a skill’s references/ directory (e.g. REFERENCE.md, STANDARDS.md). Loaded on demand when the agent needs them.
• Use case: Keep SKILL.md under ~500 lines; put detailed specs, examples, and edge cases in reference files. See Agent Skills specification and Cursor Skills – Optional directories.

Example layout:

.cursor/skills/deploy-app/
├── SKILL.md
├── scripts/
│   ├── deploy.sh
│   └── validate.py
├── references/
│   └── REFERENCE.md
└── assets/
    └── config-template.json

5. Scripts (inside a skill)

• What they are: Executable files in a skill’s scripts/ directory. The agent runs them when following the skill (e.g. scripts/deploy.sh staging).
• Use case: Reliable, repeatable steps (deploys, migrations, validation) without pasting large code blocks into the skill body. See Cursor – Including scripts in skills.

Reference scripts in SKILL.md by relative path from the skill root; use forward slashes (e.g. scripts/validate.py), not Windows-style backslashes.

SKILL.md Format (Technical Spec)

Every skill is a directory whose name must match the skill name in frontmatter. The spec is defined at agentskills.io/specification.

Required: Directory + SKILL.md

skill-name/
└── SKILL.md   # Required

Frontmatter (YAML)

Required fields:

Optional fields:

Example frontmatter:

---
name: deploy-app
description: Deploy the application to staging or production. Use when deploying code or when the user mentions deployment, releases, or environments.
license: MIT
---

Body

The rest of SKILL.md is markdown: step-by-step instructions, examples, edge cases. Recommendations:

1. Keep SKILL.md under ~500 lines for performance (create-skill and spec).
2. Progressive disclosure: Put only essential content in SKILL.md; link to references/ (and optionally scripts/) so the agent loads details on demand.
3. Reference files one level deep from SKILL.md; avoid long reference chains.

How to Use Skills in Cursor

1. Automatic: At startup Cursor discovers skills from the directories above. The agent is shown available skills and applies them when it decides they’re relevant (Cursor Skills).
2. Manual: In Agent chat, type / and search for the skill name, then select it (e.g. /deploy-app).
3. View skills: Cursor Settings (Ctrl+Shift+J / Cmd+Shift+J) → Rules → Agent Decides section lists discovered skills.

To make a skill manual-only (like a classic slash command), set in frontmatter:

disable-model-invocation: true

Creating Your Own Skills Locally

Option A: Use the Built-in Create-Skill Skill

Cursor ships with a create-skill skill that walks you through authoring a new skill. It’s one of the built-in skills in ~/.cursor/skills-cursor/ (do not edit that folder; use it by invocation).

Steps:

1. In Agent chat, type /create-skill (or /create skill if your UI shows it that way).
2. Answer or infer:
   • Purpose and scope
   • Personal (~/.cursor/skills/) vs project (.cursor/skills/)
   • When the agent should apply it
   • Domain knowledge and output format
3. The agent will create the directory, SKILL.md, and optionally references/ and scripts/ following best practices (concise, progressive disclosure, no Windows paths, etc.).

The create-skill skill emphasizes (see Cursor’s built-in skills and the Agent Skills specification):

• Descriptions in third person and specific (what + when).
• Under 500 lines for the main SKILL.md.
• Progressive disclosure and one-level-deep references.
• Clear workflow patterns (template, examples, conditional workflow, feedback loop).

Option B: Create a Skill by Hand

1. Choose location and name

• Project: .cursor/skills/my-skill-name/
• User: ~/.cursor/skills/my-skill-name/

2. Create the directory and SKILL.md

---
name: my-skill-name
description: One-sentence summary. Use when the user does X or asks about Y.
---
 
# My Skill Name
 
## When to Use
- Scenario 1
- Scenario 2
 
## Instructions
1. First step.
2. Second step; if needed, run `scripts/helper.sh`.
3. Third step.
 
## References
- Details in [references/REFERENCE.md](references/REFERENCE.md).

3. Add optional dirs

• scripts/ — executable scripts; reference in body as scripts/scriptname.
• references/ — e.g. REFERENCE.md; link from SKILL.md.
• assets/ — templates, configs, static data.

4. Validate (optional)

Use the skills-ref reference library to validate frontmatter and naming:

skills-ref validate ./my-skill-name

Migrating Rules and Commands to Skills

Cursor 2.4+ includes a migrate-to-skills flow (Cursor Skills – Migrating rules and commands):

1. In Agent chat, type /migrate-to-skills.
2. The agent finds:
   • Dynamic rules (“Apply Intelligently”, no globs) → converted to standard skills.
   • Slash commands (user/workspace) → converted to skills with disable-model-invocation: true.
3. Generated skills appear under .cursor/skills/. Rules with alwaysApply: true or specific globs are not migrated, as their behavior differs from skills.

Best Practices (Summary)

• Descriptions: Third person; include both what the skill does and when to use it; add trigger keywords.
• Size: Keep SKILL.md under ~500 lines; move detail to references/.
• Paths: Use scripts/foo.py, not scripts\foo.py.
• Terminology: Use one consistent set of terms (e.g. “API endpoint” everywhere).
• Scripts: Prefer small, self-contained scripts with clear errors over large inline code in the skill.
• Discovery: Don’t put skills in ~/.cursor/skills-cursor/; use ~/.cursor/skills/ or .cursor/skills/.

Quick Reference: Cursor Context at a Glance

Resources Referenced

• Agent Skills – Overview — Open standard and rationale.
• Agent Skills – Specification — SKILL.md format, frontmatter, optional dirs, validation.
• Agent Skills – What are skills? — Conceptual intro.
• Agent Skills – Integrate skills — For implementers.
• Cursor Docs – Context: Skills — Skill directories, scripts, references, migration.
• Cursor Docs – Context: Rules — AGENTS.md, project/user/team rules, rule types.
• Cursor Changelog 2.4 – Subagents, Skills, Image Generation — Skills in editor and CLI.
• Anthropic – Example skills (GitHub) — Official skill examples.
• agentskills/agentskills (GitHub) — Spec and skills-ref validation.
• Cursor Forum – How to use Agent Skills — Community usage.
• Cursor Forum – Cursor 2.4: Skills — 2.4 skills discussion.
• Agentic Coding in 2025 — Predecessor approach with markdown-as-context.
• cursor.directory — Community Cursor rules and references.
• Dev.to – From Prompt to Production: Rules, Skills, and Subagents in Cursor — Workflow-oriented guide.
• Claude Code – Extend Claude with skills — Claude Code’s skills docs (same open standard).
• Cursorhow – Agent Skills Hub — Curated skills and usage.

"The best model is not the one with the most parameters, but the one with the best instructions—and the best instructions are the ones that persist, version, and compose." — A modest paraphrase of the principle that capability emerges from structure plus context.