RFC: Skill Overlays by @nibzard

RFC-OVERLAYS.md

RFC: Skill Overlays

Status: Draft Last Updated: 2026-03-09 Author: @nibzard

Abstract

Skill overlays are an optional extension for specializing a base skill without forking it.

An overlay is not a separate skill and is not independently discovered at session start. Instead, it is a support file inside an existing skill directory that adds domain-specific instructions after the base skill has been activated.

This RFC is designed to align with the current Agent Skills model in this repository:

• SKILL.md remains the only required skill entrypoint
• normal skill discovery and activation stay unchanged
• overlay-aware clients may load overlay files on demand as an additional layer of progressive disclosure

Goals

• Specialize a base skill for a narrower domain or workflow
• Preserve compatibility with existing Agent Skills clients
• Avoid skill catalog bloat from many near-duplicate skills
• Keep the base skill portable and reusable

Non-Goals

• Defining a new top-level skill artifact alongside SKILL.md
• Changing base skill discovery rules
• Requiring all clients or validators to support overlays
• Standardizing structural Markdown merge algorithms in v1

Motivation

Many skills are broadly useful but need narrower guidance in some contexts:

• a browser skill may need travel-site-specific guidance
• an xlsx skill may need SaaS-model-specific structure
• a docx skill may need legal-memo-specific conventions

Without overlays, authors usually choose one of three poor options:

1. Fork the base skill, which pollutes the catalog with slight variants
2. Put every specialization into the base skill, which makes it bloated
3. Rely on ad hoc prompting, which is hard to reuse or share

Relationship to the Current Standard

The current Agent Skills standard assumes:

• skills are discovered by locating directories containing SKILL.md
• the model first sees a catalog of skill metadata
• the full SKILL.md is loaded only when the skill is activated
• support files are loaded on demand after activation

This RFC keeps that model intact. Overlays are treated as support files that live under the skill root and are loaded only after the base skill is already in context.

Clients that do not implement overlays can ignore them safely.

Related Proposals

This RFC is adjacent to several open proposals in this repository, but it is intentionally narrower than all of them:

• Issue #115: path-based, recursive skill discovery. That proposal changes where skills are discovered. This RFC does not change base skill discovery and keeps overlays out of the startup catalog.
• Issue #124: dynamic context injection in SKILL.md. That proposal adds post-activation dynamic rendering. This RFC follows the same general philosophy of additive, post-activation context loading.
• Issues #90 and #100: skill relationships and dependencies. This RFC does not define dependencies between separate skills.
• Issues #95 and #137: skill-to-skill invocation and nested skill behavior. This RFC does not define overlays as invocable sub-skills or nested skills.
• Issue #105: frontmatter compatibility and extension pressure across clients. This RFC avoids introducing new required top-level frontmatter fields for the base skill spec.
• Issue #110: dependencies, validation, and testing. This RFC keeps overlay validation optional and tooling-specific in v1.

Conceptual Model

session start
    |
    v
discover base skills only
    |
    v
activate base skill (load SKILL.md)
    |
    v
base skill points to available overlays
    |
    v
load relevant overlay on demand
    |
    v
overlay instructions specialize base skill

The important property is precedence, not file-level Markdown rewriting. An overlay is a higher-priority instruction layer for a narrower use case.

Directory Layout

skill-name/
├── SKILL.md
├── overlays/
│   ├── travel-booking.md
│   └── hotel-comparison.md
├── references/
└── scripts/

overlays/ is an optional directory under the skill root, similar to references/ or scripts/.

Base Skill Requirements

The base skill remains a normal spec-compliant skill with its own SKILL.md.

To make overlays discoverable after activation, the base SKILL.md should include a short overlay index. For example:

## Available Overlays

- `overlays/travel-booking.md`
  Use when booking flights, hotels, or other travel accommodations.

- `overlays/hotel-comparison.md`
  Use when the task is to compare lodging options across multiple listings.

This is the only v1 discovery mechanism. Overlays are not added to the startup skill catalog.

Overlay File Format

Overlay files are Markdown support files. To align with existing skill conventions, they use SKILL-style YAML frontmatter for lightweight metadata.

---
name: travel-booking
description: Specializes the browser skill for booking flows on travel sites.
metadata:
  when: Booking flights, hotels, or travel accommodations
  priority: "10"
  composable: "false"
---

# Form Handling

Prefer destination, dates, guests, then search.

# Result Extraction

Capture property name, price, rating, availability, and URL.

Metadata Conventions

• name: overlay identifier in kebab-case
• description: one-line summary of what the overlay changes and when to use it
• metadata.when: applicability guidance for the model
• metadata.priority: optional integer-like string; higher values apply later
• metadata.composable: optional true or false; defaults to false

