Phase 3: Migrate Content with Progressive Disclosure

Move the source skill's body into the scaffolded SKILL.md. If the body exceeds the recommended size, split into references/ files.

3.1 The 5K token rule

Tessl's tessl skill review warns when SKILL.md exceeds ~5000 tokens (typically ~500 lines or ~20 KB of markdown). When triggered, the agent loading the skill pays the full content cost on every activation, even if it only needs one section.

Decide based on source size:

3.2 The slim-SKILL.md pattern

When splitting, the SKILL.md becomes a navigator. Target ~1500 tokens. It should contain:

1. Frontmatter (name, description, metadata)
2. Purpose (1-2 short paragraphs — what the skill does, what modes it supports)
3. Workflow with a phase index table that links to each reference file
4. Quick Decision Triage — single-liner anchors for the most common decisions, so the agent has working knowledge without reading any reference
5. Command/action anchors — at least one concrete command block, checklist, template, or first-action sequence that can be used without opening references
6. Output Format templates if the skill produces structured output — these are short and worth keeping in SKILL.md so the agent always has them
7. Pointers to cross-cutting references (guardrails, decision flowcharts, success criteria)

This is the layout that the agentic-harness-architect tile used to drop front-loaded tokens from ~7500 to ~213.

3.3 Quality 100 entrypoint contract

Before first publish, the root SKILL.md must be a minimal executable slice, not just a table of contents. Progressive disclosure keeps detail in references, but registry Quality still judges whether the entrypoint itself is actionable.

The root SKILL.md should satisfy all four Implementation dimensions without opening a reference file:

References may deepen execution, but they cannot be the only place executable guidance lives. If every command, template, and concrete action is hidden in references/, expect a Quality dock on Implementation/Actionability even when lint and local review pass.

3.4 Markdown links are required for references

When you reference a file in SKILL.md from the slim-SKILL pattern, use real markdown links, not backticked paths:

Why: Tessl's lint extracts the skill bundle's reachable files by parsing markdown links. Backticked paths get flagged as orphaned files ("Found N orphaned file(s) not linked from manifest entrypoints"). Orphans don't get installed when a user runs tessl install — they're effectively missing, even though they exist in the repo.

If the source skill already used backticked paths, rewrite each reference as a markdown link during migration.

3.5 Preserve existing structure if source is a folder

If the source skill is already a folder with references/ and/or scripts/:

1. Copy references/ into <tile-path>/skills/<tile-name>/references/ verbatim. Rewrite any references/foo.md mentions in SKILL.md as markdown links.
2. Copy scripts/ into <tile-path>/skills/<tile-name>/scripts/ verbatim. These already work as bundled executables.
3. Copy assets/ similarly if present.

Do not move bundled resources up to the tile root — they must live under skills/<tile-name>/ to be reachable from SKILL.md via relative paths.

3.6 Reference file conventions

Each reference file should be self-contained enough to read solo. The agent reading a reference doesn't necessarily have SKILL.md's context. Start each reference with:

• A single-line statement of what it covers
• (Optional) A short framing sentence before diving in

End with exit criteria if the reference describes a phase the agent should complete — explicit "this phase is done when X, Y, Z" statements help the agent know when to stop and move on.

3.7 Lint after content migration

tessl tile lint <tile-path>

Watch for:

• ⚠ SKILL.md is approximately N tokens (recommended maximum: 5000) — exceeded budget, split further
• ⚠ Found N orphaned file(s) — references not reachable via markdown links; fix the SKILL.md links
• ✘ anything: stop and fix; Tessl won't publish an invalid tile

Exit criteria

Phase 3 is complete when:

• SKILL.md contains the migrated content (slim entry point if split, full body if under 5K tokens)
• Root SKILL.md satisfies the Quality 100 entrypoint contract: concise, independently actionable, workflow-clear, and linked to deeper references
• All references/ files exist and are reachable via markdown links in SKILL.md
• tessl tile lint shows 0 errors, 0 warnings (other than possibly token-cost info, which is fine)
• Front-loaded tokens reported by lint is in the range ~100-500 (description + slim SKILL.md)