What Belongs in a Skill vs a System Prompt

The Bloat Problem: Why Your Agent Gets Worse When You Add More Instructions

Here's a uncomfortable truth about AI agents that most builders learn the hard way: adding more instructions can make your agent worse, not better. The instinct to document everything — every convention, every workflow, every edge case — directly into always-on context seems responsible. The evidence says otherwise.

A February 2026 study from ETH Zurich researchers put this to the test, asking whether repository-level context files actually help coding agents. The results were sobering: LLM-generated context files reduced task success rates by approximately 3% compared to no context file at all, while increasing inference costs by over 20%. Even human-written files delivered only about a 4% improvement — a thin return for the token bill.

Why would extra context hurt? The researchers identified two core problems. Detailed codebase overviews are largely redundant with documentation the agent can already find, and overly restrictive instructions make real tasks harder to solve. An agent drowning in rules spends its attention budget obeying constraints instead of completing work.

Token economics compound the damage. Anthropic's own best practices documentation frames the context window as "a public good" shared with the system prompt, conversation history, and every other skill's metadata — and their PDF extraction example shows how a verbose skill burns roughly 150 tokens where a concise one needs about 50. Triple the cost, for instructions that mostly restate what the agent already knows.

The practical takeaway is that always-on real estate is the scarcest resource your agent has. Everything you place there competes for attention on every single request, whether relevant or not. That means applying a hard filter to what deserves the spot:

• Architecture overviews, hard constraints, and build/test commands — the agent genuinely needs these baseline facts
• Task-specific workflows like deployment checklists or PR review procedures — these belong in skills that load only when triggered
• Long reference documentation — link to it instead of pasting it
• Information the agent can infer from the codebase itself — cut it

This is why the skills architecture exists as a separate concept rather than a subsection of your system prompt. Skills load conditionally, entering context only when the task matches their description, which is why they can afford to be detailed — up to 500 lines — without bloating every request. The layered pattern that's emerging across tools like Claude Code, Cursor, and Codex keeps baseline context under roughly 120 lines total, with deep capability available on demand.

The challenge, then, isn't deciding whether to use skills — it's knowing which instructions deserve always-on status versus on-demand loading, and among the thousands of published skills, which ones actually lift performance. That's the gap SkillzBench is being built to close: a free directory that will benchmark every skill in a sandbox with the same model, with and without the skill, publishing the Lift in percentage points so you can see exactly what each instruction package adds before it ever touches your agent's context.

If you want to follow along as the benchmarks, security scans, and free MCP connector come online, the SkillzBench waitlist is open now — everything on the platform will be free, supported by ads rather than user fees.

Two Different Jobs: Always-On Baseline vs On-Demand Expertise

Picture your AI agent as a new hire: a short orientation briefing they carry everywhere, plus a shelf of manuals they consult only when the job demands it. That's exactly how the industry now separates system prompts from agent skills — and getting the split wrong measurably hurts performance.

System prompts and lean context files like AGENTS.md and CLAUDE.md handle the always-on baseline: personality, safety constraints, hard rules the agent must never break, and build or test commands. The consensus recommendation is to keep these files under 100 lines, because context is expensive. An ETH Zurich study found that LLM-generated context files actually reduced task success rates by about 3% compared to no file at all, while human-written files improved success by only around 4% — and adding context files increased inference costs by over 20%.

Skills handle everything else: the multi-step workflows, domain expertise, and output formats that only matter for specific tasks. Cursor defines a skill as a portable, version-controlled package that teaches agents domain-specific tasks (per its official documentation), and skills can run up to 500 lines precisely because they load only when triggered.

This separation works through progressive disclosure, a three-tier loading architecture:

• Discovery: only a skill's name and description load at startup, roughly 50 tokens per skill
• Activation: the full SKILL.md body loads on demand, around 500 to 5,000 tokens
• Execution: optional reference files and scripts load lazily, only as needed

Because only metadata sits permanently in context, agents can juggle 100+ installed skills without bloating the window — the Claude platform docs call the context window "a public good" shared with the system prompt, conversation history, and every other skill's metadata.

The practical test for what earns a place in either layer comes from the agentskills.io best practices guide: ask, "Would the agent get this wrong without this instruction?" If the answer is no, cut it. Architecture overviews, naming conventions, and hard constraints pass that test for always-on files; deployment checklists and PR-review procedures belong in skills. One caution: because skills inject instructions directly into the agent's prompt as high-priority fragments, treat third-party skills as high-trust artifacts. That's why SkillzBench is building a free directory that security-scans and verifies every skill before you install it — join the waitlist to get vetted skills the day it launches.

Calibrating Control: How Specific Should Your Skill Be?

Once you've decided something belongs in a skill, a harder question follows: how tightly should you script it? Over-specify a flexible task and you strangle the agent's judgment; under-specify a fragile one and it breaks your production database. Getting this calibration right is what separates a skill that helps from one that actively hurts.

The Claude documentation offers a "degrees of freedom" framework with three levels. High-freedom skills use plain text instructions, suited to tasks with multiple valid approaches and context-dependent decisions. Medium-freedom skills use pseudocode or parameterized scripts when a preferred pattern exists but some variation is acceptable. Low-freedom skills specify exact scripts with few or no parameters, reserved for fragile, error-prone operations where consistency is critical.