The overlay inherits its base skill from its containing directory. v1 does not support an overlay targeting an arbitrary external skill.

Overlay-specific fields are placed under metadata rather than new top-level keys like extends, parent, or priority. The reason is compatibility: current Agent Skills tooling treats top-level frontmatter as a constrained schema, and several adjacent proposals are still exploring how far top-level frontmatter should be extended across implementations.

Activation Flow

1. The client discovers and catalogs base skills exactly as it does today.
2. The model activates a base skill by loading its SKILL.md.
3. If the base skill's instructions indicate that an overlay is relevant, the model loads that overlay file.
4. The overlay's instructions are treated as a narrower, higher-priority layer on top of the base skill.

This preserves progressive disclosure:

• base metadata at session start
• base instructions at skill activation
• overlay instructions only when relevant
• other resources only when needed

Precedence

When overlay content conflicts with base skill guidance, the higher-priority instruction wins.

Recommended precedence order:

1. system constraints
2. developer or platform instructions
3. user instructions
4. overlay instructions
5. base skill instructions
6. referenced examples and support files

An overlay may narrow the scope of the base skill, but it must not grant capabilities or permissions that the host agent would otherwise deny.

Composition

The default model is one overlay at a time.

An overlay is not:

• a separate skill that appears in the startup catalog
• a dependency that must be installed independently
• a nested skill that can be invoked by name
• a mechanism for cross-skill delegation
• a way to target a different skill outside the containing directory

Multiple overlays may be applied only if:

• the client supports multi-overlay composition
• each overlay is marked composable
• the resulting order is deterministic

If multiple overlays are applied, sort by:

1. metadata.priority ascending
2. filename ascending

Later overlays have higher precedence than earlier overlays.

Semantics in v1

v1 defines overlays as instruction layers, not as structural document patches.

That means:

• clients do not need to physically merge Markdown files
• "same heading overrides same heading" is guidance for authors, not a normative parsing rule
• the effective behavior comes from instruction precedence in the model context

This avoids underspecified AST-level merge behavior while still supporting the main use case: specialization of a base skill.

Authoring Guidance

Use an overlay when the result is still the same skill, but adapted for a narrower domain.

Prefer a separate skill when:

• the workflow is independently useful outside the base skill
• the specialization changes the skill's identity
• the overlay would be larger or more general than the base skill

Keep overlays focused. They should usually:

• narrow decision rules
• add domain-specific terminology
• add domain-specific extraction or formatting requirements
• clarify edge cases for a known subdomain

They should usually not:

• restate most of the base skill
• duplicate long examples from the base skill
• introduce unrelated workflows

Validation in v1

This RFC does not require changes to the core Agent Skills validator for base skill compliance.

Overlay-aware tooling may additionally validate:

• the file is under overlays/
• the containing directory has a valid base SKILL.md
• the overlay frontmatter includes name and description
• metadata.priority, if present, parses as an integer
• metadata.composable, if present, is true or false
• overlay file references resolve within the skill root

The following are authoring heuristics, not hard validator rules:

• avoid overlays that mostly duplicate the base skill
• avoid overlays that broaden the base skill's scope
• prefer a separate skill if the specialization stands on its own

Trust and Security

Overlays inherit the trust boundary of their containing skill.

• if a project-level skill is blocked by trust settings, its overlays are blocked too
• overlays do not create new discovery surfaces outside the skill root
• overlays must not expand permissions beyond what the base skill and host agent already allow

Example

Base skill: browser

SKILL.md excerpt:

---
name: browser
description: Navigate websites, interact with forms, and extract structured information.
---

## Available Overlays

- `overlays/travel-booking.md`
  Use when the task involves booking flights or accommodations.

## Core Workflow

Navigate carefully, confirm visible page state, and extract structured data.

Overlay file: overlays/travel-booking.md

---
name: travel-booking
description: Specializes browser workflows for travel booking sites.
metadata:
  when: Booking flights, hotels, or accommodations
  priority: "10"
  composable: "false"
---

# Form Handling

Look first for destination, travel dates, guest count, and the primary search action.

# Result Extraction

Extract listing name, total price when visible, rating, cancellation terms, and URL.

Activation path:

1. the model sees browser in the startup skill catalog
2. the model activates browser by loading SKILL.md
3. the task is specifically about travel booking, so the model loads overlays/travel-booking.md
4. the overlay specializes how the browser skill approaches the task

Conclusion

Skill overlays provide a way to specialize a base skill without creating a separate top-level skill.

The key design choice in this RFC is compatibility: overlays are support files loaded after base skill activation, not a second discovery format. That keeps the current Agent Skills model intact while making specialization easier to express.