AI Coding Tool Landscape

Research into agent file formats (skills, rules, memory, hooks, agents, plugins), invocation methods, context loading strategies, and format differences across AI coding tools — informing tome’s connector architecture.

Last updated: March 2026

1. The Full Taxonomy

AI coding tools have up to seven layers of configuration. Most discussions focus on the first three, but the extended structures (hooks, agents, plugins, MCP) are where the real divergence happens.

Key insight: Skills and MCP are the two truly portable layers. Everything else is tool-specific.

2. Tool-by-Tool Breakdown

Claude Code

Vendor: Anthropic | Type: CLI agent | SKILL.md: Full standard + extensions

Unique skill extensions beyond the standard:

• disable-model-invocation: true — user-only invocation
• user-invocable: false — model-only (background knowledge)
• context: fork + agent: Explore — run skill in isolated subagent
• `!command` syntax — inject shell output into skill content before sending to model
• $ARGUMENTS, $0, $1 — argument substitution
• hooks — lifecycle hooks scoped to the skill

Extended structures:

• Hooks — 12 lifecycle events (SessionStart, PreToolUse, PostToolUse, Stop, etc.) with 3 hook types: command, prompt, agent. Configured in settings.json at global/project/local levels.
• Agents — .claude/agents/*.md with YAML frontmatter (11+ fields: tools, model, maxTurns, hooks, mcpServers, permissionMode, etc.). Isolated subagents with own context/tools/model.
• Plugins — plugin.json manifest bundling skills + agents + hooks + MCP + LSP servers + output styles. Marketplace discovery via /plugin. Three install scopes: user/project/local.
• Commands — .claude/commands/*.md (legacy, superseded by skills but still supported). Simple markdown, no frontmatter.
• Settings — Three-level hierarchy: ~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json. Permissions, hooks, MCP servers. JSON schema available.
• MCP — .mcp.json at project root or in settings. Supports stdio/http/sse. Env var expansion: ${VAR}, ${VAR:-default}.

Codex CLI

Vendor: OpenAI | Type: CLI agent | SKILL.md: Standard + agents/openai.yaml

agents/openai.yaml adds Codex-specific configuration:

interface:
  display_name: "User-facing name"
  icon_small: "./assets/logo.svg"
  brand_color: "#3B82F6"
policy:
  allow_implicit_invocation: false   # Disable auto-matching
dependencies:
  tools:
    - type: "mcp"
      value: "toolName"
      url: "https://example.com"

Antigravity

Vendor: Google | Type: IDE agent | SKILL.md: Standard

Key pattern: Antigravity emphasizes narrow, precise descriptions with explicit “do not use” clauses to reduce false activation.

Cursor

Vendor: Anysphere | Type: IDE | SKILL.md: Adopted via agentskills.io (2026)

.mdc rule example:

---
description: Python API conventions
globs: ["*.py", "src/**/*.py"]
alwaysApply: false
---
Use type hints on all function signatures...

Evolution: .cursorrules (2023) → .cursor/ folder with index.mdc (2024) → Multi-file .cursor/rules/*.mdc (2025) → Context-aware rules with MCP integration (2026)

Windsurf

Vendor: Codeium | Type: IDE | SKILL.md: Not documented

Activation modes:

OpenCode

Vendor: SST (open source) | Type: CLI agent | SKILL.md: Via standard

OpenClaw

Vendor: Open source | Type: Autonomous agent | SKILL.md: Supported

OpenClaw has the richest file taxonomy — 8 separate config files loaded at session start into the system prompt. This gives fine-grained control but means more files for tome to discover and potentially sync.

Nanobot (HKUDS)

Vendor: HKUDS (open source) | Type: Lightweight CLI agent | SKILL.md: Via OpenClaw compat

Nanobot is essentially an OpenClaw-compatible agent in a fraction of the code. Same file conventions, same workspace structure.

PicoClaw

Vendor: Open source | Type: Ultra-lightweight agent | SKILL.md: Not documented

PicoClaw prioritizes extreme minimalism. For tome, it would likely be an MCP target rather than a skill directory target.

Gemini CLI

Vendor: Google | Type: CLI agent | SKILL.md: Standard

Extensions (2026): gemini-extension.json packaging prompts, MCP servers, and commands. Extension settings allow user-prompted configuration on install with env var mapping.

Shell execution: !{command} syntax for shell injection with auto-escaping of {{args}}. Argument substitution via {{args}} (not $ARGUMENTS).

Gemini CLI is the simplest format for instructions — plain markdown files concatenated into context. No frontmatter, no structured fields. The @file.md import syntax and !{command} execution are unique.

Skills (2026): Gemini CLI now supports SKILL.md directory scanning. Personal skills at ~/.gemini/skills/ and the portable ~/.agents/skills/ path. For tome, Gemini CLI is a Symlink target via ~/.gemini/skills/.

VS Code Copilot

Vendor: GitHub (Microsoft) | Type: IDE agent | SKILL.md: Full standard (since Jan 2026)

Copilot Workspace (GitHub Next): Running coding agents via GitHub Actions — agent workflows as CI/CD.

Amp

Vendor: Sourcegraph | Type: CLI/IDE agent | SKILL.md: Standard (migrating to)

Amp is a useful case study — their migration from custom commands to Agent Skills demonstrates the industry consolidation trend.

Goose

Vendor: Block (Square) | Type: Autonomous agent | SKILL.md: Standard

Goose now supports SKILL.md directory scanning alongside its MCP-centric extension model. For tome, Goose is a Symlink target via ~/.config/goose/skills/.

Aider

Vendor: Open source | Type: CLI pair programmer | SKILL.md: Not documented

Aider is minimal — no skills, no hooks, no agents. Pure configuration-driven.

3. Instruction Files (Rules)

Each tool reads project-level instructions from a differently-named markdown file. The content is plain markdown (no frontmatter) and is always loaded into context.

What this means for tome

A “rule” that should apply everywhere needs to exist as up to 5 different files:

• CLAUDE.md (Claude Code)
• AGENTS.md (Codex, OpenCode, OpenClaw)
• GEMINI.md (Antigravity, Gemini CLI)
• .github/copilot-instructions.md (VS Code Copilot)
• .cursor/rules/*.mdc or .windsurf/rules/*.md (IDE-specific)

Symlinks can unify the markdown-based ones, but Cursor/Windsurf require format transforms.

AGENTS.md as open standard

AGENTS.md has emerged as an open instruction-file standard under the Linux Foundation / Agentic AI Foundation. It is adopted by Codex, OpenCode, OpenClaw, and configurable in Gemini CLI — the instruction-file equivalent of the SKILL.md skills standard. The portable path ~/.agents/ (and its skills/ subdirectory) is scanned by Codex, Goose, Gemini CLI, OpenCode, Amp, and Cursor.

4. SKILL.md Standard (agentskills.io)

The Agent Skills format originated at Anthropic in late 2025 and was released as an open standard. It defines a portable way to package reusable instructions, scripts, and resources for AI coding agents. As of February 2026, 27+ tools have adopted it.

Who supports it

Invocation methods

Required frontmatter

---
name: my-skill          # 1-64 chars, lowercase + hyphens, must match directory name
description: |          # 1-1024 chars. When to use this skill.
  What it does and when the agent should activate it.
---

Optional frontmatter

license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
compatibility: Requires poppler-utils
allowed-tools: Read Grep Bash(git:*)

Skill directory structure

skill-name/
├── SKILL.md           # Required — instructions + frontmatter
├── scripts/           # Optional — executable code
├── references/        # Optional — detailed docs loaded on demand
└── assets/            # Optional — templates, data files

Discovery paths

5. Parsing Differences (The Details That Break Things)

5.1 YAML Frontmatter

Delimiters: All tools require --- (three hyphens) at start and end.

Unknown fields: Silently ignored by all tools following the Agent Skills standard. Claude Code has occasionally thrown errors on unexpected keys in non-standard positions.

Case sensitivity: All field names are case-sensitive and must be lowercase. SKILL.md filename must be exact uppercase — skill.md won’t be discovered.

Multiline descriptions — MAJOR GOTCHA:

Claude Code’s YAML parser breaks on Prettier-formatted multiline descriptions:

# BROKEN — Claude Code can't parse this (Prettier-wrapped):
---
description: This is a long description that Prettier
  wraps across multiple lines without a block scalar
---

# WORKS — single line:
---
description: This is a long description kept on one line  # prettier-ignore
---

# WORKS — explicit block scalar:
---
description: |
  This is a long description using
  a YAML block scalar indicator.
---

Other tools (Codex, Cursor, Windsurf, Gemini CLI) handle standard YAML multiline correctly.

Workaround: Keep descriptions single-line, or use # prettier-ignore comment, or disable Prettier’s proseWrap for SKILL.md files.

5.2 Markdown Body

Code blocks: All tools prefer triple backticks with language tags. Indented code blocks (4 spaces) work but lack syntax highlighting.

XML tags: Claude is fine-tuned to recognize XML tags (<example>, <system-reminder>, etc.) as structural elements. No other tool does this. Skills that rely on XML structure for Claude won’t parse the same way in Codex/Copilot.

Shell execution in content:

Argument substitution:

Claude Code parser bug: ! inside inline code backticks can be misinterpreted as a bash command. Avoid ! in code spans within SKILL.md files meant for Claude Code.

5.3 Rules Formats (Cursor & Windsurf)

Cursor .mdc files:

---
description: Python API conventions
globs: ["*.py", "src/**/*.py"]
alwaysApply: false
---
Use type hints on all function signatures...

