From 2ddb07a1f5f4d6f3e8ec312126ae4b6e08357ee5 Mon Sep 17 00:00:00 2001 From: kitzy Date: Tue, 28 Jul 2026 11:22:27 -0400 Subject: [PATCH] Wire content-style into the fleet-guide-formatting skill and require endmatter (#49698) **Related issue:** N/A # Checklist for submitter - [x] N/A: this is a `.claude/skills` change (Claude Code tooling), not a user-visible product change. No `changes/` entry, tests, migrations, config settings, or fleetd/orbit changes apply. ## Summary Updates the `fleet-guide-formatting` skill based on review feedback from the first guide written with it (#49681). Two problems came up in that review: **The skill didn't run `content-style`.** It cross-referenced `content-style` as the place voice and grammar rules live, but phrased it as "use that skill instead," which read as someone else's job. The result was a structurally correct guide that still needed a separate style pass. `content-style` is now a required companion, called out in the frontmatter description (so it's visible at trigger time, not just after loading), in a dedicated section near the top, in both the writing and auditing workflows, and as an audit checklist item. **Endmatter wasn't being generated.** The skeleton listed endmatter as "required" but never said the skill is what writes it, so drafts came back without the `` tags and the author had to notice and add them. There's now an "Endmatter is not optional" section with per-field guidance, and a matching comment above the block in `references/template.md`. The existing don't-fabricate-the-author rule is preserved: `authorFullName`, `authorGitHubUsername`, and `publishedOn` stay as placeholders to be filled in rather than guessed. ## Also in this PR The skill files themselves didn't follow `content-style`, which is a bad look for a skill whose main change is "always run `content-style`." Ran all three files through it: - Removed ~40 em dashes (the connector-after-a-bold-label pattern), replaced with periods or colons. - Renamed two headings off `-ing` verbs per the headings rule: "Writing a new guide" to "Write a new guide," "Auditing or retrofitting an existing guide" to "Audit or retrofit an existing guide." - Fixed quote punctuation to sit outside the quotes per the handbook. This accounts for most of the `canonical-examples.md` diff. - Cut filler ("actually," "very"), added missing Oxford commas, and replaced one use of "agent" (on the avoid list) with `fleetd`. Also fixed a content bug found while editing: the "what guides never have" note about Conclusion/Summary sections had drifted out of "The skeleton" section, where it belongs. ## Testing Not applicable, no automated tests cover skill markdown. Verified by grep that the files contain no em dashes outside backticked search targets, no filler or hype words from the avoid lists, no banned terminology, and that all headings are sentence case. --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../skills/fleet-guide-formatting/SKILL.md | 106 +++++++++++------- .../references/canonical-examples.md | 70 ++++++------ .../references/template.md | 13 ++- 3 files changed, 106 insertions(+), 83 deletions(-) diff --git a/.claude/skills/fleet-guide-formatting/SKILL.md b/.claude/skills/fleet-guide-formatting/SKILL.md index 365a71e298..7fc3dfeca6 100644 --- a/.claude/skills/fleet-guide-formatting/SKILL.md +++ b/.claude/skills/fleet-guide-formatting/SKILL.md @@ -1,84 +1,104 @@ --- name: fleet-guide-formatting -description: Ensure Fleet how-to guides (articles/ with meta category "guides") follow the concise, step-by-step structure established by Fleet's best guides — short problem statement, prerequisites, inline gotcha callouts, task-based or numbered steps, optional verify/troubleshoot sections, no filler. Use when writing a new guide, converting a draft into a guide, or auditing/retrofitting an existing guide's structure. Trigger on requests like "write a guide for X," "format this as a guide," "check guide formatting," "audit our guides," "does this follow our guide structure," or when editing a file under articles/ tagged category "guides". This skill governs STRUCTURE — what sections exist, in what order, how steps are shown. For voice, grammar, and word choice, use the content-style skill instead; the two are meant to be used together. Do NOT use this for articles, case studies, or announcements — those are different meta categories with their own conventions (articles use the fleet-article-formatting skill). If the piece's meta category is anything other than "guides", this format does not apply. A strong signal this skill applies: the draft reads like an opinion piece, roundup, or narrative with no concrete steps an admin could follow — that's the exact anti-pattern this skill exists to catch. +description: Ensure Fleet how-to guides (articles/ with meta category "guides") follow the concise, step-by-step structure established by Fleet's best guides: short problem statement, prerequisites, inline gotcha callouts, task-based or numbered steps, optional verify/troubleshoot sections, no filler. Use when writing a new guide, converting a draft into a guide, or auditing/retrofitting an existing guide's structure. Trigger on requests like "write a guide for X", "format this as a guide", "check guide formatting", "audit our guides", "does this follow our guide structure", or when editing a file under articles/ tagged category "guides". This skill governs STRUCTURE: what sections exist, in what order, how steps are shown. It does NOT replace the content-style skill. Always run content-style over the prose as part of using this skill, in the same session, before calling a guide done. Do NOT use this for articles, case studies, or announcements, which are different meta categories with their own conventions (articles use the fleet-article-formatting skill). If the piece's meta category is anything other than "guides", this format does not apply. A strong signal this skill applies: the draft reads like an opinion piece, roundup, or narrative with no concrete steps an admin could follow. That's the exact anti-pattern this skill exists to catch. allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git diff*), Bash(git status*) effort: medium --- # Fleet guide formatting -A Fleet guide gets an admin to step 1, step 2, done. It is not a thought piece, a roundup, or an essay that happens to live in `articles/`. This skill exists to do one job: let an admin find the exact step they need without reading past it. Every rule below serves that — this skill captures the structural skeleton established across Fleet's best guides and gives a checklist for writing new guides or auditing existing ones. +A Fleet guide gets an admin to step 1, step 2, done. It is not a thought piece, a roundup, or an essay that happens to live in `articles/`. This skill exists to do one job: let an admin find the exact step they need without reading past it. Every rule below serves that. This skill captures the structural skeleton established across Fleet's best guides and gives a checklist for writing new guides or auditing existing ones. -This skill is about **structure only**: which sections exist, in what order, how steps are shown. For voice, tone, and grammar mechanics (sentence case, em dashes, filler words, Fleet terminology), use the `content-style` skill and its `references/style-rules.md` — apply both together when writing or reviewing a guide. +This skill is about **structure only**: which sections exist, in what order, how steps are shown. Voice, tone, and grammar mechanics live in the `content-style` skill. -## Scope — when this skill applies +## Required: run content-style in the same session -This format is for Fleet **guides only** — pieces published under ``: step-by-step procedures an admin follows to accomplish one task. +Structure alone is not enough to ship a guide. **Every time you use this skill, invoke the `content-style` skill over the guide's prose before you hand the draft back.** Don't treat it as a suggestion the author can pick up later, and don't substitute your own recollection of the rules for loading the skill. + +- **Writing a new guide:** load `content-style` before drafting, so the prose is right the first time, then re-run its review pass on the finished draft. +- **Auditing or retrofitting a guide:** run `content-style` over the file as part of the same audit. Report style findings alongside the structural ones. + +## Scope: when this skill applies + +This format is for Fleet **guides only**, meaning pieces published under ``: step-by-step procedures an admin follows to accomplish one task. It does **not** apply to: -- **Articles** (`category` = `articles`) — thought-leadership, how-to essays, and comparison pieces. Use the `fleet-article-formatting` skill instead. +- **Articles** (`category` = `articles`): thought-leadership, how-to essays, and comparison pieces. Use the `fleet-article-formatting` skill instead. - **Case studies** (`category` = `success stories`) - **Announcements** (`category` = `announcements`) -Before applying this format, check the piece's `` value (or ask the author which category it's destined for). If it isn't `guides`, stop and don't impose this structure — flag the mismatch instead (see the mistagged-piece check in the audit checklist below). +Before applying this format, check the piece's `` value, or ask the author which category it's destined for. If it isn't `guides`, stop and don't impose this structure. Flag the mismatch instead (see the mistagged-piece check in the audit checklist below). ## Canonical examples These are the reference guides this skill is derived from. Read one or two before writing a new guide if you want the pattern in context: -- `articles/deploy-fleet-on-docker-compose.md` — task-headed sections in doing-order, "Optional:" labeled steps, a Troubleshooting section with bold symptom lead-ins. -- `articles/migrate-fleet-server.md` — "Before you begin" prerequisites with inline risk callouts, sequential H2 steps, a "Verify the migration" section, Troubleshooting at the end. -- `articles/enforce-macos-updates-per-major-version.md` — explicit "Step 1 / Step 2 / Step 3" H2 headings because the count itself matters, inline `>` Note/Warning callouts placed exactly where they bite, a numbered UI click-path nested inside a step. -- `articles/set-device-hostname-via-fleet-api.md` — tight prerequisites, numbered click-path-style steps for an API workflow, bold endpoint/header labels instead of prose. -- `articles/manage-bootstrap-package-with-gitops.md` — the shortest possible version of the skeleton: intro, prerequisites, three action-headed steps, a "More information" link, done. -- `articles/autopkg-with-fleet.md` — branching steps (direct mode vs. GitOps mode) handled as sibling H2 sections, each self-contained; a "Get help" section instead of "Further reading" because the tool is community-maintained. -- `articles/canary-fleet-for-fleetd-updates.md` — leads with the *problem* before the fix, a `>` callout for a licensing gotcha, numbered steps under one H2 "Set up your canary fleet" rather than one H2 per step. -- `articles/managed-migration-assistant-mac-to-mac-migration-with-fleet.md` — "Requirements" then "What transfers and what doesn't" (a reference table-in-prose the reader needs before touching config) before any steps; branches for GitOps vs. UI paths; "Further reading" at the end. +- `articles/deploy-fleet-on-docker-compose.md`: task-headed sections in doing-order, "Optional:" labeled steps, a Troubleshooting section with bold symptom lead-ins. +- `articles/migrate-fleet-server.md`: "Before you begin" prerequisites with inline risk callouts, sequential H2 steps, a "Verify the migration" section, Troubleshooting at the end. +- `articles/enforce-macos-updates-per-major-version.md`: explicit "Step 1 / Step 2 / Step 3" H2 headings because the count itself matters, inline `>` Note/Warning callouts placed exactly where they bite, a numbered UI click-path nested inside a step. +- `articles/set-device-hostname-via-fleet-api.md`: tight prerequisites, numbered click-path-style steps for an API workflow, bold endpoint/header labels instead of prose. +- `articles/manage-bootstrap-package-with-gitops.md`: the shortest possible version of the skeleton. Intro, prerequisites, three action-headed steps, a "More information" link, done. +- `articles/autopkg-with-fleet.md`: branching steps (direct mode vs. GitOps mode) handled as sibling H2 sections, each self-contained, and a "Get help" section instead of "Further reading" because the tool is community-maintained. +- `articles/canary-fleet-for-fleetd-updates.md`: leads with the *problem* before the fix, a `>` callout for a licensing gotcha, numbered steps under one H2 "Set up your canary fleet" rather than one H2 per step. +- `articles/managed-migration-assistant-mac-to-mac-migration-with-fleet.md`: "Requirements" then "What transfers and what doesn't" (a reference table-in-prose the reader needs before touching config) before any steps, branches for GitOps vs. UI paths, and "Further reading" at the end. -**Watch for the mistagged case:** a piece tagged `category: guides` with no prerequisites, no numbered or task-headed steps, and a closing "recap" or "priorities" list instead of stopping after the last practical action. That's an article that got the guides tag, not a guide. Use this as the litmus test in the audit checklist below — see `references/canonical-examples.md` for a full breakdown of the pattern. +**Watch for the mistagged case:** a piece tagged `category: guides` with no prerequisites, no numbered or task-headed steps, and a closing "recap" or "priorities" list instead of stopping after the last practical action. That's an article that got the guides tag, not a guide. Use this as the litmus test in the audit checklist below. See `references/canonical-examples.md` for a full breakdown of the pattern. ## The skeleton -1. **H1 title** — sentence case, task-verb-led: "Deploy Fleet with Docker Compose," "Migrate Fleet server to a new deployment," "Manage bootstrap packages with GitOps." When introducing a named Apple/Fleet feature, "Feature name: task" also works: "Managed Migration Assistant: Mac-to-Mac migration with Fleet." -2. **Opening — no heading** — one short paragraph (rarely two). States the problem and what the reader ends up with. No history lesson, no "in today's landscape." State scope limits up front if the guide doesn't cover every scenario. -3. **Prerequisites** — heading is "Prerequisites," "Requirements," "What you'll need," or "Before you begin." A bulleted list of concrete, checkable requirements (versions, access level, artifacts in hand). Version-dependent requirements go inline in the bullet, not a separate paragraph. -4. **Gotcha callouts, threaded inline** — `> **Note:**` or `> **Warning:**` blockquotes placed right next to the step or requirement they affect. Never a standalone "Gotchas" section collecting them all at the top. -5. **Steps** — pick the shape that fits the task, don't force one pattern: +1. **H1 title.** Sentence case, task-verb-led: "Deploy Fleet with Docker Compose", "Migrate Fleet server to a new deployment", "Manage bootstrap packages with GitOps". When introducing a named Apple or Fleet feature, "Feature name: task" also works: "Managed Migration Assistant: Mac-to-Mac migration with Fleet". +2. **Opening, no heading.** One short paragraph, rarely two. States the problem and what the reader ends up with. No history lesson, no "in today's landscape". State scope limits up front if the guide doesn't cover every scenario. +3. **Prerequisites.** The heading is "Prerequisites", "Requirements", "What you'll need", or "Before you begin". A bulleted list of concrete, checkable requirements: versions, access level, and artifacts in hand. Version-dependent requirements go inline in the bullet, not in a separate paragraph. +4. **Gotcha callouts, threaded inline.** Use `> **Note:**` or `> **Warning:**` blockquotes placed right next to the step or requirement they affect. Never a standalone "Gotchas" section collecting them all at the top. +5. **Steps.** Pick the shape that fits the task, don't force one pattern: - Sequential H2 sections named as actions, in doing-order, each with H3 sub-steps if needed. - Explicit "Step 1: ...", "Step 2: ..." H2 headings when the count of steps itself matters. - - A numbered click-path list inside one section, when the action is "go click through these screens" — bold the UI element names. + - A numbered click-path list inside one section, when the action is "go click through these screens". Bold the UI element names. Every step: imperative mood, active voice, one action per step or paragraph. -6. **Verify** (when success isn't obviously visible) — short section confirming the change took effect, often itself a numbered click-path. -7. **Troubleshooting** (when failure modes are known) — heading "Troubleshoot" or "Troubleshooting." Each item leads with a **bold symptom** acting as a pseudo-heading, followed immediately by the fix. -8. **Further reading / Related resources / Get help** (optional) — a short link list at the very end, before the endmatter. -9. **Endmatter** — required. Matches the template in `content-style/references/content-types.md`, `category` set to `guides`, `articleTitle` matching the H1 exactly. +6. **Verify** (when success isn't obviously visible). A short section confirming the change took effect, often itself a numbered click-path. +7. **Troubleshooting** (when failure modes are known). The heading is "Troubleshoot" or "Troubleshooting". Each item leads with a **bold symptom** acting as a pseudo-heading, followed immediately by the fix. +8. **Further reading / Related resources / Get help** (optional). A short link list at the end, before the endmatter. +9. **Endmatter.** Required, and you write it. See "Endmatter is not optional" below. -What guides never have: a "Conclusion," "Summary," or "Wrapping up" section that restates what was just said. The guide ends after the last practical section. +What guides never have: a "Conclusion", "Summary", or "Wrapping up" section that restates what was said. The guide ends after the last practical section. -## Writing a new guide +## Endmatter is not optional -1. Confirm it's actually a guide: is there a concrete task with real prerequisites and steps? If the content is analysis, opinion, or a roundup with no procedure, it belongs in `category: articles`, not `guides` — say so rather than forcing the skeleton onto it. -2. Copy `references/template.md` as a starting skeleton and fill it in section by section. -3. Write the opening last if it helps — it's easier to state the problem precisely once the steps are settled. -4. Run the `content-style` skill's checklist over the prose (voice, sentence case, no em dashes, no filler, Fleet terminology) before finishing. -5. Self-check against the audit checklist below. +Every guide ends with the `` block from `.claude/skills/content-style/references/content-types.md`. **Emit it yourself as part of the draft.** A guide handed back without endmatter is incomplete, and the author shouldn't have to notice it's missing and paste it in. `references/template.md` ends with the block already filled in for guides. Keep it there. -## Auditing or retrofitting an existing guide +Fill it in like this: -Read the file, then check each item. Report findings by section, don't just say "needs work": +- `articleTitle`: matches the H1 exactly, character for character. +- `category`: always `guides` for this skill. If it should be anything else, this skill doesn't apply (see Scope). +- `description`: 1-2 sentences, 150 characters max, factual and benefit-driven. Write this one. It's the only field you can derive from the guide itself. +- `authorFullName`, `authorGitHubUsername`, and `publishedOn`: **never fabricate these.** If you don't know the author or the intended publish date, leave the placeholder in place and tell the author which fields they need to fill in. -- [ ] H1 is sentence case and task-verb-led (or "Feature name: task"). -- [ ] Opening is one short paragraph (two at most), states problem + outcome, no throat-clearing intro. -- [ ] Has a prerequisites/requirements section if the task depends on a version, access level, or artifact. +## Write a new guide + +1. Confirm it's a guide: is there a concrete task with real prerequisites and steps? If the content is analysis, opinion, or a roundup with no procedure, it belongs in `category: articles`, not `guides`. Say so rather than forcing the skeleton onto it. +2. Load the `content-style` skill now, before drafting, so the prose is right the first time. +3. Copy `references/template.md` as a starting skeleton and fill it in section by section, endmatter included. +4. Write the opening last if it helps. It's easier to state the problem precisely once the steps are settled. +5. Run the `content-style` review pass over the finished prose. Search for `—` and rewrite every hit in prose (ignore code blocks and inline code). +6. Self-check against the audit checklist below. + +## Audit or retrofit an existing guide + +Read the file, run the `content-style` skill over it, then check each item. Report findings by section, don't just say "needs work": + +- [ ] H1 is sentence case and task-verb-led, or "Feature name: task". +- [ ] Opening is one short paragraph, two at most, states the problem and the outcome, and has no throat-clearing intro. +- [ ] Has a prerequisites or requirements section if the task depends on a version, access level, or artifact. - [ ] Gotchas are `>` callouts placed next to the step they affect, not buried in a paragraph or dumped in their own section. - [ ] Steps are numbered or task-headed, not narrated as flowing prose the reader has to parse for actions. - [ ] Each step is imperative mood, one action. -- [ ] Bold is used only for UI elements, field/file names, and troubleshooting symptom lead-ins. Never decorative. +- [ ] Bold is used only for UI elements, field and file names, and troubleshooting symptom lead-ins. Never decorative. - [ ] Has a Verify section if success or failure isn't obvious from the last step. -- [ ] Troubleshooting entries (if present) lead with a bold symptom, not a generic "Issue:" label. -- [ ] Ends after the last practical section. No summary/conclusion coda. -- [ ] Endmatter present and correct: category is `guides`, `articleTitle` matches the H1 exactly. -- [ ] **If it has no prerequisites and no concrete steps**, it's not a guide. Recommend recategorizing to `articles` or restructuring around an actual procedure — don't just reshuffle headings on a piece that has no steps to number. +- [ ] Troubleshooting entries, if present, lead with a bold symptom, not a generic "Issue:" label. +- [ ] Ends after the last practical section. No summary or conclusion coda. +- [ ] Endmatter present and complete: all six `` tags, `category` is `guides`, `articleTitle` matches the H1 exactly, and `description` is under 150 characters. Author and date are real, or flagged as needing the author's input. Never invented. +- [ ] `content-style` was run over the prose in this session, and its findings are reported alongside the structural ones. +- [ ] **If it has no prerequisites and no concrete steps**, it's not a guide. Recommend recategorizing to `articles` or restructuring around a real procedure. Don't just reshuffle headings on a piece that has no steps to number. For a deeper structural breakdown of each canonical example and the mistagged-article anti-pattern, see `references/canonical-examples.md`. diff --git a/.claude/skills/fleet-guide-formatting/references/canonical-examples.md b/.claude/skills/fleet-guide-formatting/references/canonical-examples.md index 369dcfb20b..71c3e27e10 100644 --- a/.claude/skills/fleet-guide-formatting/references/canonical-examples.md +++ b/.claude/skills/fleet-guide-formatting/references/canonical-examples.md @@ -5,76 +5,76 @@ Detailed notes on how each reference guide implements the skeleton from `SKILL.m ## articles/deploy-fleet-on-docker-compose.md - Opening states the outcome and time-to-complete in one sentence: "You'll have a Fleet instance running with MySQL and Redis in about 15 minutes." -- Prerequisites heading: "What you'll need." -- Steps are sequential H2 sections named as actions: "Download the configuration files" → "Configure your environment" → "Configure TLS" → "Start Fleet" → "Access Fleet." -- Branching handled with bold inline labels inside one section rather than separate headings: "**Option 1: Reverse proxy or load balancer handles TLS**" / "**Option 2: Fleet handles TLS directly**," with an explicit "Skip to 'Start Fleet' below" for readers who don't need option 2. -- Optional steps are labeled in the heading itself: "Optional: Add your license key," "Optional: Configure S3 storage." +- Prerequisites heading: "What you'll need". +- Steps are sequential H2 sections named as actions: "Download the configuration files" → "Configure your environment" → "Configure TLS" → "Start Fleet" → "Access Fleet". +- Branching handled with bold inline labels inside one section rather than separate headings: "**Option 1: Reverse proxy or load balancer handles TLS**" and "**Option 2: Fleet handles TLS directly**", with an explicit "Skip to 'Start Fleet' below" for readers who don't need option 2. +- Optional steps are labeled in the heading itself: "Optional: Add your license key", "Optional: Configure S3 storage". - Troubleshooting: each item is a **bold symptom** used as a pseudo-heading ("**Permission denied errors on /logs**"), followed directly by the fix, sometimes with a code block. -- Ends with "Production considerations" — a bulleted list of hardening tips, not a summary. Still practical, not a recap. +- Ends with "Production considerations", a bulleted list of hardening tips rather than a summary. Still practical, not a recap. ## articles/migrate-fleet-server.md - Opening explicitly scopes the guide down: "Every environment is different, so this guide focuses on the essential steps rather than trying to cover every possible scenario." This lets the guide skip edge cases without apologizing for it later. -- Prerequisites heading: "Before you begin," bulleted, each bullet bolds the action verb ("**Back up your database.**", "**Plan for downtime.**", "**Save your `FLEET_SERVER_PRIVATE_KEY`.**"). -- The single highest-risk gotcha (losing the private key) is stated in the prerequisites bullet, then repeated verbatim as its own numbered item inside the "Set up the new Fleet instance" step, and repeated a third time in Troubleshooting. Repetition at the point of action is intentional for genuinely destructive mistakes — don't treat "don't repeat yourself" as an absolute in this case. -- Steps are sequential H2 sections: "Stop the Fleet server" → "Back up the MySQL database" → "Set up the new Fleet instance" → "Import the database" → "Configure S3 storage (if applicable)" → "Start Fleet on the new instance" → "Update DNS." -- Explicit "Verify the migration" section, itself a numbered list of checks, not just "you're done." +- Prerequisites heading: "Before you begin", bulleted, each bullet bolds the action verb ("**Back up your database.**", "**Plan for downtime.**", "**Save your `FLEET_SERVER_PRIVATE_KEY`.**"). +- The single highest-risk gotcha (losing the private key) is stated in the prerequisites bullet, then repeated verbatim as its own numbered item inside the "Set up the new Fleet instance" step, and repeated a third time in Troubleshooting. Repetition at the point of action is intentional for genuinely destructive mistakes. Don't treat "don't repeat yourself" as an absolute in this case. +- Steps are sequential H2 sections: "Stop the Fleet server" → "Back up the MySQL database" → "Set up the new Fleet instance" → "Import the database" → "Configure S3 storage (if applicable)" → "Start Fleet on the new instance" → "Update DNS". +- Explicit "Verify the migration" section, itself a numbered list of checks, not just "you're done". - "Additional notes" section between Verify and Troubleshooting holds true-but-not-actionable-right-now facts (Redis doesn't need migration, secrets live in MySQL). This is a legitimate fourth slot when a guide has caveats that aren't gotchas tied to a specific step and aren't failure modes either. - Troubleshooting: bold symptom lead-ins as sub-headings within prose, each followed by a bulleted fix list. ## articles/enforce-macos-updates-per-major-version.md -- Prerequisites bullets are conditioned on Fleet version ("Fleet v4.86 or earlier: ... Fleet v4.87 or later: this flag is enabled by default. No action needed.") — version-gating lives inline in the bullet, not as a separate compatibility table. -- A `> **Warning:**` callout sits directly after prerequisites because using this guide's approach alongside a conflicting built-in feature breaks devices — the warning is positioned before the reader can make the mistake, not after. -- A short "How it works" H2 explains the mechanism in two sentences before any steps — this is a legitimate extra section when the "why this works" isn't obvious from the task name alone. -- Steps use explicit "Step 1: ...", "Step 2: ...", "Step 3: ..." H2 headings because the guide is fundamentally "create N things, once per OS version," and the count is the organizing structure. +- Prerequisites bullets are conditioned on Fleet version ("Fleet v4.86 or earlier: ... Fleet v4.87 or later: this flag is enabled by default. No action needed."). Version-gating lives inline in the bullet, not as a separate compatibility table. +- A `> **Warning:**` callout sits directly after prerequisites because using this guide's approach alongside a conflicting built-in feature breaks devices. The warning is positioned before the reader can make the mistake, not after. +- A short "How it works" H2 explains the mechanism in two sentences before any steps. This is a legitimate extra section when the "why this works" isn't obvious from the task name alone. +- Steps use explicit "Step 1: ...", "Step 2: ...", "Step 3: ..." H2 headings because the guide is fundamentally "create N things, once per OS version", and the count is the organizing structure. - A `> **Note:**` callout is nested inside Step 1, immediately after the content that would trigger the problem it describes (a version-already-current error), including the literal error text the reader will see. -- A numbered UI click-path list is nested inside Step 3 for the "Using the Fleet UI" path, sitting next to a code block for the "Using GitOps" path as a sibling H3 — same step, two execution methods, not two different steps. +- A numbered UI click-path list is nested inside Step 3 for the "Using the Fleet UI" path, sitting next to a code block for the "Using GitOps" path as a sibling H3. Same step, two execution methods, not two different steps. - "Verify" is its own H2 with a numbered click-path. - Ends with "Related resources" as a plain link list. ## articles/set-device-hostname-via-fleet-api.md -- Prerequisites are three bullets, all concrete artifacts the reader must already have (token, serial number, enrollment state) — no soft prerequisites like "familiarity with APIs." -- Steps are sequential H2 sections matching the literal API call sequence: "Get the host UUID" → "Create the rename command" → "Base64 encode the command" → "Send the command." -- Bold labels replace sub-headings for structured request/response data: "**Endpoint:**", "**Headers:**", "**Body:**" — this is the right pattern for API guides specifically, in place of prose description of the HTTP call. -- A callout about a strict requirement (`CommandUUID` must be unique) is placed as a **bold-lead sentence inline**, not a blockquote — blockquotes aren't mandatory for every gotcha; a bold lead sentence works when the gotcha is one sentence and directly inside the step it affects. -- No Verify or Troubleshooting section — appropriate because the guide is a single API call with an obvious pass/fail (the request either 200s or it doesn't), and there's nothing failure-prone enough to warrant one. Don't add sections the task doesn't need. +- Prerequisites are three bullets, all concrete artifacts the reader must already have (token, serial number, enrollment state). No soft prerequisites like "familiarity with APIs". +- Steps are sequential H2 sections matching the literal API call sequence: "Get the host UUID" → "Create the rename command" → "Base64 encode the command" → "Send the command". +- Bold labels replace sub-headings for structured request/response data: "**Endpoint:**", "**Headers:**", "**Body:**". This is the right pattern for API guides specifically, in place of prose description of the HTTP call. +- A callout about a strict requirement (`CommandUUID` must be unique) is placed as a **bold-lead sentence inline**, not a blockquote. Blockquotes aren't mandatory for every gotcha; a bold lead sentence works when the gotcha is one sentence and directly inside the step it affects. +- No Verify or Troubleshooting section, which is appropriate because the guide is a single API call with an obvious pass/fail (the request either 200s or it doesn't), and there's nothing failure-prone enough to warrant one. Don't add sections the task doesn't need. ## articles/manage-bootstrap-package-with-gitops.md - The shortest example: intro (2 sentences) → one `>` Note callout (fleets can't share bootstrap packages) → Prerequisites → three action-headed H2 steps → "More information" link. No Verify, no Troubleshooting. -- Demonstrates that the skeleton compresses cleanly for a small task — don't pad a three-step guide with a Verify or Troubleshooting section just to look complete. +- Demonstrates that the skeleton compresses cleanly for a small task. Don't pad a three-step guide with a Verify or Troubleshooting section just to look complete. ## articles/autopkg-with-fleet.md - Opening explains what the third-party tool is before anything else, since the reader may not know it, and explicitly disclaims official support: "It's not an official Fleet product and isn't directly supported by Fleet." -- Two execution modes ("Direct mode" and "GitOps mode") are siblings H2s, each self-contained with its own prerequisites subsection ("Additional prerequisites for GitOps mode") and its own steps — rather than one shared step list with branches inside it. Use sibling H2 branches (as here) when the two paths diverge enough to need their own sub-steps; use inline bold-labeled options (as in the Docker Compose TLS example) when the branch is a single short choice. -- A `>` callout justifying a design decision ("Why S3?") is placed where the reader would otherwise ask "why not just upload directly," answering the objection instead of ignoring it. -- Ends with "Get help" instead of "Further reading" because the tool is community-maintained — the section name should match what the reader actually needs (support channels, not background reading). +- Two execution modes ("Direct mode" and "GitOps mode") are sibling H2s, each self-contained with its own prerequisites subsection ("Additional prerequisites for GitOps mode") and its own steps, rather than one shared step list with branches inside it. Use sibling H2 branches, as here, when the two paths diverge enough to need their own sub-steps. Use inline bold-labeled options, as in the Docker Compose TLS example, when the branch is a single short choice. +- A `>` callout justifying a design decision ("Why S3?") is placed where the reader would otherwise ask "why not just upload directly", answering the objection instead of ignoring it. +- Ends with "Get help" instead of "Further reading" because the tool is community-maintained. The section name should match what the reader needs: support channels, not background reading. ## articles/canary-fleet-for-fleetd-updates.md -- Opens by naming the problem (EDRs flagging fleetd) for three sentences before naming the fix — appropriate when the reader may not yet believe they need this guide. Contrast with `set-device-hostname-via-fleet-api.md`, which states the task in sentence one because there's no motivating problem to sell. +- Opens by naming the problem (EDRs flagging fleetd) for three sentences before naming the fix. This is appropriate when the reader may not yet believe they need this guide. Contrast with `set-device-hostname-via-fleet-api.md`, which states the task in sentence one because there's no motivating problem to sell. - A `>` callout for a licensing gate ("`update_channels` is only available in Fleet Premium.") sits right after the concept explanation and before the steps, so a Free-tier reader doesn't follow steps that won't work for them. -- Steps are a numbered list nested under a single H2 ("Set up your canary fleet") rather than one H2 per step — appropriate for a short, three-item sequence that doesn't need step-level anchors. -- Closing section ("Start small, catch problems early") reads like a summary but earns its place by adding new practical framing (pick one device per platform, watch for updates) rather than restating prior sentences. This is the narrow exception to "no conclusion section" — allowed only when the closing paragraph still tells the reader what to do next, not just that they've reached the end. +- Steps are a numbered list nested under a single H2 ("Set up your canary fleet") rather than one H2 per step, which suits a short, three-item sequence that doesn't need step-level anchors. +- Closing section ("Start small, catch problems early") reads like a summary but earns its place by adding new practical framing (pick one device per platform, watch for updates) rather than restating prior sentences. This is the narrow exception to "no conclusion section", allowed only when the closing paragraph still tells the reader what to do next, not just that they've reached the end. ## articles/managed-migration-assistant-mac-to-mac-migration-with-fleet.md - "Requirements" (not "Prerequisites") holds version and enrollment-method constraints. -- A dedicated "What transfers and what doesn't" H2 sits between Requirements and the first configuration step — this is reference material the reader needs in their head before they touch config, not a step itself. Legitimate as its own section when steps would be misconfigured without it. -- GitOps vs. UI paths are H3 siblings under "Configure Managed Migration Assistant in Fleet," each a short numbered list — same pattern as the enforce-macos-updates guide's Step 3. -- An `> **Warning:**`-equivalent constraint stated as a bold-lead sentence inline ("One constraint from Apple: the **Restore** pane ... cannot be hidden") — again, inline bold works for a single-sentence gotcha; reserve full blockquotes for gotchas that need more than one sentence or a code sample. -- Closes with "End-to-end flow": a numbered list walking the full process across both Macs. This is a legitimate closing section distinct from a summary — it's a sequence diagram in prose, useful because the actual steps were split across two systems (source Mac, destination Mac, Fleet) and the reader needs to see them stitched together once. -- "Further reading" link list at the very end, before endmatter. +- A dedicated "What transfers and what doesn't" H2 sits between Requirements and the first configuration step. This is reference material the reader needs in their head before they touch config, not a step itself. Legitimate as its own section when steps would be misconfigured without it. +- GitOps vs. UI paths are H3 siblings under "Configure Managed Migration Assistant in Fleet", each a short numbered list. Same pattern as the enforce-macos-updates guide's Step 3. +- An `> **Warning:**`-equivalent constraint stated as a bold-lead sentence inline ("One constraint from Apple: the **Restore** pane ... cannot be hidden"). Again, inline bold works for a single-sentence gotcha. Reserve full blockquotes for gotchas that need more than one sentence or a code sample. +- Closes with "End-to-end flow": a numbered list walking the full process across both Macs. This is a legitimate closing section distinct from a summary. It's a sequence diagram in prose, useful because the steps were split across two systems (source Mac, destination Mac, Fleet) and the reader needs to see them stitched together once. +- "Further reading" link list at the end, before endmatter. ## Anti-pattern: an article wearing the guides tag Watch for pieces tagged `category: guides` that are structurally articles. The tells: -- No Prerequisites/Requirements section at all. -- No numbered steps and no task-headed H2 sections. Headings are topic nouns describing changes or themes ("TLS requirements are getting stricter," "Intel Mac support timeline"), not actions the reader takes. -- Body paragraphs are multi-sentence analysis and framing, not procedure. This can be entirely voice-compliant prose — the problem is structural, not a style violation. +- No Prerequisites or Requirements section at all. +- No numbered steps and no task-headed H2 sections. Headings are topic nouns describing changes or themes ("TLS requirements are getting stricter", "Intel Mac support timeline"), not actions the reader takes. +- Body paragraphs are multi-sentence analysis and framing, not procedure. This can be entirely voice-compliant prose. The problem is structural, not a style violation. - Closes with a numbered "recap" or "priorities" list whose items are strategic takeaways ("start the budget conversation for X"), not steps of one task working toward a shared goal. A numbered list alone doesn't make something a procedure. -- If asked to "fix" a piece like this, the right move is not to force prerequisites and steps onto it. Flag that it's mistagged and recommend `category: articles`, or ask whether the intent was actually a guide — in which case it needs a real procedure written, not a reformat of the existing prose. +- If asked to "fix" a piece like this, the right move is not to force prerequisites and steps onto it. Flag that it's mistagged and recommend `category: articles`, or ask whether the intent was a guide. In that case it needs a real procedure written, not a reformat of the existing prose. diff --git a/.claude/skills/fleet-guide-formatting/references/template.md b/.claude/skills/fleet-guide-formatting/references/template.md index a57f482c32..5639161b80 100644 --- a/.claude/skills/fleet-guide-formatting/references/template.md +++ b/.claude/skills/fleet-guide-formatting/references/template.md @@ -1,20 +1,20 @@ # [Task-verb-led title in sentence case] -[One short paragraph. State the problem and what the reader ends up with. No history lesson, no "in today's landscape." If the guide doesn't cover every scenario, say so here in one sentence.] +[One short paragraph. State the problem and what the reader ends up with. No history lesson, no "in today's landscape". If the guide doesn't cover every scenario, say so here in one sentence.] ## Prerequisites - + Check these before you start: -- [Concrete, checkable requirement — version, access level, or artifact in hand] +- [Concrete, checkable requirement: version, access level, or artifact in hand] - [Another requirement. Gate by version inline if needed: "Fleet v4.86 or earlier: do X. Fleet v4.87 or later: no action needed."] > **Warning:** [What goes wrong, and how to avoid it. Keep it to the risk that matters most.] -## [First action, as an imperative heading — e.g. "Create a recipe override"] +## [First action, as an imperative heading, e.g. "Create a recipe override"] [One or two sentences of setup, then the command or click-path.] @@ -59,11 +59,14 @@ Check these before you start: ## Further reading - + - [Link with descriptive text, not "here"] - [Another link] +