2026 Cursor Agent Skills Complete Guide: SKILL.md Format, Three-Tier Loading, and Mac Cloud 7×24 Runbook (With Decision Matrix)

1. Three pain points: why Agent Skills exist

1. Complex prompts do not scale across projects. Deployment Runbooks, security audit checklists, and PR templates get pasted into chat again and again. Team knowledge lives inside individual conversation histories, and onboarding a new engineer means re-explaining the same twelve steps. Skills move that knowledge into Git where code review applies.
2. Context fills with rules that are not relevant right now. Dumping an entire style guide into .cursorrules consumes tokens on every turn. When the Agent is diffing a single file, those always-on rules crowd out the actual patch context. Skills load only when the task matches—freeing budget for code.
3. Skills and hardware shape are disconnected. Even a perfect OpenClaw or Hermes Skill fails if the Gateway sleeps. Laptops suspend on lid close; cheap Linux VPS hosts lack native macOS and Xcode. The Skill exists on disk but never runs in production—see our Hermes Agent three-layer memory and always-on hardware guide for why uptime compounds Skill value.

One-line definition: a Skill is an operations manual written for an AI Agent, loaded at the right moment so the Agent does the right thing without you retyping the playbook.

Teams that treat Agent workflows as infrastructure—not chat tricks—ship faster because Skills encode guardrails once and reuse them across repos, CI jobs, and Gateway channels. The rest of this article shows the file format, loading mechanics, and where to host the daemons that execute them.

2. What a Skill is: comparison with Rules

Rules answer "how should code look?" Skills answer "what steps must happen before merge?" Keep lint preferences in Rules; put release gates, rollback scripts, and approval flows in Skills. A mature repo often carries a thin Rule layer plus a growing .cursor/skills/ tree checked into Git.

Skills can wrap slash commands and shell scripts, and they compose with MCP: MCP supplies tools (API clients, databases, browsers), while Skills orchestrate steps, branching, and failure handling. Think of MCP as the socket wrench and Skill as the torque sequence printed on the workshop wall.

3. SKILL.md file structure and format

Standard directory layout (compatible with Cursor, Claude Code, Codex, and Gemini CLI):

Minimal working SKILL.md example (following the agentskills.io open standard):

description is a routing key, not a summary. Wrong: "This skill contains deployment instructions." Right: state when to load—trigger phrases, scenarios, file globs. Cursor matches tasks against descriptions before pulling the full Skill body, so vague copy never activates.

Optional frontmatter fields extend routing and safety. paths scopes activation to matching files. disable-model-invocation: true forces manual /skill-name invocation—useful for destructive operations. metadata can tag owner teams or compliance tiers without bloating the instruction body.

4. Three-tier progressive loading

1. Discovery: The runtime reads only name and description to judge relevance. This tier stays tiny—often a few dozen tokens per Skill in the catalog.
2. Activation: When a match scores high enough, the full SKILL.md body loads and the Agent follows its steps.
3. On demand: The Agent pulls files from references/ when detail is needed. scripts/ execute locally; only stdout/stderr returns to context—the script source never consumes tokens.

Search paths include .cursor/skills/ (project), .agents/skills/ (portable), and ~/.cursor/skills/ (user-global). Cursor 2.4+ ships /create-skill for interactive authoring and /migrate-to-skills to lift legacy slash commands and fat Rules into Skills.

The three-tier model is why large Skill libraries remain practical: discovery stays cheap, activation pays only for the one workflow in flight, and references/scripts scale detail without linear token growth. Teams running twenty Skills on a Gateway should still monitor aggregate discovery cost—keep descriptions tight.

5. Always-on hardware decision matrix: where do Skills actually run?

agentskills.io is a cross-platform open standard; project Skills belong in Git with the same review bar as application code. Validate Gateway integration on macOS hardware before promoting a Skill to production—browser automation, code signing, and Keychain access behave differently on Linux containers. For headless Playwright Skills, follow our OpenClaw skill-browser deployment walkthrough on a Mac VPS node.

Linux VPS wins on raw uptime cost for text-only agents, but the moment your Skill chain touches xcodebuild, Apple notarization, or Metal-backed inference, you need macOS. Renting bridges the gap: monthly opex, no depreciation, RAM tier changes without buying new silicon.

6. Five-step Runbook: from zero to a production-ready Skill

Step 1 — Define the trigger scenario

Pick a high-frequency, repeatable task your team already documents in Notion or Slack. List the exact user phrases and file globs that should activate the Skill, then paste them into description. If two Skills overlap, narrow descriptions until only one should fire.

Step 2 — Create SKILL.md

Run mkdir -p .cursor/skills/my-skill and add SKILL.md. Keep name aligned with the directory name—Cursor uses both for routing and manual /my-skill invocation.

Step 3 — Split references and scripts

Move long policy text into references/REFERENCE.md. Put executable checks in scripts/. In the Skill body, explain why each step runs so the Agent can skip or adapt when context differs—do not paste fifty lines of shell inline.

Step 4 — Smoke test

Run a real task and confirm automatic triggering. Test manual /my-skill invocation. Flip disable-model-invocation for destructive flows and verify the Agent refuses to auto-run. Log token usage before and after—activation should beat pasting the same prompt raw.

Step 5 — Deploy to Mac cloud

rsync or git-pull the skills tree to your VPSMAC node. Register a launchd plist so the Gateway survives reboots—see Mac cloud Agent automation node for SSH delivery and daemon patterns. Pin Xcode and macOS versions on the node to match your Skill assumptions.

7. Citeable technical facts (2026)

• Open standard: The Agent Skills specification lives at agentskills.io. Minimum SKILL.md fields are name and description; optional fields include paths, disable-model-invocation, and metadata.
• Cursor built-ins: /create-skill walks interactive creation; /migrate-to-skills (2.4+) converts legacy Rules and slash commands into Skills.
• Security boundary: Audit third-party Skills from ClawHub before enabling exec or network permissions—reuse our OpenClaw production hardening checklist for Gateway tokens and sandbox policy.

8. FAQ

Skill vs MCP? MCP connects APIs; Skills orchestrate multi-step flows. Do Skills make the model rigid? No—the model still chooses tools and ordering within the Skill guardrails. Where should Skills live? Personal utilities in ~/.cursor/skills/; team workflows in .cursor/skills/ committed to Git with CODEOWNERS.

9. Conclusion: Skills answer "how," Mac cloud answers "always on"

Stacking prompts or stuffing Rules wastes tokens and resists version control. Laptops suspend when you travel; Linux VPS hosts cannot run Apple-native steps your Skill assumes. Skills compress repeatable workflows into SKILL.md files that load only when needed—solving the "how do we do this?" problem in software.

Two failure modes show up in support tickets weekly: teams that authored excellent Skills but hosted Gateways on hardware that sleeps, and teams that kept pasting prompts because Skills never survived a repo migration. The first needs always-on macOS; the second needs Git-backed Skill directories and a shared Mac cloud node for integration tests.

For production Agent Gateways—OpenClaw, Hermes, or Cursor-driven CI—that must stay reachable while you offline, renting a VPSMAC Mac cloud node trades predictable monthly cost for bare-metal macOS, launchd 7×24 uptime, and SSH access your Skill scripts expect. Check skills in locally, sync to the node, and let the Gateway run while the Skill library compounds across sprints.