Four activation modes:

Windsurf rules:

Four activation modes: Manual (@-mention), Model Decision (AI decides), Glob (file pattern), Always On.

Limits: Both Cursor and Windsurf enforce 6,000 chars per rule file, 12,000 chars combined. Content beyond the limit is silently truncated.

5.4 VS Code Copilot .instructions.md

---
description: 'Purpose of these instructions (1-500 chars)'
applyTo: '**/*.py'
---
Natural language instructions here...

• description and applyTo are the main frontmatter fields
• excludeAgent: "code-review" or "coding-agent" for agent targeting
• No char limit documented, but recommended to stay under 2 pages
• Glob patterns in applyTo use standard glob syntax

5.5 File Encoding

UTF-8: All tools assume UTF-8. Claude Code has documented bugs with UTF-8 corruption (especially CJK characters via MultiEdit tool). Non-UTF-8 files (Windows-1252) get silently corrupted.

BOM: Use UTF-8 without BOM. VS Code can handle BOM but other tools may not.

Line endings: Use LF (\n). Cursor has a known bug converting CRLF → LF. Enforce via .gitattributes.

Skill names: Must be [a-z0-9-]+ (lowercase alphanumeric + hyphens). No emoji, no unicode, no uppercase.

6. Memory & Persistence

Memory is the least portable layer — every tool has its own mechanism with zero interoperability.

Claude Code

Codex CLI

Cursor

Windsurf

Antigravity

VS Code Copilot

OpenClaw / Nanobot

Summary Table

7. Context Loading Strategies

How each tool manages token budget:

The key difference: SKILL.md-based tools use progressive disclosure (metadata → body → resources), while rules-based tools (Cursor, Windsurf) front-load everything up to their char limits.

Progressive Disclosure Flow

Skills use a three-tier loading strategy to minimize context window consumption:

graph LR
    subgraph "Session Start (~100 tokens/skill)"
        A["Scan skill directories"]
        B["Read frontmatter only<br/>(name + description)"]
    end

    subgraph "Task Matching"
        C{"User prompt matches<br/>skill description?"}
        D["Skill stays dormant"]
    end

    subgraph "Activation (<5000 tokens)"
        E["Load full SKILL.md body"]
        F["Execute instructions"]
    end

    subgraph "On Demand (variable)"
        G["Load references/<br/>scripts/ assets/"]
    end

    A --> B --> C
    C -- No --> D
    C -- Yes --> E --> F
    F -. "if needed" .-> G

8. MCP vs Skills: Efficiency

The Token Problem

MCP servers add tool definitions to context at session start. Each tool includes its name, description, parameter schema, and usage hints — all in natural language so the model understands when and how to use them.

When to Use Which

They’re complementary, not competitive. MCP provides capabilities (tools the agent can call). Skills provide knowledge (instructions the agent follows). A skill can even declare MCP tool dependencies in its frontmatter.

Progressive Disclosure is the Key

