---
title: "Proposal: Packing Light for Agents"
description: "Why agent skill registries need single-file slugs, version-pinned dependencies, and explicit anti-patterns alongside multi-asset directories."
pubDate: 2026-08-31
author: "Anaiya"
heroImage: "/images/blog/agent_skill_chips.jpg"
image: "/images/blog/agent_skill_chips.jpg"
tags: ["agent-skills", "skillchips", "architecture", "tooling", "open-source"]
audio: "/audio/2026-08-31-packing-light-for-agents.mp3"

---

> *"Do not carry a three-legged stool when you only need a walking stick."*
>
> *Caribbean Workshop Maxim*

Wuh gine on! Anaiya here. 👋🏾

If you have ever packed a bag for a quick day trip up to the hills in St. Andrew, you know the cardinal rule of travelling light: you do not bring fifty separate cardboard boxes to carry fifty individual pocket tools. You put them in one clean roll-up pouch, where you can see every blade at a glance.

Back in mid-2025, when we first architected our internal "Skillchips" framework in the Moonglade laboratory, everything was designed as a single, portable unit. We wanted an agent to look up a procedural skill, load its heuristics, and run with zero administrative friction. 

Shortly after, the industry took a monumental step forward when Anthropic formalized the directory-based `SKILL.md` format. That architecture introduced critical engineering rigor that early experiments lacked:

1. **Multi-Asset Bundling:** The ability to co-locate executable helper scripts (`scripts/`), isolated test fixtures, and reference documentation (`references/`) right beside the instruction set.
2. **Progressive Schema Disclosure:** Frontmatter metadata that lets orchestrators discover available capabilities at minimal token cost before deciding to ingest the full procedural payload.
3. **Execution Isolation:** A formal boundary ensuring complex, tool-heavy workflows have their own workspace footprint without polluting global prompts.

The Anthropic skills format proved beyond doubt that modular tool design was the future of agent engineering. But as our studio registry expanded past fifty specialized capabilities, we ran into a practical nuance of scale: **in our internal studio registry snapshot (September 2026), over 80% (42 of 50) of skills bundle zero external scripts or binary assets.** They are pure procedural domain knowledge and prompt contracts.

Today, we are proposing an additive evolution to the Agent Skills standard: **Single-File Skills (`<name>.skill.md`)**, paired with two structural invariants modern agent systems benefit from.

---

### The Proliferation Problem: When `ls` Stops Working

When you audit a real-world registry of 20 or 50 skills, a striking pattern emerges: most skills do not need subdirectories, binary attachments, or test harnesses.

Yet under a strict directory-only layout, your workspace explodes:

```text
skills/
├── bajan-dialect/
│   └── SKILL.md
├── caribbean-fashion/
│   └── SKILL.md
├── posing-guidance/
│   └── SKILL.md
└── unit-converter/
    └── SKILL.md
```

You end up with dozens of directories containing identically named files. `ls` is no longer a clean index; searching requires recursive directory walks; and expressing side-by-side versions (e.g. testing `v1` against `v2` in the same repo) is awkward without folder renaming.

For skills that bundle helper scripts or datasets, directories make total sense. But for the vast majority that do not, a single slug-named file is far cleaner:

```text
skills/
├── bajan-dialect.skill.md
├── caribbean-fashion.skill.md
├── posing-guidance.skill.md
└── unit-converter.skill.md
```

`ls` becomes your index again. Zero filesystem bloat.

---

### The Two Invariants Current Standards Miss

Beyond file layout, running autonomous multi-agent systems in production highlighted two structural gaps in current skill conventions:

#### 1. Version-Pinned Dependencies (`requires`)
While the open Agent Skills specification provides a general `compatibility` string and arbitrary metadata fields, it lacks an enforced, version-pinned dependency resolver. If a spatial skill relies on a specific engine release, loading it into an untested runtime can cause silent failure.

In our proposed single-file format, dependencies are declared explicitly in the frontmatter:

```yaml
requires:
  - "phoenix-core>=20.0"
  - "pgva>=12.1"
```

If the environment does not satisfy the contract, the loader fails loudly before executing flawed workflows.

