Agent Skills: Stop Stuffing Workflows Into Your Rules File

This post assumes familiarity with AI coding agents (Cursor, Claude Code, Windsurf, etc.), basic prompt engineering concepts, and rules files (Cursor’s .cursor/rules/ or Claude Code’s CLAUDE.md).

If you’re new to agent-assisted development, start with your tool’s getting-started docs first. If you haven’t used rules before, read the Cursor rules docs or Claude Code’s memory docs before continuing, understanding rules is essential context for why skills exist.

The problem: Rules that become operating manuals

Every team’s rules file follows the same trajectory. It starts with a few sensible guardrails:

• “Ask before destructive actions”
• “Don’t add new dependencies without approval”

Then someone adds a checklist for billing code. Another person adds migration procedures. A third contributes API design templates. Six months later, your “rules” section is a 5,000-token operating manual that loads on every single agent interaction.

What goes wrong:

• The base prompt gets bloated. Every conversation pays the token cost of every workflow, even ones that never fire.
• Important policies get buried. “Never delete production databases” sits next to “For billing code, check idempotency keys”; the agent treats them with equal weight.
• Specialized workflows can’t be reused. That carefully written migration review checklist is locked inside one project’s rules file.
• Maintenance is painful. Changing a single procedure means editing a giant block of text and hoping nothing else breaks.
• Debugging gets harder. When the agent misbehaves, tracing the cause through a wall of interleaved concerns is tedious.

Rules are meant to be guardrails, short, always-on policies that shape behavior across all tasks. When you overload them with task-specific procedures, you’re using the wrong tool for the job.

Read more: React Best Practices: Separation of Concerns & Code Optimization

What are agent skills?

A skill is a self-contained folder that packages a specific workflow or expertise area:

my-skill/

├── SKILL.md          # Required: instructions + metadata

├── scripts/          # Optional: executable code

├── references/       # Optional: documentation

└── assets/           # Optional: templates, resourcesCode language: PHP (php)

The SKILL.md file is the entry point. Its frontmatter contains a name and description; the body contains the actual instructions.

Here’s a real example – a skill that applies Dependency Inversion to a module:

---
name: dependency-inversion
description:
  Refactor a module to follow the Dependency Inversion Principle by extracting
  interfaces, inverting concrete dependencies, and wiring via injection. Use
  when the user asks to decouple modules, invert dependencies, extract an
  interface, apply SOLID principles, or improve testability of tightly coupled
  code.
---

Decouples modules by replacing direct imports of concrete implementations with
injected abstractions, improving testability and swappability.

## Dependency Inversion Progress:

- [ ] Step 1: Identify concrete dependencies in the target module
- [ ] Step 2: Extract an interface (port) for each dependency
- [ ] Step 3: Update the module to depend on the interface, not the concrete
- [ ] Step 4: Create an adapter implementing the interface for the original concrete
- [ ] Step 5: Wire the adapter via constructor or factory injection
Code language: CSS (css)

Skills use progressive disclosure to manage context in three stages:

1. Discovery. At startup, agents load only the name and description of each available skill. A few tokens per skill and enough to know when one applies.
2. Activation. When a task matches a skill’s description, the agent reads the full SKILL.md into context.
3. Execution. The agent follows the instructions, loading referenced files or running bundled scripts as needed.

A project can have dozens of skills installed. The agent only pays the token cost for the ones it uses in a given conversation.

Before and after

A pattern that comes up constantly. Check:

Before, everything lives in rules:

• “Always ask before risky actions”
• “Don’t add new dependencies without approval”
• “For billing code, inspect idempotency”
• “For migrations, check rollback paths”

All four statements load on every prompt, every time. The last two are irrelevant unless the developer is actively working on billing or migrations.

After – keep rules short, move expertise into skills:

Rules (always loaded):

• Ask before risky actions
• Don’t add new dependencies without approval

Skills (loaded on demand):

• billing-review – idempotency checks, payment edge cases
• migration-review – rollback paths, data integrity verification

The rules stay focused on universal policies. The specialized knowledge activates only when it’s needed.

Real Numbers

One real-world React project restructured from rules-only to rules-plus-skills and measured the token impact on prompt startup:

That’s a reduction of 4,908 tokens at startup – 69% less context consumed before the agent even begins working. The full skill instructions still exist and still get used. They don’t load until the agent needs them.

Skills vs rules: When to use which

Skills and rules solve different problems:

Use rules for universal policies that should govern every interaction.

• “Ask before destructive actions.”
• “Use conventional commits.”
• “Prefer composition over inheritance.”

Use skills for task-specific workflows that only matter in certain contexts.

• “How to write a Playwright e2e test.”
• “How to scaffold a new API endpoint.”
• “How to review billing code for payment edge cases.”

Read more: Machine Learning Explained: What It Is, How It Works, and Why It Matters for Business

Where agent skills fit alongside MCPs and subagents

Skills aren’t the only way to extend agent capabilities. Two other patterns, MCP servers and subagents, solve different problems.

MCP (Model Context Protocol)

MCP gives agents a standardized way to connect to external tools, data sources, and applications. It’s a USB port for agents to access live systems.

Skills and MCPs complement each other. A skill teaches the agent how to use the tools an MCP provides. The skill says “here’s the workflow for reviewing a PR.” The MCP provides the GitHub API access to fetch diffs and post comments.

Worth noting: MCP tool responses consume token limits. Large payloads from MCP calls fill the context window fast, which makes the lean-context argument for skills even stronger.

Subagents

Subagents are specialized worker instances that handle subtasks independently, often in parallel.

Skills tell an agent what to do. Subagents handle who does it. A subagent might load a skill to learn how to perform its delegated task.

Choosing the right tool

These mechanisms layer together. Rules for safety guardrails, skills for team workflows, MCPs for tool access, subagents for parallelizable work.

Why this matters for teams

Token savings matter. The organizational payoff matters more. Skills turn team knowledge into portable, versioned artifacts that any agent can pick up and execute.

When a senior engineer writes a security-review skill, every developer on the team gets the same review checklist – new hire or veteran. The knowledge doesn’t live in someone’s head or a Confluence page that nobody reads. It lives where the agent uses it.

Sharing skills across teams

Skills are folders. Distribute them with tools developers already have. Agent runtimes that support skills recognize multiple installation scopes:

Project-scoped skills get committed to the repo and travel with it. User-scoped skills are personal – your preferred code style, your writing workflow.

For team distribution, the simplest approach is a shared Git repo. Point a directory in your project at it via submodule, and updates come in when you pull:

git submodule add https://github.com/your-org/shared-skills .claude/skills/shared

A practical starting point

Where to begin:

1. Audit your rules file. Anything task-specific is a skill candidate.
2. Start with one high-value skill. Pick the workflow your team repeats most often – test writing, PR review, service scaffolding.
3. Put it in the repo. Project-scoped skills require zero infrastructure. Commit the folder, and every team member’s agent picks it up automatically.
4. Iterate based on usage. Watch how the agent activates the skill. Refine the description if it triggers too often or not enough. Tighten the instructions when the agent misses steps.
5. Promote to share. Once a skill proves itself in one project, move it to a shared repository or registry for broader use.

Trade-offs and limitations

Agent skills may have some limitations, as:

• Discovery depends on description quality. If a skill’s description doesn’t match how developers phrase their requests, the agent won’t activate it. Writing good trigger descriptions takes iteration.
• Skills are another thing to maintain. They drift out of date like documentation does. A stale skill that teaches the wrong workflow is worse than no skill at all.
• Not every agent runtime supports them yet. Skills as a pattern are gaining traction but aren’t universally standardized. Check your tool’s docs for current support.
• Overhead for small projects. If your rules file is 500 tokens and covers everything you need, extracting skills adds organizational complexity without meaningful token savings.

Conclusion

If your rules file is starting to feel messy, you already know. You’ve been scrolling past sections thinking “this doesn’t belong here.” Trust that instinct. Pull it out into a skill folder. Give it a name and description. See what happens.

Further Reading

• Agent Skills Specs – the spec itself
• The Complete Guide to Building Skills for Claude (PDF) – Anthropic’s comprehensive guide
• Claude Code skills documentation – Claude Code-specific implementation details
• Cursor skills documentation – IDE-specific implementation details
• Skills.sh – browse and discover community skills