The fundamental difference: skills let agents load context incrementally based on what’s actually needed, while MCP front-loads everything. For a library of 50 skills, progressive disclosure means ~5000 tokens at session start vs. potentially hundreds of thousands for equivalent MCP tool definitions.

9. Hooks & Lifecycle Events

Hooks let tools run shell commands or logic at specific points in the agent lifecycle. This is the fastest-growing area of divergence.

Claude Code — 12 Events, 3 Hook Types

Location: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json

Events:

Hook types:

Matchers target specific tools:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash(npm run *)",
      "type": "command",
      "command": "echo 'npm command detected'"
    }]
  }
}

Patterns support: exact ("Bash"), specifier ("Bash(npm run lint)"), wildcards ("Bash(curl *)"), regex-like ("mcp__.*__write.*").

Exit codes: 0 = success, 2 = block action (stderr becomes error message).

Codex CLI — Notify Hooks

Location: Configuration or CLI flags

Codex has a simpler hook system called “notify”:

• Executes external programs on lifecycle events (e.g., agent-turn-complete)
• Less granular than Claude’s 12 events
• Focused on notification rather than validation/blocking

Windsurf — Cascade Hooks

Location: Settings/configuration

• Shell commands at workflow lifecycle points
• Receives JSON context via stdin (similar to Claude)
• Supports user prompt events and policy violation blocking
• Enterprise distribution via cloud dashboard + MDM deployment (Feb 2026)

Amp — Tool Execution Hooks

Location: Settings ("amp.hooks")

{
  "amp.hooks": {
    "tool:post-execute": "npm run lint"
  }
}

• Event format: "tool:post-execute"
• Simpler than Claude’s matcher system

Other Tools

Cross-Tool Hook Comparison

10. Agents & Subagents

Agents are isolated execution contexts with their own tools, model, and permissions. This is distinct from skills (which provide instructions within the main context).

Claude Code — Most Mature Agent System

Location: ~/.claude/agents/*.md (global), .claude/agents/*.md (project)

Format: YAML frontmatter + markdown body

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: [Read, Glob, Grep]
model: sonnet
maxTurns: 10
---
You are a code reviewer focused on...

Frontmatter fields (11+):

Key difference from skills: Agents run in isolated context with their own model and tool restrictions. Skills inject instructions into the current context.

VS Code Copilot — Custom Agents

Location: .github/agents/

GitHub Copilot supports custom agents with:

• Custom tools and prompts
• MCP server access
• Agent targeting via excludeAgent field in instructions
• Two built-in agent types: coding-agent and code-review

Cursor — Parallel Subagents

Location: .cursor/agents/

• Up to 8 parallel agents via Git worktree isolation
• Agents get their own worktree branch for conflict-free parallel work
• Configured similarly to Claude agents

Antigravity — Agent Manager

• Dispatches up to 5 agents simultaneously on separate features
• Multi-model support (Gemini 3 Pro, Claude Sonnet 4.5, GPT-OSS)
• Agent Manager UI for orchestration (not file-based configuration)
• Claims 5-10x productivity from parallel agent execution

Codex CLI — Sandbox Agents

Codex takes a security-first approach:

• Dual-layer security: OS-level sandbox (what’s possible) + approval policy (when to ask)
• Three approval modes: suggest (read-only), auto-edit (edits approved, commands need approval), full-auto
• Agents run within sandbox constraints

OpenClaw/Nanobot — Workspace Files as “Agent Personality”

Rather than defining subagents, OpenClaw defines the main agent’s personality via 8 workspace files:

This is philosophically different — OpenClaw treats the AI as an entity with personality and rituals, rather than a tool with configurations.

Cross-Tool Agent Comparison

11. Plugins & Extensions

Plugins bundle multiple configuration objects (skills, agents, hooks, MCP servers) into a single installable package.

Claude Code — Plugin Ecosystem

Location: .claude-plugin/plugin.json at plugin root

Manifest format:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": { "name": "Author", "email": "dev@example.com" },
  "commands": "./commands/",
  "agents": "./agents/",
  "skills": ["skill1", "skill2"],
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json",
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/"
}

What plugins can contain: Skills, agents, hooks, commands (legacy), MCP servers, LSP servers, output styles.

Discovery: /plugin command → Discover tab. Official + community marketplaces. Three installation scopes: user (default), project, local.

Note: Manifest is optional — Claude Code auto-discovers components if absent.

Cursor — Plugin Marketplace

• Packages skills, subagents, MCP servers, hooks, rules into single install
• 10,000+ tools on Agnxi.com marketplace
• 1,800+ MCP servers available

VS Code Copilot — Extensions

Two flavors:

1. Skillsets — lightweight: tools, prompts, knowledge
2. Full agents — autonomous: multi-step workflows, GitHub App integration

Built as GitHub Apps using the Copilot API. Chat participants (@workspace, @terminal) are built-in extensions.

Gemini CLI — Extensions

Location: Extension directory with gemini-extension.json

{
  "name": "my-extension",
  "prompts": ["./prompts/"],
  "mcpServers": { ... },
  "commands": ["./commands/"]
}

Extension settings (2026): User-prompted configuration on install with environment variable mapping.

Goose — Six Extension Types

100+ MCP servers in toolkit catalog. Auto-OAuth on 401 for HTTP extensions.

Amp — Skills Migration

Amp (Sourcegraph) is actively consolidating:

• Deprecated (Jan 2026): Custom commands, toolboxes
• Replacing with: Agent Skills (SKILL.md standard)
• Migration path: .agents/commands/*.md → .agents/skills/*/SKILL.md
• Key motivation: on-demand loading (zero tokens until needed) vs toolbox overhead

