{"slug": "the-skills-file-pattern", "title": "The Skills File Pattern", "summary": "SectorFlow Engineering developed a skills file pattern to manage Claude Code context efficiently. Instead of appending all rules to a single CLAUDE.md file, they split context into separate files under .claude/ by purpose, importing only what each task needs. This reduces token usage and prevents contradictory rules from accumulating.", "body_md": "**SectorFlow Engineering Series** · Part 2 of 3 · Read Part 1 first: [Token Efficiency in Claude Code](https://dev.to/kavyarani7/token-efficiency-in-claude-code-2kpi)\n\n*How we stopped appending to CLAUDE.md and started importing only what we need.*\n\nJune 2026 · SectorFlow Engineering\n\nIn this seriesPart 1:[Token Efficiency in Claude Code](start here).[Part 3: Picking Models and Tools]— the MCPs we tried, refused, and why.\n\nIf you use Claude Code for a while you'll probably land where we did: a `CLAUDE.md`\n\nthat got too big and too self-contradictory to trust.\n\nIt starts fine. You write down the basics — what the app does, where the server lives, what the API looks like. Then something breaks. Claude picks the wrong model string, or makes a chart without the right color, or ignores a cache rule you mentioned in passing three weeks ago. So you write the rule down and append it. Reasonable.\n\nAnd it works for a while. Then the file's big, the week-two rules are sitting on top of the week-six rules, and when two of them disagree — they will, because requirements move and old notes go stale — the model either reconciles them into mush or just picks one. You spend an hour debugging output before you realize the rule you thought was active got overridden by something you wrote months ago and forgot about.\n\nThe bigger issue: the whole file loads every session, no matter what you're doing. A color fix on the frontend doesn't need the deployment runbook. An API route change doesn't need the chart color rules. Every line that isn't relevant is costing tokens and adding noise.\n\nWe thought about how to fix this without just deleting the stuff we'd need again later, and ended up with what we call the skills file pattern. Split the context into separate files by purpose, import only what the task needs.\n\n`CLAUDE.md`\n\nstops being the rulebook and becomes a table of contents. The actual rules move into separate files under `.claude/`\n\n.\n\n| File | What it owns | When it loads |\n|---|---|---|\n`core.md` |\nAbsolute constraints: model strings, API key rules, cache TTLs, data contracts | Every session — the foundational constraints |\n`design.md` |\nColor tokens, chart types, component patterns, loading-state conventions | UI and frontend tasks only |\n`infrastructure.md` |\nHosting config, environment variables, deployment rules, automator wiring | Infrastructure and CI tasks |\n`workflow.md` |\nTicket format, commit rules, token rules, division of labor | Every coding session |\n`architecture.md` |\nADRs, scaling thresholds, rejected technical decisions | Architecture reviews and new integrations |\n\nThe import syntax in `CLAUDE.md`\n\nis nothing special:\n\n```\n@sector-dashboard/.claude/core.md\n@sector-dashboard/.claude/design.md\n@sector-dashboard/.claude/workflow.md\n(infrastructure.md and architecture.md load only when the task references them)\n```\n\nSo a UI task loads core + design + workflow. An infra task loads core + infrastructure + workflow. `architecture.md`\n\nonly shows up if someone actually asks about a scaling decision or an ADR. The context stays small and stays on topic.\n\n`core.md`\n\nis the one file that loads every single session, so everything in it has to be true and currently enforced. We treat it like a constitution. Stable, authoritative, never wishful.\n\nTwo kinds of things go in:\n\nDon't put aspirations in core.md. \"We should try to…\" or \"ideally the model would…\" — that's workflow.md material. core.md is only for things that are true right now. The moment you put a hope in there, reality eventually contradicts it and now you've got a lie sitting in your most-trusted file.\n\nEvery hex value, every chart-type assignment, every loading-state pattern goes in `design.md`\n\n. Three reasons it pays off:\n\n`design.md`\n\n. No component files had to change just to record the rule.`design.md`\n\nis also where we list what not to touch. `TradingViewChart.jsx`\n\nis wrapper-only. `signals.js`\n\nhas its own color system and must not get the new `--sf-`\n\nvariables. Those \"don't\" rules matter as much as the conventions do.\n\nThis is the file that matters most day to day. It spells out what Claude does and what the engineer does, in enough detail that there's no room to wonder. Part 1 has the full reasoning, but the short version is: if the engineer can do it in under two minutes in a terminal, it shouldn't go to Claude through an MCP.\n\n`workflow.md`\n\nalso holds the task format we make engineers use when they hand work to Claude:\n\n| Required field | Why it exists |\n|---|---|\n`Branch: {name}` |\nStops Claude asking or guessing — one less tool call |\n`Files to CREATE: [list]` |\nScopes creation, stops new files getting added speculatively |\n`Files to MODIFY: [list + one-liner]` |\nKeeps Claude from reading unrelated files for context |\n`What to build: [criteria]` |\nThe single source of truth for when it's done |\n`Do NOT read: [not listed]` |\nAn explicit boundary — absence isn't permission |\n\nIf any of those fields is missing, Claude asks before it touches a file. That kills the usual failure mode where it reads three or four files \"to understand the codebase\" before writing a single line.\n\nArchitecture decisions go in as ADRs — the decision, what led to it, what it costs us. We record the rejected ones too, and those turn out to be the more useful part.\n\nWhen some future session asks \"why not GraphQL?\" or \"should we add WebSockets for live data?\", the answer is already sitting there: considered, rejected, here's why. Claude doesn't reopen it and neither do we.\n\nOne rule keeps the split files from turning into the same contradictory mess as the old monolith:\n\nOne file owns one domain. If a rule could live in two files, it goes in the more constrained one — usually core.md. And if you can't tell which file a rule belongs in, it's probably too vague to be a rule.\n\nIn practice: color tokens go in `design.md`\n\n, not `core.md`\n\n. Cache TTLs go in `core.md`\n\n, not `architecture.md`\n\n. Division of labor is `workflow.md`\n\n, not `core.md`\n\n. Once the domains are clear the contradictions jump out — if the same thing shows up in two files, one of them is wrong.\n\n`design.md`\n\nand nothing else.It's not a complicated setup. Six files and a manifest. The work is in holding the one-domain line: the moment a file starts feeling like it's about two things, split it.", "url": "https://wpnews.pro/news/the-skills-file-pattern", "canonical_source": "https://dev.to/kavyarani7/the-skills-file-pattern-2oam", "published_at": "2026-06-16 04:33:48+00:00", "updated_at": "2026-06-16 04:47:03.985065+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-tools"], "entities": ["SectorFlow", "Claude Code", "CLAUDE.md"], "alternates": {"html": "https://wpnews.pro/news/the-skills-file-pattern", "markdown": "https://wpnews.pro/news/the-skills-file-pattern.md", "text": "https://wpnews.pro/news/the-skills-file-pattern.txt", "jsonld": "https://wpnews.pro/news/the-skills-file-pattern.jsonld"}}