feat: add docs-accept-quest authoring skill

[florent-leborgne]

Summary

Adds docs-accept-quest, an end-to-end authoring skill that turns an Elastic documentation GitHub issue into a draft PR in the repo that owns the target pages. Every factual claim must be traceable to product source or another authoritative evidence — not issue-body prose alone.

Not docs-content-only. Quests usually start from an elastic/docs-content issue, but product-repo routing can put the edit (or a companion PR) in kibana, elasticsearch, or another in-product docs tree. The skill confirms ownership before branching.

What the skill does

Given a docs issue (elastic/docs-content#N is typical; other repos and full URLs are accepted), the skill runs this pipeline:

0. Resolve writer paths (once per machine) — locate the local docs-content clone (for corpus search and docs-content worktrees), pitfalls checklist, and editorial preferences (env vars, local YAML config, or first-run questions). Existing files stay in place; the skill only records paths.
1. Understand the issue — read the issue and every linked product PR (metadata, files, full diff). Search for sibling/follow-up PRs. Assess implementation scope, whether-to-document, availability floor (backport labels ≠ shipped release), and which docs repo owns the page.
2. Find existing docs — Elastic Docs MCP + source grep for the canonical hub, siblings, shared snippets, and content-type fit. Read docs source at a fresh ref, not a stale clone.
3. Plan the edits — lightest change that closes each gap; persona/goal brief for new or overview pages; placement, cumulative scoping, SEO, and screenshot flags. Pause for user sign-off when IA is ambiguous.
4. Draft — worktree from origin/main in the target docs repo; write against editorial preferences + docs-applies-to-tagging (when installed) + style guide / MyST.
5. Verify — enumerate every concrete claim; confirm UI strings, defaults, and behavior at product HEAD; sweep the pitfalls checklist for doc-shaped mistakes.
6. Self-review — Vale (if available) plus style / applies_to / content-type / accuracy checklist.
7. Reader test — isolated subagent comprehension pass (no drafting context leaked in).
8. Open a draft PR — in the owning repo (and companion PRs when needed); title/body from the actual diff; pending links and screenshot todos when needed.

Companion catalog skills (docs-applies-to-tagging, docs-content-type-checker, docs-page-opening-optimizer, docs-check-style) are optional: invoke when installed, do not fail if missing.

Bundled reference files

File	Role
pitfalls.examples.md	Doc-shaped pitfalls checklist (links, structure, corpus terms, issue prose)
editorial-preferences.example.md	Prose-craft / drafting preferences complementary to the style guide and Vale

These examples are the files I use today in my day-to-day docs workflow (shared as starters). Writers can copy them on first run, or point Phase 0 at their own paths and keep using existing files without moving them.

Paths persist in ~/.config/elastic-docs/docs-accept-quest.local.yml (or env vars / a workspace docs-accept-quest.local.yml).

Writer setup

On first run the skill resolves:

Path	If you already have one
$DOCS_CONTENT_ROOT	Point at your local docs-content clone (still needed for corpus search when the PR opens elsewhere)
$DOCS_PITFALLS_PATH	Point at your existing pitfalls file
$EDITORIAL_PREFERENCES_PATH	Point at your existing editorial preferences

Later runs skip Phase 0 when config or env vars are present. For non-docs-content target repos, the skill asks for that clone path when branching.

Test plan

• Install the skill from this branch and run /docs-accept-quest (or equivalent) with no local config — confirm it asks for the three paths and can seed from the bundled examples
• Re-run with paths already set to existing files — confirm it does not overwrite them and skips re-asking
• Run against a docs-content issue whose pages live in docs-content — confirm Phase 1–8 and draft PR on docs-content
• Run (or dry-run plan) against an issue whose pages live in kibana/elasticsearch — confirm product-repo routing and PR target are not assumed to be docs-content
• Confirm companion skills (docs-applies-to-tagging, etc.) are optional when missing

[github-actions]

Skill Quality Review

docs-accept-quest

Overall: A comprehensive, well-structured multi-phase workflow skill that encodes Elastic-specific documentation conventions and processes with high specificity and actionability.

Strengths:

• Clear trigger description covers all input formats and scenarios (#123, full URL, repo-qualified)
• Every phase has concrete, imperative steps — no vague guidance
• Excellent specificity: real MCP tool names, exact git commands, content-type tables, and source-verification patterns all encode project-specific knowledge the model would not have from training alone
• Good use of companion skill references with graceful-degradation semantics (do not fail the quest if missing)
• Phase 5 verification discipline (enumerate-before-verify, HEAD-not-diff) is a strong pattern that directly prevents a common class of accuracy bugs
• Internal links reference bundled files (pitfalls.examples.md, editorial-preferences.example.md) that exist in the skill directory
• Code fences are balanced (13 pairs, no unclosed fences)
• Phase 0 first-run setup is clear and avoids hard-coded paths

Issues:

• Length (622 lines, threshold 500): The skill exceeds the soft limit, but every phase is load-bearing for a genuinely complex 8-phase workflow. The excess is justified. If trimming is ever needed, the Phase 2 content-type table (lines 220–228) partially duplicates guidance available at the fetched URL and is the lowest-risk cut.
• AskUserQuestion in allowed-tools: This is a non-standard tool that may not exist in all Claude Code environments. Its absence is handled gracefully in Phase 0 (prefer AskUserQuestion when available), but listing it in allowed-tools may generate a warning or no-op in environments that do not support it. Consider whether it needs to be listed there or only referenced in prose.

Suggestions:

• Phase 7 embeds a literal subagent prompt that the executing agent reads and then pastes into a child agent. Adding a short framing note like Paste the block below verbatim as the subagent first message would make the boundary explicit and reduce the risk of the parent agent partly internalizing the second-person instructions.

Generated by Skill Quality Review for #115 · sonnet46 · 28.8 AIC · ⌖ 5.32 AIC · ⊞ 5.9K · ◷

[github-actions]

Skill Eval Results

docs-accept-quest

Eval	Prompt	Pass Rate	Details
1	Accept docs quest for elastic/docs-content#9999. I already have docs-content at ~/work/docs-content...	4/4 (100%)	All passed
2	Accept docs quest elastic/docs-content#1234 for a Kibana UI change with a linked implementation PR...	5/5 (100%)	All passed
3	First run of docs-accept-quest with no local config and no env vars. I do not have pitfalls or editorial preference files yet...	3/3 (100%)	All passed
4	The docs issue says docs may not be needed for an invisible automatic change with no new user-facing control...	2/2 (100%)	All passed

Overall: 14/14 expectations passed (100%)

Assessment: The skill instructions clearly and explicitly address all eval scenarios:

• Eval 1: Phase 0 resolution order (env var → config file → first-run setup) ensures paths already provided by the user are recorded without moving or overwriting existing files. The config write step persists them for future runs.
• Eval 2: Phase 1 mandates reading the linked PR diff as the primary source of truth, running all four sibling PR searches before drafting, verifying i18n strings at HEAD (not issue prose), reading pitfalls/editorial preferences during Phase 4 and 5, and Phase 8 opens a draft PR with draft: true.
• Eval 3: First-run setup explicitly copies bundled example files to user-chosen paths (no hard-coded ~/Documents/github/... layout), writes config to ~/.config/elastic-docs/docs-accept-quest.local.yml, and proceeds. The skill explicitly prohibits hard-coded usernames or fixed paths.
• Eval 4: The whether-to-document gate in Phase 1 explicitly lists "Invisible/automatic change; no new setting, step, or user choice → Recommend no docs (or release note only)" and states "don't draft until the user confirms" when the issue body signals docs may not be needed.

Generated by Skill Eval Testing for #115 · sonnet46 · 33.5 AIC · ⌖ 5.25 AIC · ⊞ 5.7K · ◷