The analogy from the docs makes it memorable: a narrow bridge with cliffs on both sides calls for low freedom, while an open field with no hazards invites high freedom. The agentskills.io best practices guide echoes this: for flexible tasks, explain the "why" so the agent can make context-dependent decisions; for fragile tasks, use prescriptive directives like "run exactly this sequence."

Beyond calibration, several writing habits consistently produce better skills:

• Pushy descriptions with what-and-when: the description drives skill selection from potentially 100+ candidates, and Claude Code tends to under-trigger, so descriptions should state both what the skill does and when to use it — slightly assertively.
• Coherent scope, like a function: too narrow causes overhead and conflicting instructions; too broad makes precise activation difficult. Aim for one coherent unit of work.
• Defaults over menus: when multiple approaches are valid, pick a clear default and mention alternatives only as escape hatches. Equal options without a default waste the agent's time exploring unproductive paths.

One often-overlooked high-value element is a "Gotchas" section — a list of environment-specific facts that defy reasonable assumptions. The agentskills.io guide identifies these as some of the most valuable content a skill can contain, because they capture exactly what the model cannot infer. The same guide also warns against a common pitfall: asking an LLM to generate a skill without domain context, which produces vague, generic procedures instead of the specific patterns and edge cases that make skills worth loading.

Remember that effectiveness depends on the underlying model — what works for Opus might need more detail for Haiku, per the Claude docs. And since every token competes for attention in a shared context window, apply the test to each instruction: would the agent get this wrong without it? If not, cut it.

If you'd rather test than write from scratch, SkillzBench is building a free directory of agent skills with security scanning, quality judging, and benchmarking — so you can see which skills actually lift performance before you install anything.

The Trust Problem: Skills Are Prompt Injection by Design

Every time you install a third-party skill, you're handing a stranger a pen and letting them write directly into your agent's brain. That's not a metaphor — it's the literal mechanics of how skills work, and it's the industry's most under-discussed tension.

According to security research, skills don't require a formal protocol or handshake — they're injected directly into the agent's system prompt, "the most 'prime real estate' in an AI's context." A malicious SKILL.md file gets treated as a high-priority system prompt fragment, which one analysis bluntly calls "prompt injection by design." The same convenience that makes skills portable and swappable is exactly what makes them dangerous.

The supply chain compounds the problem. Unlike npm packages or container images, the skills ecosystem currently operates without mandatory reviews, package signing, or lockfiles. Anyone can publish a skill; nothing verifies what's inside it before your agent loads it. And the attacks aren't theoretical: the ClawHavoc campaign deployed over 300 credential harvesters, and researchers have gamed marketplaces into distributing skills that steal SSH and AWS keys.

For teams adopting skills, verification has to be non-negotiable:

• Pin to a commit SHA so the skill you reviewed is the skill that runs — upstream changes can't silently swap in new instructions.
• Security-scan every version, since skills can carry instructions that exfiltrate data or override safety constraints.
• Check licenses and maintenance signals before depending on a package someone may abandon tomorrow.
• Test in a sandbox before production, so a rogue skill can't touch real credentials on its first run.

This is precisely the gap SkillzBench is being built to close. The free directory and MCP connector will pin every skill version to a commit SHA, run security scans, validate licenses, and publish a 0–100 trust score built from security, quality, license, maintenance, and community signals — so you can install skills with evidence instead of hope. The platform is in pre-launch, and everything — the directory, the MCP connector, benchmarks, and alerts — will be free.

The skills architecture is worth adopting; the trust model is what you have to build around it. Treat every skill as a high-trust artifact, verify before you load it, and join the waitlist at skillzbench.com to get verified skills the moment the platform goes live.

Your Implementation Checklist: Restructure Context in an Afternoon

Your always-on context files are likely bloating your token budget and hurting performance. An ETH Zurich study found that LLM-generated context files reduced task success rates by approximately 3%, while increasing inference costs by over 20%.

You need to audit your current setup immediately to reclaim efficiency. Start by checking your AGENTS.md and CLAUDE.md files against the recommended limit of under 100 lines. If you are exceeding this threshold, you are forcing the agent to process redundant information on every single turn.

Move workflows out of static files into dynamic skills. Task-specific instructions, such as deployment checklists or API patterns, belong in SKILL.md files that load only when relevant. This prevents the agent from wasting attention on irrelevant details during simple queries.

Apply the "wrong-without-it" test to every line in your always-on context. Ask yourself: would the agent get this wrong without this specific instruction? If the answer is no, cut it. As noted in best practices guides, every token competes for the agent's attention with everything else in the window.

When writing your skill descriptions, be slightly pushy. Agents tend to under-trigger skills rather than over-trigger them, so your description must clearly state both what the skill does and exactly when to use it. This ensures the correct capability is loaded for complex tasks.

• Audit AGENTS.md and CLAUDE.md to ensure they stay under 100 lines each.
• Extract task-specific workflows into separate SKILL.md files to enable on-demand loading.
• Remove any instruction the agent can infer from the codebase or existing documentation.
• Write pushy skill descriptions that specify the exact trigger conditions for activation.
• Source third-party skills only from verified, benchmarked directories to mitigate security risks.

Security is a critical consideration when expanding your agent's capabilities. Skills are injected directly into the system prompt, creating a vector for "prompt injection by design" if sourced from unverified channels. The current supply chain lacks mandatory reviews or package signing, making vetting essential.

SkillzBench is building a free, independent directory to solve this verification gap. We will pin every version to a commit SHA, security-scan, and benchmark skills to provide clear Lift scores. Join the waitlist to access these trust scores and test verified skills for free once live.