Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

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

Browse Source 
- 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>
This commit is contained in:
Defame1297
2026-05-26 18:33:36 +00:00
parent be2910f8f6
commit 663f10c3fe
4 changed files with 16 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.agents/skills/write-skill/META.md
View File

@@ -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.

8
.agents/skills/write-skill/SKILL-TEMPLATE.md
View File

@@ -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>

7
.agents/skills/write-skill/SKILL.md
View File

@@ -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