Progressive structure

Applies to: StablEdge Desktop 0.4.4 and later

When a regular Skill is loaded, its whole body enters the context at once. With a long body and many topics, that takes up a lot of context. The Progressive structure splits the body into sections with stable IDs: loading returns only a "cover", and the Agent then reads specific sections on demand.

When to use it

• The body has several fairly independent topics, and one task usually needs only one or two of them;
• A few rules must be followed whatever the task is, and need to stay on the cover at all times;
• You want the Agent to reference sections by stable ID instead of relying on the heading text.

For a Skill with a very short body (within a few dozen lines) that must be read in full every time, keep the regular structure.

How to turn it on

Add a progressive mapping to the frontmatter. Here is how the built-in xlsx Skill does it (excerpted from builtin/xlsx/SKILL.md, description omitted):

---
name: xlsx
description: "..."
progressive:
  always:
    - mandatory-rules
    - core-tools
---

As soon as the progressive key appears in the frontmatter, the Skill is parsed by the Progressive rules. When you have no sections that must always be shown, write progressive: {}.

Section ID syntax

In the body of a Progressive Skill, every level-2 and level-3 heading must carry {#section-id} at its end:

## Mandatory rules {#mandatory-rules}

...

## Core tools {#core-tools}

### Reading a spreadsheet {#read-sheet}

...

A section starts at its heading and ends before the next heading of the same or a higher level. A level-2 section therefore contains all the level-3 sections under it, and level-3 sections can also be read on their own.

progressive.always

progressive.always is a list of section IDs. The listed sections go straight onto the cover, so the Agent sees them when it loads the Skill; this suits hard rules that must be followed and the most frequently used entry points.

• It must be a list of non-empty strings, with no duplicates;
• Every ID must actually exist in the body;
• Always-on sections also appear in the section index.

The built-in plugin-creator puts three rules sections on the cover (excerpted from builtin/plugin-creator/SKILL.md):

progressive:
  always:
    - current-rules
    - engineering-constraints
    - forbidden-boundaries

The more Always-on sections you add, the longer the cover, and the less context on-demand reading saves. Usually one to three is enough.

How section loading works

1. Load the cover: the Agent calls the load action of the skill tool and gets the cover. The cover contains, in order: a one-line hint on how to read sections, the bundled file list (if any), the full content of the Always-on sections, and an automatically generated index of "sections you can read on demand" (each entry reads section ID — title, with level-3 sections shown indented).
2. Read a section: the Agent uses the read_section action and passes a section_id to get the content of that section; offset and limit read only a range of lines.
3. Heading compatibility: when no ID is passed, the Agent can also look up by heading text (case-insensitive), but duplicate headings make it ask for an ID instead. IDs are therefore the only reliable way to reference a section.

The cover and sections are cached by Skill directory content, and any file change in the directory invalidates the cache.

Validation and fallback

All of the following count as Progressive validation errors:

• progressive is not a mapping, or progressive.always is not a list of IDs or has duplicates;
• A level-2 or level-3 heading lacks an ID, or IDs repeat;
• always references an ID that does not exist;
• The body has no section with an ID at all;
• The resources declaration has problems; see Declaring resources.

When these errors occur:

• At install time: the preview step rejects the Skill outright with the specific error, and the Skill is not installed;
• A Skill already in the directory (for example, after a manual edit): the Skill still loads, but falls back to returning the whole body at once, and read_section is unavailable.