# Agent Skills vs Rules Files vs Retrieved Context: What Goes Where in 2026


URL: https://getunblocked.com/blog/agent-skills-vs-rules-files/
Published: 2026-09-07T09:30:00Z
Author: Dennis Pilarinos
Categories: AI Agents, Engineering Insights

Agent skills vs rules files vs retrieved context: a 2026 decision guide for the 3 layers of agent behavior, and the failure modes of mixing them up.

---
The GitHub trending page has been colonized by instruction folders. [Matt Pocock's skills collection](https://github.com/mattpocock/skills) sits near 255,000 stars, [affaan-m's ECC agent harness](https://github.com/affaan-m/ECC) is right behind it at roughly 252,000, and [Anthropic's own skills repo](https://github.com/anthropics/skills) has cleared 174,000. None of them contain a single line of application code.

## Why are skills repos suddenly everywhere?

Because the format finally standardized, and standardization made instructions shareable. [Agent Skills](https://agentskills.io/) began as an Anthropic format and is now an open standard: a folder with a SKILL.md file, loaded through progressive disclosure, supported by Cursor, Copilot, Gemini CLI, Codex, and dozens more clients. The [skills ecosystem report for 2026](https://agentman.ai/blog/agent-skills-ecosystem-report-2026) counts around 40 products supporting the standard and about 1.9 million public skills indexed from GitHub. The repos riding the wave range from Pocock's deliberately small set to ECC's maximalist harness, which bundles 286 skills, 68 specialized agents, and 94 commands into a single install that claims to work across Claude Code, Codex, and Cursor.

The star counts measure something real, but not what they appear to. One [analysis of the skills-repo wave](https://agentconn.com/blog/agent-skills-new-dotfiles-repos-racing-250k-stars-2026/) calls skills "the new dotfiles" and warns that "star velocity is measuring enthusiasm, not maturity." The same ecosystem report backs that up: SkillsBench scored 47,150 public skills at an average of 6.2 out of 12. The wave is real. The median artifact riding it is mediocre. Which makes it worth being precise about what skills are actually for.

## What are agent skills actually good at?

Procedures. A skill is a named, versioned way of doing one thing: running a release, triaging a bug, writing a spec. The [Claude Code skills docs](https://code.claude.com/docs/en/skills) draw the line cleanly: create a skill "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact." The loading model is the point. Skills disclose progressively, in three stages: the agent sees only names and short descriptions at startup, reads the full instructions when a task matches, and pulls bundled scripts or reference files only during execution. A rarely used runbook costs almost nothing until invoked; in Claude Code, only the description sits in context, capped at 1,536 characters.

The evidence favors small and sharp. In the same report's SkillsBench data, sets of two to three targeted skills lifted task performance by 18.6 points, while monolithic put-everything-in-one-document skills reduced it by 2.9. Pocock's collection follows the same philosophy: [a few dozen composable skills](https://www.aihero.dev/skills), each encoding one habit a senior engineer would apply anyway. The failure mode is stuffing facts into the procedure: a deploy skill that hardcodes last quarter's service names is a runbook fused to a snapshot, and the snapshot expires first.

## What still belongs in a rules file?

Constraints. A rules file (CLAUDE.md, AGENTS.md, .cursor/rules) is the always-loaded layer, which makes it the right home for anything that must hold on every single task: never commit to main, always use the internal HTTP client, run this linter before finishing. The [AGENTS.md standard](https://agents.md/) now covers more than 60,000 open-source projects, and [Cursor's rules docs](https://cursor.com/docs/context/rules) tell you to keep rules under 500 lines and skip anything a linter already enforces. Which file to write is [its own decision](https://getunblocked.com/blog/claude-md-vs-agents-md-vs-cursor-rules/); most teams land on [one file that every agent reads](https://getunblocked.com/blog/single-file-agent-instructions/).

The failure mode is bloat. Every procedure that creeps into the always-loaded file taxes every session, relevant or not, and grows until the agent starts ignoring it. That decay pattern is common enough to have a name and a fix: see [rules file rot](https://getunblocked.com/blog/rules-file-rot/) and [how to audit a bloated CLAUDE.md](https://getunblocked.com/blog/audit-fix-bloated-claude-md/). A useful tell during an audit: if a section describes how rather than never or always, it is a skill wearing the wrong clothes, and moving it out makes both layers better at their jobs.

## What should never live in either?

Facts that change. Who owns the payments service, which API version is current, what last week's incident review decided, whether the migration you are about to suggest was already tried and rejected. Write those into either static layer and you have created documentation with an expiry date and no expiry alert. This is [context rot](https://getunblocked.com/blog/what-is-context-rot/): the instructions stay fluent while the world they describe moves on, which is worse than missing instructions because nothing looks wrong.

Changing facts belong in the retrieval layer: context fetched fresh at task time from the systems where it actually lives. This is what a context engine like [Unblocked](https://getunblocked.com/) does. It connects the sources engineering knowledge is scattered across (GitHub, Slack, Jira, docs), answers with the current state rather than a snapshot, cites where each answer came from so a suspicious engineer can check, and respects existing permissions so agents only see what their operator could. The [tradeoff between static instructions and a context engine](https://getunblocked.com/blog/rules-files-vs-context-engine/) comes down to one question: does this line describe your intent, or the world? Intent changes slowly enough to write down. The world your team works in changes daily, which is why [team knowledge needs a live hub](https://getunblocked.com/blog/team-memory-hubs-ai-agents/) rather than a markdown fossil.

## How do the three layers work together?

Cleanly, once each holds only what it is built for. Rules constrain, skills execute, retrieval informs. A well-run agent session uses all three in one pass: the constraint layer says never push straight to main, the release skill says how a release proceeds, and retrieval reports which services changed since the last one. Here is the decision table:

| Layer | Loads when | Best for | Rots when |
| --- | --- | --- | --- |
| Agent skills | On demand, when the task matches | Procedures: multi-step workflows, runbooks, checklists | Facts get baked into the steps |
| Rules files | Every session, always in context | Constraints: conventions, prohibitions, invariants | Procedures accumulate and bloat the file |
| Retrieved context | At task time, per question | Current facts: ownership, decisions, state, history | The sources it draws from go unmaintained |


Note the third row's failure mode is different in kind. Skills and rules rot by being written once and left alone. Retrieval rots only if the underlying sources die, and your team updates Slack, GitHub, and Jira just by working. That asymmetry is the entire argument for [pushing changeable facts out of static instructions](https://getunblocked.com/blog/keep-agent-instructions-up-to-date/).

The migration path runs in one direction. Start from whatever you have today, usually an overgrown CLAUDE.md, and sort each block with the table above. Procedures move out into skills, one folder per workflow, where they gain versioning and stop taxing every session. Facts move out into whatever system already owns them, with retrieval wired in so the agent can ask. What remains is the constraint core: short, stable, and cheap enough to load everywhere. Teams that run this sort usually cut the always-loaded file by more than half without losing a single behavior, because most of what it held was never a constraint in the first place.

## FAQ

### Should I convert my CLAUDE.md into skills?

Partially. Keep the constraints (a few hundred lines at most of never/always statements and pointers) and extract every multi-step procedure into its own skill. The Claude Code docs recommend exactly this split, and it pays twice: the always-loaded file gets cheaper, and the procedures gain on-demand loading plus per-skill versioning. What you should not do is convert facts into either format; move those to retrieval or delete them. If you support several agents, the constraint core can live in one AGENTS.md so every tool reads the same source of truth.

### Are the big skills repos safe to install wholesale?

Treat them like dependencies, not decorations. Security research cited in the 2026 ecosystem report detected prompt injection in 36% of skills tested, and the SkillsBench average of 6.2 out of 12 says most public skills are mediocre even before you consider security. Install a handful from authors you trust (Pocock's set and Anthropic's official repo are both actively curated), read each SKILL.md before it runs, and prune what you do not invoke, since unused descriptions still occupy context budget. A skill you never audit is a third party writing instructions into your agent's context.

### Does retrieved context replace rules files?

No. Retrieval answers questions; it does not enforce anything, and asking it to police conventions is the third misfiling failure mode. A convention that lives only in old Slack threads gets applied only when the agent happens to ask about it, which is to say unreliably. A constraint you want applied on every task must be in context on every task, which is precisely what the always-loaded layer provides and retrieval does not. The three layers cover each other's blind spots, and no one of them can do the other two jobs. If you are trying to make one tool carry all three jobs, you have found [the limit of any single-tool setup](https://getunblocked.com/blog/why-not-just-claude-code/).

## The three-layer test

Before a line of agent guidance goes anywhere, ask three questions. Does it describe how to do something? Skill. Must it hold on every task regardless of relevance? Rules file. Could it be false in three months without anyone editing the file? Then it should not be written down at all; it should be fetched. Run the test over your existing setup and most teams find the same skew: a constraints file full of procedures, skills full of facts, and no retrieval layer at all, so the agent [relearns your organization from scratch every session](https://getunblocked.com/blog/claude-code-institutional-memory/). The 250,000-star repos will keep multiplying, and the good ones are genuinely worth installing. But a quarter-million stars on a folder of procedures does not solve the layer those repos cannot ship: nobody can publish your org's current state to GitHub. The skills wave is worth joining. Just file each thing where it rots slowest.