Cross-Tool Plugin Comparison

12. MCP Server Configuration

MCP (Model Context Protocol) is the most universally supported integration mechanism — every major tool supports it.

Configuration Formats

Claude Code MCP Config

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Environment variable expansion: ${VAR} (required), ${VAR:-default} (optional), ${CLAUDE_PLUGIN_ROOT} (plugin-relative).

Key Differences

• Antigravity: MCP Hub with 1,500+ pre-configured servers — UI-driven setup
• Goose: MCP is the primary extension mechanism (not just an add-on)
• Claude Code: Most flexible — supports project, global, and plugin-scoped MCP configs
• Cursor: Stored in .cursor/mcp.json separate from other settings

13. Settings & Permission Systems

Claude Code — Three-Level Settings

Hierarchy (last wins): ~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(~/.zshrc)"],
    "ask": ["Bash(curl *)"],
    "deny": ["Read(./.env)", "Edit(.env*)"]
  },
  "hooks": { ... },
  "mcpServers": { ... },
  "model": "sonnet",
  "maxTurns": 25
}

Permission modes: ask (default), acceptEdits, plan, bypassPermissions (“YOLO”).

Automatic timestamped backups (5 most recent retained).

Codex CLI — Dual-Layer Security

Cursor — Settings in .cursor/

