From 8d73084042271c5182512b467798ea0a5ac4a7e6 Mon Sep 17 00:00:00 2001 From: Tim Petrella Date: Tue, 7 Apr 2026 19:33:42 -0400 Subject: [PATCH] Add output-only rule for example files Document in four places that example output files should contain only the skill's actual output with no preambles, commentary, or "how to use" sections: - skill-authoring-guide.md (Section 6) - write-skill SKILL.md (Example files section) - adapt-skill SKILL.md (Example files section) - conventions-checklist.md (both copies, new checklist item) Co-Authored-By: Claude Opus 4.6 (1M context) --- skill-authoring-guide.md | 4 +++- skills/adapt-skill/SKILL.md | 2 +- skills/adapt-skill/references/conventions-checklist.md | 1 + skills/write-skill/SKILL.md | 2 +- skills/write-skill/references/conventions-checklist.md | 1 + 5 files changed, 7 insertions(+), 3 deletions(-) diff --git a/skill-authoring-guide.md b/skill-authoring-guide.md index 83c3746..e835e91 100644 --- a/skill-authoring-guide.md +++ b/skill-authoring-guide.md @@ -143,7 +143,9 @@ Present variations neutrally (A, B, C) without labeling them with descriptors. L Every skill should include a `references/` directory with a sample output file named `example-[description].md` (e.g., `example-output.md`, `example-positioning-brief.md`). The `references/` directory is part of the [Agent Skills open standard](https://agentskills.io). It may also contain glossaries and other supporting documentation the skill reads at runtime. -Example files use the `example-` prefix so they are distinguishable from other reference documents. The example serves as both a quality benchmark for the LLM and a preview for the user. +Example files use the `example-` prefix so they are distinguishable from other reference documents. The example serves as both a quality benchmark for the LLM and a preview for the user on the skill page. + +The example file should contain only the skill's actual output. Do not include preambles ("This example demonstrates..."), "How to use this document" sections, or commentary explaining what the example shows. The output should speak for itself. ### Fictional brand naming diff --git a/skills/adapt-skill/SKILL.md b/skills/adapt-skill/SKILL.md index 2992aa7..5fb79ae 100644 --- a/skills/adapt-skill/SKILL.md +++ b/skills/adapt-skill/SKILL.md @@ -139,7 +139,7 @@ Output must be ready to paste into a CMS, upload to a platform, or hand to a tea Every skill includes an example output file in `references/`. The file must use the `example-` prefix (e.g., `example-output.md`). The SkillShelf website uses this prefix to find and display example files. A file named `sample-output.md` or `output-example.md` will not appear on the site. -The example demonstrates the ceiling, not the floor. If the example is mediocre, the LLM will calibrate to mediocre output. +The example demonstrates the ceiling, not the floor. If the example is mediocre, the LLM will calibrate to mediocre output. The example file should contain only the skill's actual output, with no preambles, commentary, or "how to use" sections. ### General behaviors diff --git a/skills/adapt-skill/references/conventions-checklist.md b/skills/adapt-skill/references/conventions-checklist.md index 2282245..326a9d0 100644 --- a/skills/adapt-skill/references/conventions-checklist.md +++ b/skills/adapt-skill/references/conventions-checklist.md @@ -60,6 +60,7 @@ Use this checklist during Phase 4 to review a skill against SkillShelf standards - [ ] Brand name makes product category immediately clear - [ ] Example demonstrates ceiling quality (not floor) - [ ] Example covers all output sections +- [ ] Example contains only the output (no preambles, commentary, or "how to use" sections) ## Ecosystem diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 2fff91d..889597a 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -176,7 +176,7 @@ Output must be ready to paste into a CMS, upload to a platform, or hand to a tea Every skill includes an example output file in `references/`. The file must use the `example-` prefix (e.g., `example-output.md`). The SkillShelf website uses this prefix to find and display example files. A file named `sample-output.md` or `output-example.md` will not appear on the site. -The example demonstrates the ceiling, not the floor. If the example is mediocre, the LLM will calibrate to mediocre output. +The example demonstrates the ceiling, not the floor. If the example is mediocre, the LLM will calibrate to mediocre output. The example file should contain only the skill's actual output, with no preambles, commentary, or "how to use" sections. ### General behaviors diff --git a/skills/write-skill/references/conventions-checklist.md b/skills/write-skill/references/conventions-checklist.md index 2282245..326a9d0 100644 --- a/skills/write-skill/references/conventions-checklist.md +++ b/skills/write-skill/references/conventions-checklist.md @@ -60,6 +60,7 @@ Use this checklist during Phase 4 to review a skill against SkillShelf standards - [ ] Brand name makes product category immediately clear - [ ] Example demonstrates ceiling quality (not floor) - [ ] Example covers all output sections +- [ ] Example contains only the output (no preambles, commentary, or "how to use" sections) ## Ecosystem