{"slug": "the-skill-bloat-dilemma-why-your-coding-agent-can-t-handle-400-skills", "title": "The Skill Bloat Dilemma: Why Your Coding Agent Can't Handle 400 Skills", "summary": "An audit of a local agent skill library found 465 skill bundles totaling 3,188 files and 21 megabytes of Markdown, scripts and JSON schemas, which pushed a fresh agent session's system prompt to 57,620 tokens before any user prompt was entered. The author reports that several major coding harnesses, including Google Antigravity, Gemini CLI, Claude Code and OpenCode, cap advertised skills at a hardcoded, unconfigurable 50 and sort them alphabetically by folder name, so skills ranked 51 through 465 are dropped; in a 108-trial benchmark across twelve engineering tasks, that default discovery produced a 66.7 percent failure rate. Pinning three or four skills in a project-level `.agents/skills.json` cut the baseline catalog from 57,000 tokens to roughly 500 tokens.", "body_md": "A few weeks ago, I ran an audit on my local development environment.\nLike many engineers leaning heavily into autonomous AI workflows, I had\ngradually adopted the open convention of storing reusable procedural\ninstructions in `~/.agents/skills/`.\n\nWhenever a teammate wrote a great workflow script, or someone published a meticulous playbook for Cloudflare edge optimizations, or a community pack for Go concurrency appeared, it went into the vault. It felt like the responsible thing to do: build a permanent, compoundable library of operational knowledge that any agent could draw upon.\n\nThen I counted the directory.\n\nThere were 465 distinct skill bundles, comprising 3,188 individual files and 21 megabytes of Markdown manuals, shell scripts, and JSON schemas.\n\nI opened a fresh terminal window, initialized an agent session in a clean repository, and looked at the token counter before typing a single prompt.\n\nThe system prompt was already hovering at **57,620 tokens**.\n\nBefore I had even asked the agent to inspect a file, it had consumed more context than the entire source code of the project we were about to touch. Every conversational turn, every clarification, and every tool call was quietly dragging that massive fifty-seven-thousand-token anchor through the API. Over a modest twenty-turn session, more than one million input tokens were vanishing into thin air just to advertise capabilities we never once touched.\n\nWe had built a library so comprehensive that it was choking the very systems meant to read it.\n\n## The Silent 50-Skill Cutoff Trap\n\nMy first instinct was to check how different harnesses handled this volume. Surely modern tools like Google Antigravity, Gemini CLI, Claude Code, or OpenCode had engineered an intelligent filtering mechanism for large vaults?\n\nWhat I discovered under the hood was far more concerning than simple token inflation.\n\nTo prevent prompt catastrophic bloat, several major harnesses implement a\nhardcoded, unconfigurable ceiling: **they only advertise the first fifty\ndiscovered skills to the model**.\n\nAt first glance, fifty sounds like a generous number. But how does an agent engine select which fifty skills to keep when your vault contains 465?\n\nIt sorts them alphabetically by folder name.\n\nConsider the mechanical reality of that choice:\n\n1. In a 465-skill library, skills 51 through 465 (roughly 89 percent of your capabilities) are silently dropped before the prompt is ever assembled.\n2. If you are working on a backend Go service, but your Go skills are named\nwith the convention `golang-cli` ,`golang-testing` , and`golang-database` , their alphabetical rank puts them somewhere around\nindex 140.\n3. As a result, your Go coding agent is given zero Go skills. Instead, it is handed fifty tools for accessibility audits, Docker scaffolding, and developer relations playbooks, simply because the letters A through D consumed the entire quota.\n\nTo verify this empirically, we constructed a controlled benchmark across twelve realistic engineering tasks, ranging from standard flag parsing to rare edge audits, evaluated over 108 trials.\n\nUnder default unmanaged discovery, the agent suffered an immediate\n**66.7 percent failure rate**.\n\nThe failure was not caused by model reasoning deficits or bad code. The model failed because the exact procedural guidance it needed had been amputated by an alphabetical sorting rule.\n\n## The Fragility of Static Manual Pinning\n\nThe obvious engineering workaround is to configure each project manually.\nYou create a local configuration file in your repository, say\n`.agents/skills.json`, and explicitly pin the three or four skills that\nmatter for that specific codebase.\n\n```\n{\n  \"skills\": {\n    \"include\": [\n      \"golang-cli\",\n      \"golang-testing\",\n      \"golang-database\",\n      \"golang-error-handling\"\n    ]\n  }\n}\n```\n\nThis immediately fixes the prompt bloat. The baseline catalog drops from 57,000 tokens down to roughly 500 tokens. Your agent launches instantly, remains razor-focused on Go patterns, and your token invoices plunge.\n\nFor about forty-eight hours, you feel like you have solved the problem.\n\nThen reality intervenes.\n\nSoftware engineering rarely respects clean repository boundaries. You are deep in the core Go CLI, and an urgent incident emerges: an edge worker is exhausting its CPU time limits, or an SQLite migration script needs to coordinate with a remote edge database, or you need to draft an API announcement.\n\nYou prompt the agent to audit the issue. But because the project configuration strictly pinned only Go tools, the agent is totally blind to your edge worker skills.\n\nIn our 108-trial benchmark, static manual configuration scored a **complete\nzero percent pass rate on off-stack and mixed tasks**.\n\nWorse, maintaining static JSON manifests across dozens of repositories introduces an exhausting maintenance tax. Every time a skill updates, or a new teammate joins, someone has to manually curate, edit, and debug JSON files across every project tree.\n\n## The Skill Governance Trilemma\n\nWe found ourselves trapped in a three-way architectural tension:\n\n```\n                  Context Economy\n               (Minimal Tokens / Turn)\n                       /\\\n                      /  \\\n                     /    \\\n                    /      \\\n  Universal Capability ---- Zero Maintenance\n (Access to 400+ Tools)    (No Fragile Syncing)\n```\n\n1. **Default Global Discovery** gives you Universal Capability, but\ndestroys Context Economy (57k tokens) and fails catastrophically via the\nsilent 50-skill cutoff.\n2. **Native Manual Pinning** gives you Context Economy (500 tokens), but\ndestroys Universal Capability (zero access to off-stack tools) and creates\nhigh maintenance overhead.\n3. **Crude Ad-Hoc Scripts** risk multi-agent file collisions, lost updates,\nand untracked configuration drift.\n\nTo solve this, we had to rethink procedural memory from first principles. How does an operating system manage large programs with limited physical RAM? It does not load every shared library into physical memory at boot. It establishes a working set in L1 cache, and pages in remaining routines on demand.\n\nWe needed a **Hybrid Skill Governor**.\n\n## The Architectural Solution: Hybrid Governance\n\nThe design rests on three foundational pillars: **grounded local catalogs**,\n**just-in-time retrieval**, and **kernel-grade atomic safety**.\n\n```\n+-------------------------------------------------------------+\n| Host Global Vault: ~/.agents/skills/ (465 skills immutable) |\n+-------------------------------------------------------------+\n       |                                              |\n       v [Read-Only Inspection]                       v [Dynamic JIT]\n+-------------------------------+              +--------------------+\n| Workspace: .agents/skills.json|              | Sila MCP Server    |\n| (3-4 Grounded Domain Skills)  |              | 2 Tools: 230 tok   |\n+-------------------------------+              +--------------------+\n       |                                              |\n       v [Active in Turn 1]                           v [On-Demand Only]\n+-------------------------------------------------------------------+\n|                     Model Context Window                          |\n|  Base Prompt: 730 tokens (vs 57,620)  |  Fetch: Paid if invoked   |\n+-------------------------------------------------------------------+\n```\n\n### 1. Grounded Local Catalogs\n\nInstead of manually guessing which skills belong in a project, a read-only\nassessment engine inspects the repository manifests (`go.mod`,\n`package.json`, `wrangler.jsonc`, `Cargo.toml`) and active task goals.\n\nIt automatically pins the 3 or 4 highest-confidence domain skills directly\ninto `.agents/skills.json`. This reduces the baseline prompt overhead to\nbetween 151 and 500 tokens on Turn 1, completely bypassing the native\n50-skill cutoff.\n\n### 2. The Just-In-Time MCP Bridge\n\nTo eliminate the off-stack blindspot, we expose two lightweight, read-only Model Context Protocol (MCP) tools:\n\n- `skill_search` : Allows the agent to query the entire 465-skill catalog by\nkeyword or tag in under 2.5 milliseconds.\n- `skill_load` : Retrieves full instructions and bundled reference resources\ndynamically into the conversational turn in under 300 microseconds.\n\nCrucially, the tool declarations consume a fixed footprint of just **230\ntokens**. The agent can reach any specialized tool in the global vault, but\nwe pay the payload cost *strictly on the turns when that tool is actually\ncalled*.\n\n### 3. POSIX Advisory Locking and Cryptographic Envelopes\n\nIn real agent environments, multiple background workers often run concurrently. If two agents attempt to adjust configuration simultaneously, uncoordinated file writes cause silent data loss.\n\nWe wrapped all harness writes in a two-tier protection model:\n\n- **Kernel-level POSIX `flock`** : Enforces strict mutual exclusion at the\nOS level. If a process holding a lock is terminated with`SIGKILL` , the\noperating system kernel automatically releases the file descriptor in\n0.23 milliseconds, making deadlocks mathematically impossible.\n- **Cryptographic SHA-256 Envelopes (`_sila`)** : Every managed file records\na digest of its contents. If a human developer edits the file manually,\nthe governor detects the hash mismatch, fails closed, and outputs a\nstructured unified diff showing exactly which keys diverged.\n\n## The Four-Part Cost Accounting Model\n\nTo measure the financial and attentional reality of this architecture, we formalized the total context cost across any conversational turn $t$:\n\n$$C_{\\text{turn}}(t) = C_{\\text{meta}}(t) + C_{\\text{bridge}}(t) + C_{\\text{fetch}}(t) + C_{\\text{retained}}(t)$$\n\nWhere:\n\n- $C_{\\text{meta}}(t)$ is the catalog metadata for pinned workspace skills (151 to 500 tokens).\n- $C_{\\text{bridge}}(t)$ is the fixed 230-token declaration for the two MCP tools.\n- $C_{\\text{fetch}}(t)$ is the dynamic token payload delivered when a rare skill is loaded.\n- $C_{\\text{retained}}(t)$ represents instructions kept in conversation history across subsequent turns.\n\nWe mapped the amortization curves across both standard skills (2,700 tokens) and heavy multi-file bundles (5,300 tokens):\n\n| Conversational Turn | Unmanaged Global Vault | Native Truncated Cutoff | Hybrid Governor (Standard Skill) | \n|---|---|---|---|\n| **Turn 1 (Session Start)** | 57,620 tokens | 5,775 tokens | **730 tokens** | \n| **Turn 2 (Rare Skill Invoked)** | 57,620 tokens | 5,775 tokens | **3,455 tokens** | \n| **Turn 3 (Task Execution)** | 57,620 tokens | 5,775 tokens | **3,455 tokens** | \n| **Turn 4 (Verification & Test)** | 57,620 tokens | 5,775 tokens | **3,455 tokens** | \n| **Turn 5 (Commit & Handoff)** | 57,620 tokens | 5,775 tokens | **3,455 tokens** | \n| **5-Turn Cumulative Total** | **288,100 tokens** | **28,875 tokens** | **14,550 tokens** | \n\nFor ordinary tasks, the savings are instantaneous: you save **4,757 tokens\non every single turn** compared to the 50-cutoff limit, and over 56,000\ntokens compared to the unconstrained vault.\n\nEven when fetching a massive 5,300-token bundle on Turn 2, the hybrid model remains significantly cheaper than default discovery through Turn 8. And unlike the truncated baseline, the hybrid model actually completes the task:\n\n```\nOverall Benchmark Accuracy (108 Controlled Trials):\n  Default Global Discovery:    [████░░░░░░░░] 33.3% pass\n  Native Manual Pinning:       [██████░░░░░░] 50.0% pass\n  Sila Hybrid Governor:        [████████████] 100.0% pass\n```\n\n## When to Use What: A Pragmatic Mental Model\n\nNot every codebase requires a full governance engine. As engineers, we must avoid replacing one form of unnecessary complexity with another.\n\nHere is the operational rule of thumb we adopted:\n\n### 1. When Native Manual Pinning is Best\n\nIf you are working on a small, focused repository with a single programming\nlanguage, and your team relies on the same three or four static skills,\n**just write `.agents/skills.json` by hand**.\n\nYou do not need an MCP server or dynamic retrieval. Avoiding the MCP bridge saves you 230 tokens per turn, and your team avoids introducing any new tooling dependencies. Keep it simple.\n\n### 2. When Hybrid Governance is Mandatory\n\nYou need hybrid governance when:\n\n- Your local vault exceeds fifty skills, and you are losing capabilities to alphabetical truncation.\n- You maintain polyglot monorepos (e.g. Go backend, TypeScript edge worker, Python data scripts) where different directories require completely different active skills.\n- Your workflows regularly encounter unforeseen, off-stack tasks that cannot be anticipated in advance.\n- You run concurrent multi-agent swarms where uncoordinated file writes risk clobbering workspace configuration.\n\n## Lessons from the Swarm\n\nBuilding and verifying this system across three sequential goals taught us a great deal about the emerging craft of multi-agent engineering.\n\nOver the course of the project, more than forty autonomous subagents collaborated across three sequential goals: an initial implementation team, an empirical assessment panel, and a production hardening crew.\n\nThe most reassuring moment occurred during the hardening phase. An adversarial\nchallenger subagent was stress-testing flag combinations and identified an\nobscure edge case: passing `--force --interactive` simultaneously caused a\nsubshell prompt bypass.\n\nRather than sweeping the issue aside, the gate **failed closed**. The\norchestrator halted forward progress, spawned a targeted remediation team,\nrestructured the flag precedence so that interactive prompts always take\npriority, and verified the fix with unit regression tests before any release\ncandidate was authorized.\n\nWhen you give agents clear boundaries, verifiable contracts, and independent auditors who are incentivized to find flaws rather than rubber-stamp success, they build remarkably resilient software.\n\n## Conclusion\n\nAgent skills are one of the most promising primitives in modern software development. They allow us to capture hard-won operational wisdom in plain text and hand it directly to our tools.\n\nBut like any powerful abstraction, they cannot be scaled naively. Dumping hundreds of markdown files into a global folder and expecting a language model to sift through them on every turn is the agent equivalent of disabling virtual memory and running out of stack space.\n\nBy treating skills as a tiered memory hierarchy: keeping the working set compact in L1 prompt cache, and paging in specialized tools via just-in-time retrieval, we can preserve universal capability without paying for it on every breath.\n\nThe code is pure Go. The binaries are standalone. The global library remains untouched. And the terminal is quiet again.\n\nRecommended\n\n## Continue reading\n\nSelected from shared topics, related tags, and the recent archive.", "url": "https://wpnews.pro/news/the-skill-bloat-dilemma-why-your-coding-agent-can-t-handle-400-skills", "canonical_source": "https://jadmadi.net/posts/the-skill-bloat-dilemma/", "published_at": "2026-11-09 10:20:27.650150+00:00", "updated_at": "2026-11-09 10:20:30.515363+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "large-language-models"], "entities": ["Google Antigravity", "Gemini CLI", "Claude Code", "OpenCode", "Go"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/the-skill-bloat-dilemma-why-your-coding-agent-can-t-handle-400-skills", "markdown": "https://wpnews.pro/news/the-skill-bloat-dilemma-why-your-coding-agent-can-t-handle-400-skills.md", "text": "https://wpnews.pro/news/the-skill-bloat-dilemma-why-your-coding-agent-can-t-handle-400-skills.txt", "jsonld": "https://wpnews.pro/news/the-skill-bloat-dilemma-why-your-coding-agent-can-t-handle-400-skills.jsonld"}}