ecosystem-layering

Files (1)

• SKILL.md

SKILL.md (first lines)

# Ecosystem Layering

## Overview

If you run more than one AI coding agent on your machine, they will silently contaminate each other. Every agent recursively searches `$HOME` for files named `SKILL.md`, `AGENTS.md`, `AGENTS.md`, and loads whatever it finds first — regardless of which agent it was written for. This skill teaches a three-layer governance pattern that prevents cross-contamination while keeping all agents functional.

The pattern separates concerns into three planes: **canonical** (source of truth, write here), **runtime** (what each agent loads, scoped to its directory), and **librarian** (cross-platform documentation, maps relationships). Between canonical and runtime sits an **adaptation pipeline** that translates tool names, paths, and conventions so each agent gets content written for its own toolset.

## When to Use

- You have 2+ AI coding agents installed (any combination of Codex, Cursor, Codex, Cline, GitHub Copilot, Gemini CLI, Qwen, Windsurf, Codeium, etc.)
- An agent loaded a skill and referenced tools it doesn't have (Codex skill loaded by Cursor, etc.)
- You're setting up a new agent and don't want it loading skills from other agents
- Skills or agents appear to work but produce wrong results because they're using another platform's tool names
- You're building a skill ecosystem and want it to work across multiple platforms
- You're seeing "unknown tool" errors from skills that work fine in another agent

Don't use for:
- Single-agent setups — the problem doesn't exist
- Purely containerized/isolated agents that don't share `$HOME`
- Teams where each developer uses exactly one platform

## The Three-Plane Model

Every healthy multi-agent ecosystem separates into three planes. Each has a distinct role and a distinct edit rule.

```
┌─────────────────────────────────────────────┐
│  CANONICAL PLANE  (Write here first)         │
│  ~/my-supremepowers/, ~/.hermes/skills/      │
│  Source of truth for skills, agents, rules   │
│  EDIT: Always                                 │
└──────────────┬──────────────────────────────┘
               │  adapt-skill.py / manual
               ▼
┌─────────────────────────────────────────────┐
│  RUNTIME PLANES  (Scoped per agent)          │
│  ~/.cline/skills/, ~/.codex/skills/, ...     │
│  Each agent loads ONLY from its own dir      │
│  EDIT: Never directly — adapt from canonical  │
└─────────────────────────────────────────────┘
               │
┌──────────────┴──────────────────────────────┐
│  LIBRARIAN PLANE  (Maps everything)          │
│  ~/Guides/, docs/ECOSYSTEM_MAP.md            │
│  Cross-platform docs, path inventories       │
│  EDIT: Append, don't overwrite               │
└─────────────────────────────────────────────┘
```

### Plane Roles

| Plane | Purpose | Edit Rule | Example Paths |
|-------|---------|-----------|---------------|
| **Canonical** | Single source of truth for behaviors | Always edit here; changes flow downstream | `~/my-supremepowers/skills/`, `~/.hermes/skills/` |
| **Runtime** | What each agent actually loads | Never edit directly; adapt from canonical | `~/.cline/skills/`, `~/.codex/skills/`, `~/.cursor/skills/` |
| **Librarian** | Cross-platform maps, inventories, analysis | Append; treat as documentation, not runtime | `~/Guides/`, `docs/ECOSYSTEM_MAP.md` |

### The Golden Rule

**Canonical writes, runtime reads, librarian maps.** If you fix a bug in `~/.cline/skills/brainstorming/SKILL.md` directly, it will be overwritten the next time someone adapts from canonical. Always fix in canonical, then re-adapt.

## The Cross-Contamination Problem

Every AI coding agent makes three assumptions — all wrong in a multi-agent home directory:

1. **"I'm the only agent here"** — Recursively searches `$HOME`, finds every `SKILL.md`, `AGENTS.md`, `agents/` directory
2. **"Generic filenames are mine"** — `SKILL.md` means different things to Codex (expects `Task`/`Bash`/`WebFetch` tools) vs Cline (`spawn_agent`/`run_commands`/`fetch_web_content`)
3. **"Content was written for me"** — Loads a file and assumes tool names, paths, and conventions match its own

### Real Confirmed Case

Cline activated the `using-superpowers` skill and loaded it from `~/.gemini/extensions/supremepower/skills/` — a Gemini extension directory. The skill was written for Codex and referenced tools Cline doesn't have:

| Codex Tool (in skill) | Cline Tool (actual) |
|---|---|
| `Task` | `spawn_agent` |
| `WebFetch` | `fetch_web_content` |
| `Bash` | `run_commands` |
| `Read` / `Write` / `Edit` | `read_files` / `editor` |
| `Grep` / `Glob` | `search_codebase` |

Cline tried to use Codex tools it didn't have. This wasn't a crash — it was silent wrong behavior. The skill's instructions were followed with the wrong tools.

### Risk Surface by File Type

| File Pattern | Found In | Risk |
|---|---|---|
| `SKILL.md` | Every agent's `skills/` dir, extensions, caches | **Highest** — every agent loads skills |
| `AGENTS.md` / `CLINE.md` / `GEMINI.md` / `AGENTS.md` | Project roots, dotfolders | Auto-loaded as context on session start |
| `agents/` directory | Every dotfolder | Subagent definitions with platform-specific tool references |
| `rules/` directory | `.cursor/rules/`, `.codex/rules/`, `.qwen/rules/` | Behavioral constraints with platform syntax |
| `settings.json` / `config.toml` | Each dotfolder | MCP allow-lists, provider configs, permission models |

## The Adaptation Pipeline

When a skill must be shared across agents, run it through an adaptation pipeline instead of copying raw.

### The Pattern

```
canonical SKILL.md (written for Codex)
        │
        ▼
  adaptation script + tool-mapping tables
        │
        ▼
  platform-native SKILL.md in agent's scoped directory
```

### What Gets Transformed

A complete adaptation needs at minimum:

| Category | Codex (canonical) | Cline | Codex | Cursor | Copilot |
|---|---|---|---|---|---|
| File read | `Read` tool | `read_files` | `read_file` | `read_file` | `read_file` |
| File write | `Write` / `Edit` | `editor` | `write_file` / `patch` | `edit_file` | `edit_file` |
| Search | `Grep` / `Glob` | `search_codebase` | `search_files` | `grep_search` | `search` |

From AvaTar-ArTs/.Agent-skills, MIT.

More from AvaTar-ArTs/.Agent-skills