Skill vs Rule · Three-tier loading · SKILL.md spec · Six-step Runbook · Mac 7x24 practice
Still pasting the same long “open PR, run tests, update CHANGELOG” prompt into Cursor every week? Agent Skills turn complex flows into reusable playbooks. Pair them with Rules for guardrails and three-tier progressive loading so the Agent in 2026 behaves more like a colleague with SOPs than a one-off chat. This guide is for developers who write heavy prompts: we compare Skill vs Rule, explain SKILL.md and the agentskills.io ecosystem (31,000+ community skills), walk through a six-step Runbook to create your first Skill, and show how Mac Mini M4 monthly rental supports 7x24 Agents and Skill compounding.
2024–2025 “AI coding assistants” were mostly session completion. You re-explained context, constraints, and steps every time. In 2026, Cursor Agent (Skills strengthened from 2.4 onward) aims at task closure: read the repo, edit many files, call tools, ship to team standards. That knowledge cannot live only in chat history. It must sit in versioned Skill packages.
An Agent Skill is a folder under .cursor/skills/ or user-level ~/.cursor/skills/. The core file is SKILL.md (YAML frontmatter plus Markdown). You can add scripts/, references/, templates, and checklists. At discovery the Agent reads only name and description. After a match it activates the full body and loads attachments on demand. That avoids stuffing a 50-page Runbook into context at once.
If you already use .cursor/rules for “no comments” or “use pnpm only,” those are global guardrails. When the same release + code review + docs flow runs three times a week, growing Rules means paying tokens on every chat and makes sharing hard. Skills solve workflow reuse. Rules solve behavior boundaries. Section 2 tables the split.
Long prompts do not version: great prompts sit in Notion or Slack. The Agent cannot see them. One edit desyncs the team.
Context bloat: pasting a full Runbook crowds out code and diffs. Long jobs get truncated mid-flight.
Unstable triggers: without a structured description routing line, the Agent cannot pick the right playbook.
No progressive disclosure: large scripts and API docs stay in context. Simple subtasks still pay full token cost.
Not team-shareable: personal chat wins cannot be reviewed, merged, or rolled back like a Git branch.
Rules are traffic laws on the windshield. Skills are the shop manual in the glove box—you do not read the whole book until the fault appears.
Cursor Rules (.cursor/rules/*.mdc or project Rules) inject at session start always or by glob. They fit coding style, security red lines, and repo layout. Agent Skills follow the open agentskills.io standard (multi-tool since 2025). They default to three-tier on-demand loading for multi-step workflows, domain knowledge, and runnable scripts.
| Dimension | Rule | Agent Skill |
|---|---|---|
| Load timing | Injected at session start or on file path match | Discover → activate → read references/scripts on demand |
| Typical use | No comments, commit policy, framework choice | Open PR, deploy checks, domain API wiring, slash workflows |
| Context cost | Always resident; too many Rules keep eating space | Only metadata until triggered; then progressive expand |
| Analogy | Employee handbook / compliance | Role SOP plus toolbox (scripts, templates, linked docs) |
references/ and load when needed.scripts/validate.sh runs in sandbox; results return to the chat.Community Skills such as create-hook, create-rule, babysit (PR merge and CI), and split-to-prs already exist. MCP connects external systems. Skills teach the Agent when and in what order to use those tools. They stack; they do not replace each other.
Verified on Cursor 2.4+: use built-in /create-skill to scaffold, then tighten to team standards. The goal is to turn the prompt you only get right on the third try into a folder the team can review.
Run /create-skill in Agent chat: describe task type, trigger phrases, inputs, outputs, and taboos. Let the Agent draft SKILL.md and the tree.
Pick scope: project .cursor/skills/<skill-name>/ ships with Git; user ~/.cursor/skills/ holds cross-repo habits (never commit secrets).
Write frontmatter description: this is the routing key, not a summary. Use “USE when user asks to …” and “DO NOT use for …” so discovery matches precisely.
Progressive body: core steps stay in SKILL.md; long docs, OpenAPI, sample JSON go in references/; scripts in scripts/.
Test triggers: three positive prompts (should activate) and two negative (should not) in fresh sessions. Confirm context loads only what is needed.
Migrate old assets: lengthy Rules or one-off Commands via /migrate-to-skills or manual split. Move process content into Skills; keep Rules as short red lines.
--- name: release-pr-runbook description: USE when the user asks to open a release PR, ship a version bump, or run the pre-merge checklist. DO NOT use for hotfix without changelog or for dependency-only bumps. --- # Release PR Runbook ## Gather - Read package.json version and recent git tags. - List open PRs targeting main. ## Act - Bump version per semver. - Update CHANGELOG.md with user-facing bullets. ## Verify - Run test suite and lint. - Confirm CI green before requesting review.
| Path / field | Role |
|---|---|
SKILL.md | Required; frontmatter + main Runbook (aim for < 500 lines) |
name | Lowercase hyphen ID; matches folder name |
description | Trigger routing line; include USE when / DO NOT |
scripts/ | Validation, generators; Agent calls on demand |
references/ | Long docs, API notes; read after activation |
assets/ | Templates, diagrams, sample config (optional) |
Cursor’s Skill implementation aligns with agentskills.io. Three tiers drive token cost and stability:
Discovery: at startup or scan, load each Skill’s name + description only (tens of tokens per Skill). This forms the catalog.
Activation: after intent or keyword match, inject full SKILL.md (often hundreds to low thousands of tokens).
On-demand: load references/*.md or run scripts/* only when the body points there. No “open the whole book every time.”
Put the decision tree early in the body (scene A vs B). Push thick material into references. If a script output is huge, require the Agent to summarize key lines in the reply instead of pasting it all back.
Tip: a marketing-style description causes false triggers. Write it like a routing rule (conditions plus exclusions) to get L1 right. Official create-skill flows keep asking for trigger phrases for a reason.
Strong Skills follow four engineering rules: description as router, progressive disclosure, single responsibility (one Skill, one job family), and gather-act-verify body structure. Do not duplicate Rules—Rule says “write tests”; Skill says “how to run integration tests in this repo and read failure logs.”
| Skill / direction | Use case | Notes |
|---|---|---|
| Prompt Lookup | Tune repeat prompts, compare community templates | Less reinventing; align description format |
| React Best Practices | Component libs, RSC, performance, a11y | Externalize Vercel/team norms as a playbook |
| babysit / PR skill | PR comments, CI red, merge conflicts | Pairs with GitHub CLI and CI logs |
| create-rule / create-skill | Govern Cursor config itself | Meta-Skills for team scaffolding |
| sdk | Cursor SDK / Agent API integration | Programmatic Agent from backend or pipelines |
| loop | Scheduled patrol, cron-style Agent | Needs stable 7x24 host; see section 6 |
SKILL.md./create-skill and /migrate-to-skills in the default flow.description is a routing predicate, not an article blurb.Note: never put secrets or customer PII in description (L1 is always visible). Scripts use environment variables; gitignore sensitive references/ and explain access in the Skill body.
Skills are no longer locked to one IDE. agentskills.io offers the spec, validation ideas, and index entry points. Teams can publish internal Skill modules like an internal package registry. For individuals: fork a close community Skill, tune description and references/, review the diff in a PR.
When Skills move from “help me code” to 7x24 automation—/loop repo patrol, IM triggers for quote flows, or Cursor SDK on a long-lived server—host choice decides whether Skills compound:
~/.cursor/skills is long-term org memory.Typical setup: fixed project clone plus Skills submodule on a rented Mac; Hook runs scripts/verify.sh after merge; IM bot delivers intent, Mac executes per Skill. Same “Agent as infrastructure” idea as Hermes Gateway 7x24 and persistent memory, but Cursor Skills stay closer to daily IDE work.
Laptops and cheap VPS hosts work for writing and one-off Skill validation. Sleep, missing macOS-native automation paths, and no durable ~/.cursor state hurt 7x24. Pure API Skills can live in the cloud; once a Runbook needs local scripts, Keychain, or Apple tools, migration cost jumps. Teams that want Agent Skills as a always-on colleague with trigger and token savings compounding week over week get predictable OpEx from VpsMesh Mac Mini M4 cloud rental—uptime, remote KVM, fixed monthly fee. See Mac Mini M4 rental pricing, help center, and order page.
MCP (Model Context Protocol) is the layer that connects the outside world: databases, GitHub API, browsers, internal services via Server tools and resources. Agent Skills do not replace MCP. They are Markdown playbooks: which task to run first, which MCP tools to call next, how to verify. Analogy: MCP is outlets and cables; Skill is the power-on sequence in the device manual.
Put short rules you need on every code change in Rules (e.g. no comments, fixed package manager). Put occasional multi-step flows with scripts and appendices in Skills. Rule of thumb: on the third repeat of the same long prompt, run /create-skill. Keep Rule count low so L0 session is not full. Use /migrate-to-skills to move bloated Rule process sections out.
No. Cloud-only API Skills without macOS deps can run on Linux VPS via Cursor CLI or SDK. If Skills need Apple automation, local Keychain, or you want ~/.cursor/skills always on like a Gateway, Mac Mini M4 monthly rental is simpler. Rent one month to validate triggers and token curves. See Mac Mini M4 rental pricing and order page.