From 3c42530c7fedda804a490319f433cc6d8e8ab43c Mon Sep 17 00:00:00 2001 From: Tim Petrella Date: Tue, 7 Apr 2026 19:12:58 -0400 Subject: [PATCH] Remove glossary system from write-skill and adapt-skill All foundation skills are written, so the glossary mechanism for downstream skill consumption is no longer needed. Remove: - glossary-writing-guide.md from both skills' references - Glossary output item from SKILL.md Turn 5/Turn 4 supporting files - Glossary reference from the opening "read references" instruction - Glossary checklist items from conventions-checklist.md - Glossary mentions from FAQ and output_schema in skillshelf.yaml Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/adapt-skill/SKILL.md | 3 +- .../references/conventions-checklist.md | 3 - .../references/glossary-writing-guide.md | 187 ------------------ skills/adapt-skill/skillshelf.yaml | 3 +- skills/write-skill/SKILL.md | 3 +- .../references/conventions-checklist.md | 3 - .../references/glossary-writing-guide.md | 187 ------------------ skills/write-skill/skillshelf.yaml | 8 +- 8 files changed, 6 insertions(+), 391 deletions(-) delete mode 100644 skills/adapt-skill/references/glossary-writing-guide.md delete mode 100644 skills/write-skill/references/glossary-writing-guide.md diff --git a/skills/adapt-skill/SKILL.md b/skills/adapt-skill/SKILL.md index a14a34e..3c99f99 100644 --- a/skills/adapt-skill/SKILL.md +++ b/skills/adapt-skill/SKILL.md @@ -10,7 +10,7 @@ license: Apache-2.0 You already have a prompt or skill that works. This skill converts it into the format SkillShelf uses, so other people can find it, download it, and use it with their own AI tools. Paste your prompt, upload a file, or upload a zip, and you get back a complete skill directory ready to share. -Before starting, read `references/conventions-checklist.md` and `references/example-adaptation.md`. The other reference files are specialized. Read `references/calibration-pattern.md` only if the source skill needs a calibration step, and `references/glossary-writing-guide.md` only if the converted skill produces output consumed by other skills. Do not read them upfront. +Before starting, read `references/conventions-checklist.md` and `references/example-adaptation.md`. Read `references/calibration-pattern.md` only if the source skill needs a calibration step. Do not read it upfront. --- @@ -104,7 +104,6 @@ Produce: 1. **references/example-output.md.** A complete example of what the skill produces when run with good input. This sets the quality ceiling. 2. **skillshelf.yaml.** The SkillShelf metadata file. Read `references/skillshelf-yaml-reference.md` for valid field values. -3. **references/glossary.md.** Only if the skill produces structured output that other skills consume as input. Most skills do not need this. If yours does, read `references/glossary-writing-guide.md` for the full specification. After sharing the example output, ask the user to review it. Explain that this example is what the AI will aim for when the skill runs, so the quality, tone, and level of detail should match what they'd actually want to use. diff --git a/skills/adapt-skill/references/conventions-checklist.md b/skills/adapt-skill/references/conventions-checklist.md index 5ff74b4..d3c6cac 100644 --- a/skills/adapt-skill/references/conventions-checklist.md +++ b/skills/adapt-skill/references/conventions-checklist.md @@ -66,9 +66,6 @@ Use this checklist during Phase 4 to review a skill against SkillShelf standards - [ ] References to other skills use natural-language names, not directory names - [ ] Primitives are recommended but not required (skill works without them) -- [ ] If output is consumed by other skills: `references/glossary.md` exists -- [ ] If output is consumed by other skills: output includes version marker (``) -- [ ] If glossary exists: follows the six-section structure (Overview, Document Structure, Section Hierarchy, Handling Missing Input, Field Definitions, Changelog) ## Edge Cases diff --git a/skills/adapt-skill/references/glossary-writing-guide.md b/skills/adapt-skill/references/glossary-writing-guide.md deleted file mode 100644 index 1fcc40d..0000000 --- a/skills/adapt-skill/references/glossary-writing-guide.md +++ /dev/null @@ -1,187 +0,0 @@ -# Glossary Writing Guide - -This is a condensed reference for producing glossaries. Use it when Phase 2 determines that the skill's output will be consumed by other skills. - ---- - -## When a Glossary Is Needed - -A glossary is needed when a skill produces structured output that other skills consume as input. The Brand Voice Extractor produces a voice profile that the PDP Copy Writer reads. Without a glossary, "Sparingly" in the voice profile means something different to every downstream consumer. - -Most skills do not need a glossary. If the output is only read by humans (collection descriptions, product copy, emails), skip the glossary. - -## Six-Section Structure - -Every glossary follows this structure in order: - -### 1. Overview - -```markdown -## Overview - -One of the inputs for this skill is a [document type], produced by the -[Producing Skill Name]. This glossary explains how that document is -structured: what each section contains, what values to expect, and how -to interpret them. - -**Producing skill:** [Skill Name] -**Current version:** v[X.X] -**Document type:** [What the output is called] -**Purpose:** [One sentence] -**Consumers:** [What kinds of skills use this document as input] -``` - -### 2. Document Structure - -Table of every section in the output. One row per section, one sentence per description. Do not omit sections. - -```markdown -## Document Structure - -| Section | Description | -|---|---| -| Voice Summary | 2-3 sentence overview of the brand's overall writing character. | -| Headlines | How the brand constructs headlines, with examples from source material. | -``` - -### 3. Section Hierarchy - -Priority order when guidance overlaps. Every section must appear. - -```markdown -## Section Hierarchy - -When multiple sections provide guidance that applies to the same output: - -1. What [Brand] Avoids (hard constraints). Never violate an avoidance rule. -2. Style Decisions (specific, binary rules). Override narrative guidance when they conflict. -3. Headlines / Product Framing (context, patterns, and nuance). -4. Voice Summary (directional). If a specific section contradicts it, follow the specific section. -5. Example Copy (illustrative). Reference for tone, not binding. -``` - -### 4. Handling Missing or Unexpected Input - -All four scenarios must be addressed: - -```markdown -## Handling Missing or Unexpected Input - -**A section says "unable to determine" or equivalent:** -Do not invent guidance. Fall back to general best practices. Note to the user -what was missing. - -**An expected section is missing entirely:** -Treat the same as "unable to determine." - -**The version marker is older than the current glossary version:** -Check the changelog. Apply current definitions, but account for structural -differences noted for that version. - -**The document was not generated by this skill:** -The user may have written their own version. Do not reject it. Extract -whatever guidance is present, map it to the fields you understand, and -produce output. Fall back to best practices where coverage is missing. -``` - -### 5. Field Definitions - -One entry for every section and field. - -**For narrative sections:** - -```markdown -### Voice Summary - -**What it represents:** The overall character of the brand's writing. -**What to expect:** 2-3 sentences. May reference specific patterns. -**How to apply:** Read first to calibrate approach. Specific sections override this. -``` - -**For table fields with shared vocabulary**, define values once with observable, measurable criteria: - -```markdown -### Shared Vocabulary - -| Value | Definition | -|---|---| -| "Always" or "Yes, always" | Apply in every instance, no exceptions. | -| "Never" or "No, never" | Zero instances in any output, any context. | -| "Freely" | Use where content naturally calls for it, no restriction. | -| "Sparingly" or "Rarely" | Maximum of one instance per complete piece of output. | -| "Sparingly, [context]" | Maximum one instance, only in the specified context. Zero outside it. | -| "Only in [context]" | Permitted in the specified context. Zero outside it. | -``` - -Then a compact reference table per field: - -```markdown -### Style Decisions: Field Reference - -| Field | What it represents | Possible values | Notes | -|---|---|---|---| -| Contractions | Whether the brand uses contractions | Shared vocabulary | "Yes, always" means every "do not" becomes "don't." | -| Exclamation marks | Frequency and context | Shared vocabulary | "Sparingly" = max one per complete piece of copy. | -``` - -**For free-text fields:** - -```markdown -### Customer Address - -**What it represents:** How the brand addresses the reader. -**Possible values:** Second person ("you"), imperative ("Run."), aspirational ("for runners who..."). -**How to apply:** Match exactly. This is one of the highest-impact style decisions. -``` - -### 6. Changelog - -Newest first. Enough detail that a downstream skill encountering an older document understands the differences. - -```markdown -## Changelog - -**v0.2** Added "Humor" field to Style Decisions table. Renamed -"Customer Tone" to "Customer Address" for clarity. - -**v0.1** Initial release. -``` - ---- - -## Writing Guidelines - -- Write for a model consuming the glossary at runtime, not a human reader. -- Define vocabulary with observable, measurable criteria. "No more than once per piece of output" over "use conservatively." -- Do not repeat the producing skill's generation instructions. Describe the output, not how it was created. -- Ground definitions in behavior: what a downstream skill should *do*, not what a value *means* in the abstract. -- If a field's meaning varies by downstream context, say so and describe what the downstream skill must decide. -- Keep it compact. Every sentence should help a downstream skill make a concrete decision. - -## Version Markers - -The producing skill stamps its output with an HTML comment: - -``` - -``` - -Increment the version when: -- The output format adds, removes, or renames sections. -- The value vocabulary changes (new options, redefined terms). - -Do not increment when: -- The analysis rubric improves but format and vocabulary stay the same. - -## Dual Use - -The producing skill may reference its own glossary during generation to ensure consistent field definitions. This is intentional: the glossary defines what valid values look like, which the producer needs just as much as the consumer. - -## Downstream Referencing - -When skills live in the same repo, downstream skills reference the upstream glossary by relative path: - -``` -Before generating output, read the glossary at -../[upstream-skill]/references/glossary.md -``` diff --git a/skills/adapt-skill/skillshelf.yaml b/skills/adapt-skill/skillshelf.yaml index 26aed55..fa9d2b5 100644 --- a/skills/adapt-skill/skillshelf.yaml +++ b/skills/adapt-skill/skillshelf.yaml @@ -39,8 +39,7 @@ output_schema: description: >- A complete SkillShelf skill directory containing SKILL.md with valid frontmatter, references/example-output.md demonstrating ceiling quality, - an optional references/glossary.md for skills whose output is consumed - downstream, and a skillshelf.yaml metadata sidecar. + and a skillshelf.yaml metadata sidecar. required_files: - SKILL.md - skillshelf.yaml diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 862492d..2fff91d 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -10,7 +10,7 @@ license: Apache-2.0 This skill helps users go from "I have an idea for a skill" to a complete, convention-compliant skill directory. It walks through understanding the task, planning the skill, writing and reviewing the SKILL.md, then producing the supporting files. -Before starting, read `references/conventions-checklist.md` and `references/example-output.md`. The other reference files are specialized. Read `references/calibration-pattern.md` only if the Phase 2 plan includes a calibration step, and `references/glossary-writing-guide.md` only if the plan calls for downstream consumption. Do not read them upfront. +Before starting, read `references/conventions-checklist.md` and `references/example-output.md`. Read `references/calibration-pattern.md` only if the Phase 2 plan includes a calibration step. Do not read it upfront. --- @@ -89,7 +89,6 @@ Produce: 1. **references/example-output.md.** A complete example of what the skill produces when run with good input. This sets the quality ceiling. 2. **skillshelf.yaml.** The SkillShelf metadata file. Read `references/skillshelf-yaml-reference.md` for valid field values. -3. **references/glossary.md.** Only if the skill produces structured output that other skills consume as input. Most skills do not need this. If yours does, read `references/glossary-writing-guide.md` for the full specification. After sharing the example output, ask the user to review it. Explain that this example is what the AI will aim for when the skill runs, so the quality, tone, and level of detail should match what they'd actually want to use. diff --git a/skills/write-skill/references/conventions-checklist.md b/skills/write-skill/references/conventions-checklist.md index 5ff74b4..d3c6cac 100644 --- a/skills/write-skill/references/conventions-checklist.md +++ b/skills/write-skill/references/conventions-checklist.md @@ -66,9 +66,6 @@ Use this checklist during Phase 4 to review a skill against SkillShelf standards - [ ] References to other skills use natural-language names, not directory names - [ ] Primitives are recommended but not required (skill works without them) -- [ ] If output is consumed by other skills: `references/glossary.md` exists -- [ ] If output is consumed by other skills: output includes version marker (``) -- [ ] If glossary exists: follows the six-section structure (Overview, Document Structure, Section Hierarchy, Handling Missing Input, Field Definitions, Changelog) ## Edge Cases diff --git a/skills/write-skill/references/glossary-writing-guide.md b/skills/write-skill/references/glossary-writing-guide.md deleted file mode 100644 index cf82783..0000000 --- a/skills/write-skill/references/glossary-writing-guide.md +++ /dev/null @@ -1,187 +0,0 @@ -# Glossary Writing Guide - -This is a condensed reference for producing glossaries. Use it when Phase 2 determines that the skill's output will be consumed by other skills. - ---- - -## When a Glossary Is Needed - -A glossary is needed when a skill produces structured output that other skills consume as input. The Brand Voice Extractor produces a voice profile that the PDP Copy Writer reads. Without a glossary, "Sparingly" in the voice profile means something different to every downstream consumer. - -Most skills do not need a glossary. If the output is only read by humans (collection descriptions, product copy, emails), skip the glossary. - -## Six-Section Structure - -Every glossary follows this structure in order: - -### 1. Overview - -```markdown -## Overview - -One of the inputs for this skill is a [document type], produced by the -[Producing Skill Name]. This glossary explains how that document is -structured: what each section contains, what values to expect, and how -to interpret them. - -**Producing skill:** [Skill Name] -**Current version:** v[X.X] -**Document type:** [What the output is called] -**Purpose:** [One sentence] -**Consumers:** [What kinds of skills use this document as input] -``` - -### 2. Document Structure - -Table of every section in the output. One row per section, one sentence per description. Do not omit sections. - -```markdown -## Document Structure - -| Section | Description | -|---|---| -| Voice Summary | 2-3 sentence overview of the brand's overall writing character. | -| Headlines | How the brand constructs headlines, with examples from source material. | -``` - -### 3. Section Hierarchy - -Priority order when guidance overlaps. Every section must appear. - -```markdown -## Section Hierarchy - -When multiple sections provide guidance that applies to the same output: - -1. What [Brand] Avoids (hard constraints). Never violate an avoidance rule. -2. Style Decisions (specific, binary rules). Override narrative guidance when they conflict. -3. Headlines / Product Framing (context, patterns, and nuance). -4. Voice Summary (directional). If a specific section contradicts it, follow the specific section. -5. Example Copy (illustrative). Reference for tone, not binding. -``` - -### 4. Handling Missing or Unexpected Input - -All four scenarios must be addressed: - -```markdown -## Handling Missing or Unexpected Input - -**A section says "unable to determine" or equivalent:** -Do not invent guidance. Fall back to general best practices. Note to the user -what was missing. - -**An expected section is missing entirely:** -Treat the same as "unable to determine." - -**The version marker is older than the current glossary version:** -Check the changelog. Apply current definitions, but account for structural -differences noted for that version. - -**The document was not generated by this skill:** -The user may have written their own version. Do not reject it. Extract -whatever guidance is present, map it to the fields you understand, and -produce output. Fall back to best practices where coverage is missing. -``` - -### 5. Field Definitions - -One entry for every section and field. - -**For narrative sections:** - -```markdown -### Voice Summary - -**What it represents:** The overall character of the brand's writing. -**What to expect:** 2-3 sentences. May reference specific patterns. -**How to apply:** Read first to calibrate approach. Specific sections override this. -``` - -**For table fields with shared vocabulary**, define values once with observable, measurable criteria: - -```markdown -### Shared Vocabulary - -| Value | Definition | -|---|---| -| "Always" or "Yes, always" | Apply in every instance, no exceptions. | -| "Never" or "No, never" | Zero instances in any output, any context. | -| "Freely" | Use where content naturally calls for it, no restriction. | -| "Sparingly" or "Rarely" | Maximum of one instance per complete piece of output. | -| "Sparingly, [context]" | Maximum one instance, only in the specified context. Zero outside it. | -| "Only in [context]" | Permitted in the specified context. Zero outside it. | -``` - -Then a compact reference table per field: - -```markdown -### Style Decisions: Field Reference - -| Field | What it represents | Possible values | Notes | -|---|---|---|---| -| Contractions | Whether the brand uses contractions | Shared vocabulary | "Yes, always" means every "do not" becomes "don't." | -| Exclamation marks | Frequency and context | Shared vocabulary | "Sparingly" = max one per complete piece of copy. | -``` - -**For free-text fields:** - -```markdown -### Customer Address - -**What it represents:** How the brand addresses the reader. -**Possible values:** Second person ("you"), imperative ("Run."), aspirational ("for runners who..."). -**How to apply:** Match exactly. This is one of the highest-impact style decisions. -``` - -### 6. Changelog - -Newest first. Enough detail that a downstream skill encountering an older document understands the differences. - -```markdown -## Changelog - -**v0.2:** Added "Humor" field to Style Decisions table. Renamed -"Customer Tone" to "Customer Address" for clarity. - -**v0.1:** Initial release. -``` - ---- - -## Writing Guidelines - -- Write for a model consuming the glossary at runtime, not a human reader. -- Define vocabulary with observable, measurable criteria. "No more than once per piece of output" over "use conservatively." -- Do not repeat the producing skill's generation instructions. Describe the output, not how it was created. -- Ground definitions in behavior: what a downstream skill should *do*, not what a value *means* in the abstract. -- If a field's meaning varies by downstream context, say so and describe what the downstream skill must decide. -- Keep it compact. Every sentence should help a downstream skill make a concrete decision. - -## Version Markers - -The producing skill stamps its output with an HTML comment: - -``` - -``` - -Increment the version when: -- The output format adds, removes, or renames sections. -- The value vocabulary changes (new options, redefined terms). - -Do not increment when: -- The analysis rubric improves but format and vocabulary stay the same. - -## Dual Use - -The producing skill may reference its own glossary during generation to ensure consistent field definitions. This is intentional: the glossary defines what valid values look like, which the producer needs just as much as the consumer. - -## Downstream Referencing - -When skills live in the same repo, downstream skills reference the upstream glossary by relative path: - -``` -Before generating output, read the glossary at -../[upstream-skill]/references/glossary.md -``` diff --git a/skills/write-skill/skillshelf.yaml b/skills/write-skill/skillshelf.yaml index d2eb67c..7cf6576 100644 --- a/skills/write-skill/skillshelf.yaml +++ b/skills/write-skill/skillshelf.yaml @@ -39,8 +39,7 @@ output_schema: type: object description: >- A complete skill directory containing SKILL.md with valid frontmatter, - references/example-output.md demonstrating ceiling quality, an optional - references/glossary.md for skills whose output is consumed downstream, + references/example-output.md demonstrating ceiling quality, and a skillshelf.yaml metadata sidecar. required_files: - SKILL.md @@ -66,9 +65,8 @@ faq: - question: What files does it produce? answer: >- A SKILL.md (the main skill file with instructions), an example - output file showing what the skill produces at its best, a - skillshelf.yaml metadata file, and optionally a glossary if the - skill's output is consumed by other skills. + output file showing what the skill produces at its best, and a + skillshelf.yaml metadata file. - question: Can I use this for non-ecommerce skills? answer: >- Yes. The SKILL.md format works for any domain. The skill will note