#### 2. Explicit Anti-Patterns (`when_not`)
Current agent frameworks determine whether to trigger a skill by having an LLM match the user prompt against a single semantic `description` string.

In practice, this causes constant false-positive misfires. A posing guidance skill might trigger during a fast-action sports prompt and force an awkward Greek contrapposto onto a sprinting runner.

We solved this by requiring explicit negative boundary conditions:

```yaml
when_not:
  - "Do not apply standing contrapposto to high-speed kinetic action frames (e.g. sprinting, martial arts strikes)."
  - "Do not force 3/4 profiles on regulatory biometric headshot prompts."
  - "Do not inject limb separation air gaps for extreme macro close-ups."
```

By teaching the agent *when NOT to use a tool*, you eliminate misfires without ballooning prompt length.

---

### The Hybrid Architecture: Prose for Models, JSON for CI

A great skill format must serve two masters:
1. **The LLM and Human Engineer:** Requires rich, expressive Markdown explanations, visual analogies, and clear procedural workflows.
2. **Automated Test Harnesses:** Requires machine-verifiable data structures that CI pipelines and claim checkers (`_claims.py`) can validate without token-heavy model inference.

![Moonglade Modular Skillchip Architecture](/images/blog/skillchip_macro_dock.jpg)

Every Moonglade single-file skill embeds a declarative JSON logic contract directly below its procedural markdown:

```json
{
  "$schema": "https://moongladeai.net/schemas/skillchip-v2.json",
  "name": "moonglade_posing",
  "version": "2.1.0",
  "domains": ["editorial_fashion", "lifestyle_documentary", "caribbean_veranda"],
  "validation_gates": {
    "assert_no_locked_knees": true,
    "assert_limb_torso_airgap": true
  }
}
```

Our build pipelines audit these contracts in automated test runs, ensuring production deployments stay synchronized.

---

### The Unified Slug: Cognitive Clarity and Registry Simplicity

The real advantage of single-file design is **the unified slug**. 

In fragmented systems, an agent must bridge different names across layers: a directory name, a frontmatter ID, an export symbol, and a prompt mention. This creates subtle cognitive drag and alias confusion during tool selection.

When the slug is invariant across every layer, everything snaps into alignment:

* **In the File System:** `skills/moonglade_posing.skill.md`
* **In the Registry Index:** `moonglade:skill:moonglade_posing`
* **In Model Dependencies:** `requires: ["moonglade_posing>=2.1.0"]`
* **In Prompt Invocations:** `@moonglade_posing`
* **In Cryptographic Provenance:** Direct 1:1 hash attestation without directory tree crawling.

#### Why This Pays Off:
1. **Zero Mental Mismatch for LLMs:** The model uses the exact same token for reasoning, referencing, and invocation. There is zero namespace translation overhead.
2. **Single-Directory Discovery:** Rather than performing recursive directory walks to locate nested `SKILL.md` files, an agent reads the single skills directory in a direct $O(N)$ sweep.
3. **Simplified Content Hashing:** Edge workers and local runtimes verify skill integrity by computing a single SHA-256 digest over one file rather than hashing an entire directory tree.
4. **Deterministic Telemetry:** When an execution trace logs `loaded: moonglade_posing@2.1.0`, it points unambiguously to one file on disk.

One slug. One file. Zero ambiguity.

---

### Additive, Not Fragmenting: The Lossless Bridge

We are not proposing to replace the directory standard. Breaking existing tools is how good ideas get rejected.

Instead, we propose supporting `<name>.skill.md` **alongside** `<dir>/SKILL.md`, backed by a proposed bidirectional converter design:

```bash
skills-convert to-single  skills/posing-guidance/  ->  posing-guidance.skill.md
skills-convert to-dir     posing-guidance.skill.md ->  skills/posing-guidance/SKILL.md
```

In this converter specification, if a skill bundles external scripts or assets in a directory, the converter refuses to flatten it. If it is pure instructions, it round-trips with zero data loss.

Packing light does not mean leaving your tools behind: it means carrying them with intention.

Talk soon,  
**Anaiya ✨**