• .cursor/rules/*.mdc for rules (covered in section 5.3)
• .cursor/mcp.json for MCP servers
• .cursor/agents/ for agent definitions
• Notepads: persistent context notes referenced with @, survive across sessions (beta)

Windsurf — Enterprise Distribution

• Cloud dashboard for enterprise hook/rule distribution
• MDM deployment support (Feb 2026)
• Policy enforcement via Cascade hooks

Gemini CLI — Extension Settings

~/.gemini/settings.json:

{
  "context": { "fileName": "GEMINI.md" },
  "mcpServers": { ... }
}

Supports custom naming for context files. Extension settings (2026) allow user-prompted configuration on install.

14. Unique Structures by Tool

Some tools have first-class configuration objects that exist nowhere else.

OpenClaw’s Behavioral Workspace

OpenClaw’s 8-file system is philosophically unique — it treats the AI agent as having personality and rituals:

Cursor Notepads (Beta)

Persistent context notes that:

• Are referenced with @notepad-name in chat
• Survive across sessions
• Act like pinned context without consuming always-on token budget
• Distinct from rules (which activate automatically) and skills (which activate on match)

Copilot Workspace (GitHub Next)

Running coding agents via GitHub Actions — agent workflows as CI/CD:

• Agent gets a PR, makes changes, runs tests
• Operates in GitHub’s infrastructure, not local machine
• Distinct from Copilot Chat / VS Code integration

Goose Auto-OAuth

HTTP extensions automatically handle OAuth flows on 401 responses — no manual token management.

Antigravity Multi-Model

Agent Manager supports dispatching agents on different LLM backends simultaneously:

• Gemini 3 Pro, Claude Sonnet 4.5, GPT-OSS
• Choose model per agent based on task characteristics

15. Full Cross-Tool Comparison Matrix

Legend: Full+ = standard with extensions, Std+ = standard with extra config, Std = standard, Compat = compatible, Adopted = recently added, — = not supported

16. Diagrams

Format Family Tree

graph TD
    Standard["Agent Skills Standard<br/>(agentskills.io)"]

    subgraph "SKILL.md Family"
        CC["Claude Code<br/>(standard + extensions)"]
        Codex["Codex CLI<br/>(standard + openai.yaml)"]
        AG["Antigravity<br/>(standard)"]
        OC_skill["OpenCode<br/>(standard)"]
        Cursor_skill["Cursor<br/>(adopted 2026)"]
        Copilot_skill["VS Code Copilot<br/>(full, Jan 2026)"]
        Amp_skill["Amp<br/>(migrating to)"]
    end

    subgraph "AGENTS.md Family"
        Codex_agents["Codex CLI"]
        OC_agents["OpenCode<br/>(CLAUDE.md fallback)"]
        OClaw["OpenClaw<br/>(+ SOUL.md, IDENTITY.md, ...)"]
        Nano["Nanobot<br/>(OpenClaw subset)"]
    end

    subgraph "Custom Rules"
        Cursor_rules["Cursor<br/>(.mdc with globs)"]
        Windsurf_rules["Windsurf<br/>(4 activation modes)"]
        Copilot_rules["VS Code Copilot<br/>(.instructions.md with applyTo)"]
    end

    subgraph "Plain Markdown"
        Claude_md["Claude Code<br/>(CLAUDE.md)"]
        Gemini_md["Gemini CLI<br/>(GEMINI.md + @imports)"]
        Copilot_md["VS Code Copilot<br/>(copilot-instructions.md)"]
    end

    subgraph "MCP-Only"
        Goose_mcp["Goose<br/>(6 extension types)"]
        Pico_mcp["PicoClaw"]
    end

    Standard --> CC
    Standard --> Codex
    Standard --> AG
    Standard --> OC_skill
    Standard --> Cursor_skill
    Standard --> Copilot_skill
    Standard --> Amp_skill
    OClaw --> Nano

tome Connector Mapping

graph LR
    subgraph "Source Connectors"
        S1["Claude Plugins<br/>(installed_plugins.json)"]
        S2["SKILL.md directories"]
        S3["Cursor .mdc rules"]
        S4["Windsurf rules"]
        S5["OpenClaw workspace"]
        S6["Copilot .instructions.md"]
    end

    subgraph "tome Library"
        L["Canonical format<br/>(SKILL.md standard)"]
    end

    subgraph "Target Connectors"
        T1["Symlink targets<br/>(Claude, Codex, Antigravity,<br/>OpenClaw, Copilot, OpenCode, Amp)"]
        T2["MCP targets<br/>(Goose, PicoClaw)"]
        T3["Format transform targets<br/>(Cursor .mdc, Windsurf rules,<br/>Copilot .instructions.md)"]
    end

    S1 --> L
    S2 --> L
    S3 -. "transform<br/>.mdc → SKILL.md" .-> L
    S4 -. "transform<br/>rules → SKILL.md" .-> L
    S5 --> L
    S6 -. "transform<br/>.instructions.md → SKILL.md" .-> L

    L --> T1
    L --> T2
    L -. "transform<br/>SKILL.md → native" .-> T3

17. Guidelines for Writing Portable Skills

Do

• Keep descriptions single-line to avoid Claude Code’s YAML multiline parser bug
• Stay under 5,000 tokens per SKILL.md body (recommended by agentskills.io)
• Stay under 6,000 chars if you also target Cursor/Windsurf
• Use [a-z0-9-]+ for skill names — lowercase, hyphens only, matching directory name
• Use triple-backtick code blocks with language tags
• Use UTF-8 without BOM, LF line endings
• Include trigger keywords in descriptions so semantic matching works across tools
• Move detailed content to references/ for progressive disclosure
• Version control your skills — they’re the most portable artifact
• Stick to standard frontmatter fields: name, description, license, metadata, compatibility, allowed-tools

Don’t

• Don’t rely on XML tags for structure — only Claude parses them
• Don’t use !command or $ARGUMENTS in skills meant for multiple tools
• Don’t put emoji or unicode in skill names (descriptions are fine)
• Don’t assume multiline YAML works — test across tools
• Don’t put secrets in skills/rules — they’re version-controlled markdown
• Don’t use tool-specific frontmatter (disable-model-invocation, agents/openai.yaml, globs, alwaysApply) in cross-platform skills — move these to tool-specific config
• Don’t exceed 200 lines for auto-loaded memory files (Claude truncates beyond that)

The Portability Hierarchy

Most portable ──────────────────────────── Least portable

   SKILL.md          Instruction files       Memory
   (agentskills.io)  (CLAUDE.md, etc.)       (tool-specific)

   20+ tools         Symlink across 3-4      Zero interop
   Same format       Cursor/Windsurf need    Every tool different
   Same directory    format transforms       File, DB, or API
   structure

Tool-Specific Features to Use Sparingly

18. Common Pitfalls

Dead Rules

Path globs break after refactoring. Renamed directories cause rules to silently stop matching. Audit regularly.

Memory Poisoning

Auto-generated memories can be manipulated (prompt injection via committed files). Review auto-memory content before trusting it.

Size Bloat

Auto-memories grow unbounded. Large instruction files consume context budget, leaving less room for actual conversation. Claude Code’s 200-line auto-load limit is a safeguard.

LLM Inconsistency

Cursor rules behave differently depending on which LLM backend is active. The same .mdc rule may work with Claude but fail with GPT-4. Agent Skills are more consistent because the SKILL.md body is pure natural language.

Migration Pain

No tool provides automatic format conversion. Moving from .cursorrules to SKILL.md, or from Windsurf rules to anything else, requires manual work. This is the gap tome aims to fill.

19. What This Means for tome

Format Families to Support

Based on this research, tome’s connector architecture needs to handle four format families:

Syncable Structures (Today)

Syncable with Transforms (Future)

Not Syncable (Tool-Specific)

Connector Design Recommendations

1. SKILL.md as canonical format — The library stores everything in Agent Skills standard format. This is already what most tools natively understand. As of Feb 2026, 7+ major tools read SKILL.md natively.

2. Symlink-first for SKILL.md tools — Claude Code, Codex, Copilot, Antigravity, OpenCode, and Amp all read SKILL.md natively. Symlinks from library to target skill directory are zero-cost and keep everything in sync.

3. Transform pipeline for custom rules — Three tools need format transforms:

   • Cursor: Generate .mdc files with description, globs, and alwaysApply frontmatter from SKILL.md metadata
   • Windsurf: Generate rules with appropriate activation mode from skill description
   • Copilot: Generate .instructions.md with description and applyTo frontmatter

4. MCP config for tool-based targets — Tools that consume skills via MCP get a config entry pointing at the tome MCP server rather than direct file access. Goose is the primary MCP-only target.

5. OpenClaw/Nanobot as special cases — Their 8-file workspace model means a connector needs to map skills into the appropriate slot (AGENTS.md for instructions, TOOLS.md for capabilities, etc.) or just target their skills directory.

What’s Portable vs. What’s Not

Tool-specific skill extensions are lost in translation — tome should preserve them in metadata when syncing between tools of the same type, but can safely drop them when translating to a different format family.

The Convergence Trend

As of Feb 2026, the industry is consolidating around:

1. Agent Skills (SKILL.md) for portable instructions — the clear winner
2. MCP for portable tool integrations — universal adoption
3. Markdown instruction files for project rules — same concept, different filenames

Everything else (hooks, agents, plugins, memory) remains fragmented with no signs of standardization. For tome, this means the v1 focus on skills + MCP + instruction files covers the portable surface area. Extended structures would require per-tool connectors with no format translation possible.

20. Skill Installers: npx skills (Vercel Labs)

npx skills is a JavaScript-based skill installer with a polished interactive CLI. It supports 41 agent targets and uses a two-tier architecture remarkably similar to tome’s library model.

Registry: skills.sh — browsable skill registry with per-skill detail pages.

Architecture

Canonical copies are stored in .agents/skills/<name>/ (the emerging universal path) or tool-specific directories. Distribution to individual tools uses symlinks from their native skill dirs back to the canonical location.

Install flow: clone repo → select skills → select targets → choose scope (project/global) → choose method (symlink/copy) → security assessment → install.

.skill-lock.json (v3)

Lockfile at .agents/.skill-lock.json tracks installed skills with provenance and content hashes:

{
  "version": 3,
  "skills": {
    "skill-name": {
      "source": "owner/repo",
      "sourceType": "github",
      "sourceUrl": "https://github.com/owner/repo.git",
      "skillPath": "skills/skill-name/SKILL.md",
      "skillFolderHash": "c2f31172b6f256272305a5e6e7228b258446899f",
      "installedAt": "2026-03-06T12:49:32.629Z",
      "updatedAt": "2026-03-06T12:49:32.629Z"
    }
  },
  "dismissed": { ... },
  "lastSelectedAgents": ["amp", "cline", "codex", "cursor", "..."]
}

Key fields: sourceType + sourceUrl for provenance, skillFolderHash for content-based idempotency (similar to tome’s SHA-256 manifest hashes), installedAt/updatedAt timestamps.

Agent Targets (41 total)

Universal agents (share .agents/skills/ as project-scoped path):

Additional agents (tool-specific paths):

CLI Commands

Security Assessment

The installer integrates security risk assessment with three providers:

Each skill gets a security rating before installation, with a link to details on skills.sh.

Implications for tome

1. .agents/skills/ is the emerging universal path — 9 agents converge on it. Tome’s Directory source type can discover skills there today.
2. Lockfile as prior art for tome.lock — .skill-lock.json v3 tracks the same concepts tome needs: content hashes for idempotency, source provenance, install timestamps.
3. Symlink vs copy choice — npx skills offers both, recommending symlink. Tome already uses this model (library copies + symlink distribution).
4. Security assessment — interesting prior art for a future tome audit command.
5. 41-agent coverage — significantly expands the known agent landscape beyond tome’s current connector list.

Sources

Standards & Specifications

• Agent Skills Open Standard — format specification
• Agent Skills Specification
• Model Context Protocol — tool integration standard

Claude Code

• Skills Docs — full frontmatter reference
• Memory Docs
• Hooks Reference — lifecycle events
• Hooks Guide — hook types and matchers
• Subagents — agent configuration
• Plugins Reference — plugin manifest
• MCP Configuration — MCP server setup
• Settings — permission system
• GitHub Issues: #10589, #11322, #17119, #13932, #2154

Codex CLI

• Skills — discovery and invocation
• CLI Features — hooks, sandbox, telemetry
• AGENTS.md Guide — instruction file format

VS Code Copilot

• Custom Instructions — instruction files
• Agent Skills — SKILL.md support
• Agent Mode — agents
• Copilot Memories — memory system
• Building Extensions — plugin system

Cursor & Windsurf

• Cursor Rules Guide — .mdc format and activation modes
• Windsurf Rules
• Windsurf Cascade Memories — rules and activation
• Windsurf Cascade Hooks — lifecycle events

Gemini CLI & Antigravity

• Gemini CLI Context Files
• Gemini CLI GEMINI.md — context files
• Gemini CLI Extensions — extension system
• Antigravity MCP Integration

OpenClaw, Amp, Goose, Aider, Others

• OpenCode Rules — AGENTS.md format
• OpenClaw Memory Files — SOUL.md, HEARTBEAT.md, etc.
• Amp Skills Migration — commands → skills
• Goose Extensions — MCP-based extensions
• Aider Configuration — YAML config
• Nanobot (HKUDS) — OpenClaw-compatible agent
• PicoClaw — ultra-lightweight agent

Skill Installers

• npx skills (Vercel Labs) — 41-agent skill installer with lockfile and security assessment
• skills.sh — skill registry with per-skill detail pages and security ratings

Analysis & Security

• Skills Are More Context-Efficient Than MCP — token comparison
• MCP Token Problem — efficiency analysis
• Claude Skills vs MCP — technical comparison
• Why Cursor Rules Failed and Claude Skills Succeeded — format comparison
• The Memory Manipulation Problem
• Hidden Unicode Backdoors in Agent Skills