fix: write-skill progressive disclosure — sub-file structure and lessons

- Add sub-file constraint: content-type split rule (explains vs. directs),
  three spec-defined optional directories (scripts/, references/, assets/),
  one-level-deep rule, and wiring syntax requirement
- Update output format section to list optional sub-files as a third output
- Add self-check item for sub-file placement and wiring
- Update SKILL-TEMPLATE.md constraints and output format examples to match
- Bump META.md to v1.3
- Add two LESSONS.md entries: research agents presenting synthesis as spec
  fact; META-TEMPLATE fix deferred with explicit do-not-apply note

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.agents/skills/write-skill/META.md

@@ -1,5 +1,5 @@
 ```yaml
-version: "1.2"
+version: "1.3"
 updated: 2026-05-26
 
 # when: describes when this skill is loaded — the full trigger context.

.agents/skills/write-skill/SKILL-TEMPLATE.md

@@ -34,7 +34,8 @@ metadata:
      Do not include a constraint about body section structure — the template enforces that.
      Example:
      - Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface
-     - Body ≤500 lines — move anything longer into separate files in the skill directory -->
+     - Body ≤500 lines — content that explains rather than directs belongs in sub-files, not the body
+     - Sub-files use three spec-defined optional directories: `scripts/` (executable code), `references/` (on-demand docs), `assets/` (templates, data files, lookup tables). File references must be one level deep. Wire each sub-file with an explicit step instruction (e.g. "See references/lookup.md for error codes") — without wiring, the file is never loaded -->
 
 - <constraint>
 
@@ -58,9 +59,10 @@ metadata:
 <!-- Describe the files or artifacts produced. Include paths and how they are created
      (copy-fill from template, generated, etc.). State the template used for structured file output.
      Example:
-     Two files produced for every skill:
+     Two files produced for every skill, plus optional sub-files if the skill requires them:
      - `SKILL.md` — copy-filled from `SKILL-TEMPLATE.md` at `.agents/skills/<name>/SKILL.md`
-     - `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills/<name>/META.md` -->
+     - `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills/<name>/META.md`
+     - `scripts/`, `references/`, or `assets/` — created only when needed; each file wired with an explicit step instruction -->
 
 <description of output>
 

.agents/skills/write-skill/SKILL.md

@@ -21,7 +21,8 @@ Negative trigger cases are NOT a required input. The agent proposes them based o
 
 - Write two files for every skill: `SKILL.md` at `.agents/skills/<name>/SKILL.md` and `META.md` alongside it
 - Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface
-- Keep the body under 500 lines — move anything longer into separate files in the skill directory
+- Keep the body under 500 lines — content that explains rather than directs belongs in sub-files, not the body
+- Sub-files use three spec-defined optional directories: `scripts/` (executable code), `references/` (on-demand docs), `assets/` (templates, data files, lookup tables); additional files (e.g. `META.md`) are valid at the skill root. File references must be one level deep — no nested chains. Wire each sub-file with an explicit instruction in the step that needs it (e.g. `"See references/lookup.md for error codes"`) — without a wiring instruction the file is never loaded
 - Use XML tags only when the body has three or more logical sections and exceeds 500 tokens — default to plain prose
 - Test the trigger description against all three cases — explicit, implicit, negative — before writing any body content. Hard gate: a failed case means revise and retest, not proceed
 - Check for overlapping skills in `.agents/skills/` before writing anything — if overlap is found, surface it and wait for direction
@@ -51,10 +52,11 @@ Negative trigger cases are NOT a required input. The agent proposes them based o
 
 ## Output format
 
-Two files produced for every skill:
+Two files produced for every skill, plus optional sub-files if the skill requires them:
 
 - `SKILL.md` — copy-filled from `SKILL-TEMPLATE.md` at `.agents/skills/<name>/SKILL.md`
 - `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills/<name>/META.md`
+- `scripts/`, `references/`, or `assets/` — created only when needed; each file wired with an explicit step instruction
 
 For placeholder conversions, `SKILL.md` replaces the existing file entirely — no partial edits.
 
@@ -78,6 +80,7 @@ For placeholder conversions, `SKILL.md` replaces the existing file entirely —
 - [ ] `META.md` copy-filled from `META-TEMPLATE.md` at correct path
 - [ ] Frontmatter contains only `name`, `description`, and `metadata.category` (plus `allowed-tools` if applicable)
 - [ ] Body is under 500 lines
+- [ ] If sub-files exist: placed in correct directory type (`scripts/`, `references/`, or `assets/`) and wired with an explicit instruction in the relevant step
 - [ ] For placeholder conversions: existing files read, all stale content removed, old directory deleted if renamed
 - [ ] `write-eval` invoked — eval file exists at correct path, covers trigger cases (explicit, implicit, negative) and at least one output case
 - [ ] User prompted for HITL behavioral test

LESSONS.md

@@ -72,7 +72,7 @@ The agent-level HITL rule ("require explicit confirmation before irreversible sh
 
 ## 2026-05-26 — META-TEMPLATE uses YAML comments; META.md output retains them
 
-META-TEMPLATE.md uses YAML `#` comments to explain fields inline. SKILL-TEMPLATE.md uses HTML comments inside XML tags, which the agent strips on fill. The structural difference means SKILL.md output is clean but META.md output retains the explanatory `#` lines — an inconsistency. Fix: restructure META-TEMPLATE.md so all explanatory guidance is prose above the code block (markdown, never copied into the output YAML), and the code block itself uses `<placeholder>` syntax with no `#` comment lines. This makes META.md fill behaviour deterministic for the same reason SKILL.md fill is: `<...>` markers are unambiguously replaceable; prose above the block is not part of the template.
+META-TEMPLATE.md uses YAML `#` comments to explain fields inline. SKILL-TEMPLATE.md uses HTML comments inside XML tags, which the agent strips on fill. The structural difference means SKILL.md output is clean but META.md output retains the explanatory `#` lines — an inconsistency. Fix (deferred): restructure META-TEMPLATE.md so all explanatory guidance is prose above the code block (markdown, never copied into the output YAML), and the code block itself uses `<placeholder>` syntax with no `#` comment lines. This makes META.md fill behaviour deterministic for the same reason SKILL.md fill is: `<...>` markers are unambiguously replaceable; prose above the block is not part of the template. Do not apply until the human/copy-fill tradeoff is resolved — see 2026-05-26 session discussion.
 
 ## 2026-05-26 — Overlap checks must scan the deployed directory, not just the source repo
 
@@ -82,6 +82,10 @@ META-TEMPLATE.md uses YAML `#` comments to explain fields inline. SKILL-TEMPLATE
 
 Claude Code supports `model:` as a provider extension in SKILL.md frontmatter — it overrides the session model for the skill's turn and reverts after. Attempting to put it in META.md was wrong: META.md is provenance/audit metadata, not runtime config. The boundary: if a field affects agent behaviour at invocation time, it belongs in SKILL.md frontmatter; if it serves upgrade reviews and audit trails, it belongs in META.md.
 
+## 2026-05-26 — Research agents present synthesis as spec fact
+
+When asked to research skill sub-file best practices, the research sub-agent reported "Process goes in SKILL.md. Context goes in reference files" as if it were verbatim from the Claude Code docs or the Agent Skills spec. Checking agentskills.io directly showed the spec says: "There are no format restrictions" on the body. The principle is a reasonable synthesis, not a quoted rule — but it nearly landed in write-skill's constraints as authoritative spec language. Fix: always verify research agent claims against the primary source before encoding them as rules, especially for spec or documentation claims. Plausible synthesis is the hardest fabrication to catch because it's often correct in spirit.
+
 ## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts
 
 During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction.