# Packaged Skills, Discovery, and the Configuration Ecosystem > Source: > Published: 2026-09-13 16:31:01+00:00 *In* *Part 1**, we established what skill is — the reasoning ability that separates Chef One from Chef Two. Same recipe, same ingredients, different outcome. But Chef One’s skill doesn’t stop at knowing how to cook. He also knows which recipe card to pull from the wall, where each card lives, and which ones he can trust. That’s what this part is about.* *Part 2 covers packaged skills — how they’re structured as* *SKILL.md* *files and folders, how agents discover and activate them, how the full configuration file ecosystem fits together, and how you move from “a file on my laptop” to “a skill running in a production agent.”* Before we go further, there’s a distinction that most articles on this topic never make explicit. Everything in [Part 1](https://medium.com/@avinash-g/the-chef-can-read-the-recipe-but-can-they-cook-skills-35c06722df22?sharedUserId=avinash-g) — Chain of Thought, ReAct, Task Decomposition, Tree of Thought — describes skill as a **reasoning capability**: a pattern you elicit through prompts that shapes *how* the model thinks through a problem. You don’t install this kind of skill. You engineer it into the instructions that surround the model. There is a second, increasingly important meaning: skill as a **packaged, portable unit of capability** — a file-based artifact that an agent discovers, loads, and follows. You *do* install this kind of skill. It lives in a folder. It has a name, a description, and instructions. The agent reads it the way Chef One reads a recipe card pulled down from the wall. These two things interact: the reasoning patterns from Part 1 determine *how well* the agent executes a packaged skill. A skill file can include Chain of Thought instructions — it can *tell* the agent to reason step by step. But a skill file can’t manufacture reasoning ability the underlying model doesn’t have. A poorly skilled chef given a perfect recipe card is still Chef Two. The rest of this blog covers the second meaning. Keep both definitions in mind. Here’s a concept that almost nobody covers, and it’s one of the most important insights for building reliable production agents: **A skill doesn’t have to be a wall of natural language instructions for the LLM to reason over. It can contain deterministic, code-level rules that execute without model discretion at all.** This is the core design insight behind Decagon’s Agent Operating Procedures (AOPs) — and it’s the practical resolution to one of the oldest tension points in agentic AI: LLM reasoning is flexible but unpredictable; hard-coded logic is predictable but brittle. The answer isn’t to pick one — it’s to use both, in the right places. **Kitchen analogy:** Some things in a kitchen are judgment calls — the chef decides how much spice, how long to cook. But some things are never judgment calls: if a customer’s allergy record says NO PEANUTS, that check is not a suggestion. It’s a hard rule that executes before any cooking begins, regardless of what the chef thinks. Consider this skill instruction: ``` ## Refund ProcessingIf the customer requests a refund and the order is within 30 days andthey have no previous refunds, process the refund automatically.Otherwise, escalate to a human agent. ``` Written as pure LLM instructions, this rule will be followed *most of the time*. But “most of the time” is not the bar for a financial transaction. On some percentage of runs, the model might miscount the days, fail to retrieve prior refund history correctly, or process the refund anyway because the customer was persuasive. This is the reason to execute sensitive validation steps in code rather than LLM reasoning. Treat every skill as having three distinct zones: ``` ZONE 1: DETERMINISTIC GATES (code — not LLM) Hard rules that must execute before any LLM reasoning begins. If-then logic. Validation checks. Permission gates. These CANNOT be overridden by model reasoning or user persuasion.ZONE 2: LLM REASONING (model) Flexible interpretation, judgment, natural language understanding. Applied only within the boundaries set by Zone 1.ZONE 3: DETERMINISTIC OUTPUTS (code — not LLM) Structured result verification. Schema validation. Tool call enforcement. Audit logging. ``` *Kitchen:* Zone 1 is the allergy check at the door — no order enters the kitchen without passing it. Zone 2 is the chef’s judgment on technique and presentation. Zone 3 is the expeditor verifying the dish against the ticket before it leaves the pass. ``` ---name: refund-processordescription: Process customer refund requests. Use when a customer explicitly requests a refund for a specific order number.---# Refund Processing Skill## DETERMINISTIC GATES — Execute First, No ExceptionsBefore any other step, run these checks in code:1. `validate_refund_eligibility(order_id, customer_id)` Returns: ELIGIBLE | INELIGIBLE | ESCALATE If INELIGIBLE or ESCALATE: stop immediately, do not proceed.2. `check_fraud_signals(customer_id, order_id)` Returns: CLEAR | REVIEW_REQUIRED If REVIEW_REQUIRED: stop, escalate to fraud team.These two checks are not suggestions. They run before anyconversation with the customer about the refund outcome.## LLM REASONING — Apply Only After Gates PassOnce both gates return positive results, use judgment to:- Explain the refund timeline in a tone matching the customer's- Address additional questions about the process- Decide whether to proactively offer account credit as alternative## DETERMINISTIC OUTPUTS — Enforce Before CompletingAfter LLM reasoning, before closing:- Call `log_refund_action(order_id, action_taken, agent_id)`- Call `send_refund_confirmation(customer_id, amount, timeline)`- Verify both returned SUCCESS before telling customer "done" ``` The LLM never decides whether the refund is eligible. Code does that. The LLM decides *how to talk about it* — the part that genuinely benefits from flexible reasoning. **The practical rule:** any decision where being wrong has a concrete, measurable cost — financial, safety, compliance — belongs in a deterministic zone. Any decision where the value comes from flexible interpretation of ambiguous human input belongs in the LLM zone. A 2026 empirical study of 238 real-world [***SKILL.md***](http://skill.md) files found over 99% contain at least one “skill smell” — a structural deficiency that rarely self-corrects once introduced: These smells “rarely disappear as skills evolve” once introduced — which makes getting the structure right at authoring time significantly more valuable than iterating later. A skill is a folder, not just a file. Here’s the complete structure: ``` my-skill/├── SKILL.md ← Required: metadata + instructions├── scripts/ ← Optional: deterministic code│ ├── validate.py ← Deterministic gate logic│ └── format.py ← Output validation├── references/ ← Optional: loaded ON DEMAND only│ ├── full-policy.md│ └── edge-cases.md└── assets/ ← Optional: templates, data files └── output-template.json ``` **Kitchen analogy:** The [SKILL.md](http://skill.md/) is the laminated recipe card. scripts/ is the set of tools that run automatically (the timer that beeps at exactly 90 seconds). references/ is the thick binder kept under the counter — only opened for unusual orders. assets/ is the mise en place station. ``` ---# REQUIREDname: refund-processor # Lowercase, hyphens, max 64 chars # Must match the parent folder name exactly # No angle brackets — they inject instructionsdescription: | # Max 1,024 chars. Must state BOTH: Process customer refund # (1) what the skill does requests. Use when a # (2) when to use it — this IS the trigger customer explicitly asks # Front-load action verbs and domain keywords for a refund on a specific # Not documentation — the activation condition order number.# OPTIONALlicense: Apache-2.0metadata: author: platform-team version: "2.1.0" sensitivity: highallowed-tools: # Restrict which tools this skill can invoke - Bash(python scripts/validate.py *) - Read(./references/*)compatibility: agents: [claude, codex-cli, cursor]--- ``` **Critical rules:** ``` # [Skill Name]## When to Use This Skill[Specific — what SHOULD activate this? What looks similar but SHOULD NOT?]## Prerequisites[What must be true before this skill runs?]## DETERMINISTIC GATES [if applicable][Hard rules. Exact tool calls. Not negotiable.]## Step-by-Step Procedure[Numbered steps. Imperative verbs. Verification steps between major actions.]## Output Format[Exactly what the final output looks like.]## Edge Cases[Brief — deep detail goes in references/]## What This Skill Does NOT Do[Explicit scope exclusions — prevents scope creep]--- # scripts/validate_refund.py# Called by: refund-processor skill — DETERMINISTIC GATE step 1import sys, jsonfrom datetime import datetimedef validate_refund(order_id: str, customer_id: str) -> dict: order = fetch_order(order_id) # deterministic DB call order_age = (datetime.now() - order.created_at).days if order_age > 30: return {"status": "INELIGIBLE", "reason": "outside_window"} prior_refunds = count_customer_refunds(customer_id) if prior_refunds > 0: return {"status": "ESCALATE", "reason": "prior_refund_exists"} return {"status": "ELIGIBLE", "order_id": order_id}if __name__ == "__main__": print(json.dumps(validate_refund(sys.argv[1], sys.argv[2]))) ``` Key principles: one script one purpose; always return structured JSON; include the calling skill’s name in comments (audit trail); scripts should be idempotent where possible. ``` # In SKILL.md body:## Edge CasesFor standard refund requests, follow the steps above.For complex cases (partial orders, subscriptions, gifts, international),read: references/complex-refund-cases.mdOnly load this file for those specific scenarios. ``` This keeps the main skill under 5,000 tokens when activated while giving access to deep domain knowledge only when a rare case actually arises. ``` LEVEL 1: SELECTABLE (~50-100 tokens per skill — always in context) name + description only Purpose: activation matchingLEVEL 2: ACTIVE (<5,000 tokens — loaded on task match) Full SKILL.md body + frontmatter Purpose: procedural guidanceLEVEL 3: REFERENCE (varies — loaded one file at a time, on demand) Individual files from references/ Purpose: deep detail for specific sub-tasks ``` **The context tax:** each skill at Level 1 costs ~50–100 tokens just to be selectable. Design descriptions to earn that tax — a vague description wastes it without delivering the benefit. Since the [SKILL.md](http://skill.md/) standard emerged, a full ecosystem of agent configuration files has grown around it. Confusing which to use for what is now one of the most common practical mistakes. Here’s the complete picture: ``` your-project/├── AGENTS.md ← Always-on, cross-tool project context├── CLAUDE.md ← Always-on, Claude-specific preferences├── .claude/│ ├── skills/ ← On-demand skills (Claude Code)│ │ └── refund-processor/SKILL.md│ └── commands/ ← Slash commands (/standup, /deploy)├── .agents/│ └── skills/ ← Shared skills (Codex, VS Code, OpenCode)└── ~/.claude/ └── skills/ ← Personal skills, follow you everywhere ``` **Kitchen analogy:** [AGENTS.md](http://agents.md/) is the kitchen’s standing policy manual — always on the counter, every chef reads it every service. [CLAUDE.md](http://claude.md/) is a specific chef’s personal notebook of preferences — always with them. [SKILL.md](http://skill.md/) is the laminated recipe card on the wall — only pulled down when a matching order comes in. **AGENTS.md** **— The Universal Project Brief** Always loaded. Works across Claude Code, Codex CLI, GitHub Copilot, Cursor, and most other major agents. What belongs here: project architecture, build/test/lint/deploy commands, code conventions, team conventions that apply regardless of which AI tool is helping. What does NOT belong here: task-specific workflows, step-by-step procedures — those are [SKILL.md](http://skill.md/). **CLAUDE.md** **— Claude-Specific Preferences** Always loaded by Claude Code. If you also use Cursor or Codex, put shared rules in [AGENTS.md](http://agents.md/) and import it: . **SKILL.md** **— On-Demand Task Expertise** Loaded only when a task matches the description. The only file in this list that follows progressive disclosure — costs near-zero tokens until triggered. **The practical rule:** if you want something active for every interaction, it belongs in [AGENTS.md](http://agents.md/) or [CLAUDE.md](http://claude.md/). If you want something available but not always paying context cost, it belongs in [SKILL.md](http://skill.md/). The [SKILL.md](http://skill.md/) open standard, originally developed by Anthropic and released openly in late 2025, has since been adopted at a pace rare for any technical standard. The ecosystem grew 18.5× in just 20 days — from 2,179 skills on January 16 to over 40,000 by February 5. Claude Code, OpenAI’s Codex CLI, Gemini CLI, GitHub Copilot, Cursor, VS Code, and over 20 other platforms now support the same format. Each skill’s metadata costs ~50–100 tokens at all times. At scale: **Partitioning strategies for large registries:** **Practical rule:** keep any single session’s active skill metadata under 5,000 tokens. The 6-step mechanical sequence: ``` 1. SCAN — Agent scans every configured skills directory2. LOAD METADATA — Reads ONLY name + description from every SKILL.md3. WAIT — Metadata sits in context (~50-100 tokens per skill)4. MATCH — When a prompt arrives, compare it semantically against descriptions5. ACTIVATE — If a skill's description matches, full instructions load6. EXECUTE — Agent follows instructions, optionally running scripts/references ``` **The description field is the single most important text in the entire skill.** It is not documentation — it is the trigger condition. A vague description under-triggers or over-triggers unpredictably. A precise description front-loads the exact keywords and scope a real task would contain. **Implicit** — the agent decides a skill matches the current task based on description matching. The user never has to know skills exist. **Explicit** — the user types /skill-name, or an orchestration layer specifies exactly which skill to load. No matching ambiguity. Skills live in two kinds of locations — personal and project. Three fundamentally different ways a skill can reach an agent: Most production systems layer all three — safety-critical skills bundled, team skills dynamic-local, specialist capabilities remote-fetched. Six distinct patterns for how a skill gets loaded at the moment it’s needed: You now know how packaged skills are built, structured, discovered, and deployed. You’ve seen the three-zone hybrid architecture, the [SKILL.md](http://skill.md/) anatomy, the configuration file ecosystem, and the six runtime fetching patterns. Part 3 goes where things get harder: what happens when skills collide, fail silently, or get compromised. How do you manage a registry at scale? What does the OWASP Agentic Skills Top 10 say? What happened in the ClawHavoc supply chain incident? And how does Microsoft’s SkillOpt change the way we think about skill authoring entirely? **Next → Blog 3C: When the Kitchen Gets Complicated — Duplicates, Failures, Security, and SkillOpt** *Also in this series:**←* *Blog 3A**: The Chef Can Read the Recipe. But Can They Cook?* [Packaged Skills, Discovery, and the Configuration Ecosystem](https://pub.towardsai.net/packaged-skills-discovery-and-the-configuration-ecosystem-a5b2d3ac7ea1) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.