SKILL.md files that the Agent loads on demand. This guide covers Skill vs Rule vs MCP, directory layout aligned with agentskills.io, discover-activate-execute progressive disclosure, a six-step creation runbook, ecosystem data, and Mac Mini 24/7 host selection for production agents.
Why Agent Skills matter in 2026: three limits of traditional prompts
The trajectory of AI agents is straightforward: chatbot, then task assistant, then operator with domain workflows. Anthropic published Agent Skills as an open standard in late 2025; Cursor 2.4+, Claude Code, Codex, and Gemini CLI now share the same SKILL.md pattern. A Skill you write in Cursor often works in Copilot or Codex with only a path change—portable procedural knowledge, not vendor lock-in for a single IDE session.
Repeated labor: Every conversation re-states multi-step flows—commit, push, write PR body—and steps get skipped or drift between sessions.
Context pollution: Pasting an entire deploy manual into a Rule means it always consumes tokens, crowding out code, diffs, and the actual question.
No team reuse: Chat history cannot be Git-managed; teams cannot share agent runbooks the way they share libraries.
The Skill fix: Split workflows into folders; description handles routing; body loads only when the task matches. Scripts live under scripts/—the script source does not sit in context; only stdout/stderr feeds the Agent.
One-line definition: A Skill is an operator manual for the Agent—do the right thing at the right time. That rhymes with Hermes skill compounding after tasks, but Cursor emphasizes human-authored specs plus Git collaboration over automatic skill synthesis.
Community catalogs in early 2026 are often cited at 30,000+ installable Skills across marketplaces and aggregators. The standard is Apache 2.0 for reference code and CC-BY-4.0 for documentation—enough licensing clarity that enterprises can adopt without negotiating a single-vendor EULA for every workflow file.
Agent Skill vs Rule vs MCP: comparison matrix
| Dimension | Rule | Skill | MCP |
|---|---|---|---|
| Load timing | Every conversation by default | On demand when task matches | When tool call connects server |
| Best for | Naming, no-comments policy, brand tone | Deploy, PR, security audit, domain runbooks | GitHub API, databases, browser tools |
| Context cost | Fixed overhead | Full body only when activated | Schema and tool results per call |
| Analogy | New-hire handbook | Specialized SOP | Phone book plus API socket |
| MESHLAUNCH side | Repo .cursor/rules/ | .cursor/skills/ or .agents/skills/ | Optional CI and Issue tooling |
Rules answer what the Agent should always obey; Skills answer what steps to follow for this class of task; MCP answers which external capabilities can be invoked.
Cursor's guidance is explicit: keep Rules small and high quality; move rarely used flows into Skills. Built-in /migrate-to-skills (2.4+) converts legacy dynamic rules and slash commands into Skill folders so Rule files do not balloon into unreadable megabytes that load every session.
MCP is not a competitor—it is the wire. A deploy Skill might say: fetch open issues via MCP, run scripts/validate.py, then gh pr create. Without MCP you still need shell access or REST calls; without Skills the model improvises step order every time. Teams that conflate the three layers usually either overload Rules or expect MCP schemas to replace written procedures—they cannot.
SKILL.md file structure and three-level progressive loading
Standard project layout:
.cursor/skills/deploy-app/
├── SKILL.md
├── scripts/
│ ├── validate.py
│ └── deploy.sh
├── references/
│ └── REFERENCE.md
└── assets/
└── config-template.json
Monorepos can nest paths such as apps/web/.cursor/skills/; Skills surface only when editing files under that subtree—similar to a paths glob in frontmatter that scopes discovery to relevant directories.
--- name: deploy-app description: >- Use when the user needs to deploy the app, mentions "go live", "release to production", or "switch staging/production". paths: apps/web/** disable-model-invocation: false --- # Deploy application ## Steps 1. Run `scripts/validate.py` to verify environment variables 2. Execute `scripts/deploy.sh <environment>` 3. Confirm health check endpoint returns 200
Three-level loading (agentskills.io and Cursor docs align): Level 1 Discovery—at startup only name and description from every Skill enter context; Level 2 Activation—when the task matches, the full SKILL.md loads; Level 3 On demand—during execution the Agent reads references/ and runs scripts/ (outputs enter context; script source does not). Triggers: automatic routing from description, dialog /skill-name, or @skill-name for explicit attachment. Set disable-model-invocation: true when you want slash-command-only activation—for destructive or billing-sensitive flows.
| Discovery path | Scope |
|---|---|
.cursor/skills/ | Cursor project |
.agents/skills/ | Claude Code / Codex / Gemini CLI |
~/.cursor/skills/ | Cursor user global |
~/.agents/skills/ | Cross-tool global |
Practice summary: Write description as trigger conditions, not marketing copy; one Skill, one job; keep SKILL.md under roughly 500 lines and push detail to references/; explain why each step exists so the Agent can adapt; pick one verb family—deploy or release, not both interchangeably.
Progressive disclosure is the architectural bet: discovery metadata is cheap enough to list hundreds of Skills; activation is expensive enough that you only pay when the workflow applies. That is why stuffing deploy steps into Rules fails economically—the model reads them even when you are fixing a CSS typo.
Create your first Agent Skill: six-step runbook
Fastest path: In Cursor Agent type /create-skill, describe the workflow in plain language, follow the wizard, and save under .cursor/skills/.
Manual create: mkdir .cursor/skills/your-skill-name/, add SKILL.md; name must match the folder (lowercase, digits, hyphens).
Write description: List verbs and phrases users actually say—"open PR", "merge request", "gh pr create"—because auto-routing depends on this field, not the H1 title.
Extract scripts: Put repeatable commands in scripts/; the markdown states when to run them and how to roll back on failure. Use forward slashes: scripts/deploy.sh.
Migrate legacy rules: Run /migrate-to-skills to convert dynamic rules and old slash commands, then verify the list under Settings → Rules.
Acceptance test: Trigger with a real task—if the Agent skips the Skill, fix description before bloating the body. Use Gather → Act → Verify: read git status, execute, then confirm with tests or HTTP checks.
Common 2026 Skill categories (illustrative, not endorsements): developer velocity—prompt lookup, skill installer, Ralph-style autonomous test loops; frontend—Vercel-adjacent React/Next performance and a11y audits; workflow—PR Skill, TDD Skill, skill-writer meta-Skills. Unlike OpenClaw ClawHub distribution, Cursor Skills target IDE coding sessions. Unlike Hermes auto-skill synthesis, this path stresses human review plus Git PR as the quality gate before teammates inherit your runbook.
Version Skills like application code: tag releases, document breaking changes in references/CHANGELOG.md, and add a one-line smoke test in CI that greps for required frontmatter keys. A broken description is silent failure—the Agent simply never activates—so treat routing text as part of your public API.
2026 ecosystem data and Mac cloud 24/7 hosts: hard numbers
Open standard: agentskills.io defines frontmatter, Markdown body, and discovery paths; Anthropic engineering posts describe Skills as folders that package procedural knowledge portably across tools.
Cross-platform: The same Skill loads in Cursor, VS Code Copilot, Codex CLI, and peers; Microsoft Agent Framework ships SkillsProvider for discovery and run_skill_script in 2026 ecosystem coverage.
Host and compounding: Skills tied to launchd, Xcode signing, macOS browser automation, or a Telegram Gateway (see the Hermes memory guide) break when a laptop lid closes—roughly 60% uptime in practice kills Cron and Gateway SLAs. M4 idle draw sits around 4–6W; a typical Gateway stack 15–25W—both favor always-on hardware.
A MESHLAUNCH-shaped use case: support or ops teams encode device model plus lease term to quote sheet, standard contract draft, and return checklist as project Skills on a rented Mac Mini running Cursor Agent beside production Gateways—no personal laptop sleep or permission fights. Pure Linux VPS runs generic Skills but lacks macOS-only paths; Raspberry Pi I/O and RAM choke browser-heavy Skills.
When you need 24/7 validation of Skill plus Gateway plus local model routing, MESHLAUNCH Mac Mini M4 bare-metal rental is usually the cleaner path: dedicated Apple Silicon, SSH with the same directory layout as your desk, tarball .cursor/skills and agent state before offboarding. See rental pricing for a day trial; ops boundaries live in the help center. Compared with free cloud IDE tiers: no persistent daemon, no custom launchd—long-running Skill compounding still needs a host you control.
MCP connects external APIs and tools; a Skill is the runbook that tells the Agent when and in what order to call them. They complement each other—a Skill body can say pull Issues via MCP, then run gh pr create.
Skills are structured guidance; the model still decides. Descriptions that mirror real user phrasing trigger more reliably; production steps should document rollback. You can order an isolated M4 for destructive acceptance tests.
Generic workflows—commit hygiene, test writing—belong in ~/.cursor/skills/; repo-specific flows in .cursor/skills/ committed to Git. Cursor 2.4+ is stable; early features ship in Nightly. More deployment questions sit in the help center.