draft-docs Skill
✓ VerifiziertErstellt Entwürfe für Dokumentationen im Diátaxis-Stil, einschließlich Tutorials, How-tos, Referenzen und Erklärungen, basierend auf Code-Analysen.
- GitHub Stars
- 87
- Dateien
- 1
- Letzter Commit
- 15. Sept. 2026
- Lizenz
- Apache-2.0
- Erlaubte Tools
- —
Was macht der draft-docs Skill?
Erstellt Entwürfe für Dokumentationen im Diátaxis-Stil, einschließlich Tutorials, How-tos, Referenzen und Erklärungen, basierend auf Code-Analysen.
Zusammenfassung erzeugt aus der SKILL.md des Skills.
Über den draft-docs skill
Technical Writer und Entwickler können diesen Skill nutzen, um Code-Analysen in strukturierte Dokumentationsentwürfe zu verwandeln. Durch die Analyse von Funktionen, Klassen und aktuellen Git-Änderungen generiert das Tool Inhalte nach dem Diátaxis-Framework, das Dokumentationen in Tutorials, How-tos, Referenzen und Erklärungen unterteilt. Dies stellt sicher, dass unterschiedliche Bedürfnisse der Leser – wie das Erlernen eines neuen Konzepts oder das Nachschlagen eines API-Parameters – mit dem passenden Schreibstil bedient werden.
Ein Agent sollte diesen Skill laden, wenn er damit beauftragt wird, ein spezifisches Thema zu dokumentieren, wie zum Beispiel eine Authentication-Middleware oder eine WebSocket-API. Der Prozess beginnt mit der Erfassung des Projektkontexts, der Identifizierung der bestehenden Dokumentationsstruktur und dem Laden spezialisierter Writing-Skills wie tutorial-docs oder reference-docs. Alle initialen Outputs werden als Markdown-Dateien in einem dedizierten Draft-Verzeichnis gespeichert, um eine menschliche Überprüfung zu ermöglichen. Sobald ein Entwurf genehmigt wurde, kann der Skill die Datei an ihren endgültigen Bestimmungsort verschieben und Navigationsdateien wie navigation.json oder docusaurus.config.js automatisch aktualisieren.
Was ein agent damit machen kann
- 1Beginner Onboarding Tutorials erstellenGeneriere eine geführte Lektion, die einem neuen User zeigt, wie er seine erste Projektkomponente baut.
- 2Dokumentations-Publishing automatisierenVerschiebe einen geprüften Markdown-Entwurf an seinen permanenten Speicherort und aktualisiere die Site-Navigation.
Geschrieben basierend auf dem SKILL.md des skills. Jeder use case wurde gegen ein zitat daraus geprüft.
So installierst du den draft-docs Skill
Jeder Befehl kopiert den Skill-Ordner in das Skills-Verzeichnis des Clients. Starte den Client neu oder beginne eine neue Session, um ihn zu laden.Den draft-docs Skill in Plugin installieren
/plugin marketplace add existential-birds/beagle /plugin install beagle-docs@existential-birds
Den draft-docs Skill in Claude Code installieren
~/.claude/skills/draft-docs/SKILL.md
$ npx degit existential-birds/beagle/plugins/beagle-docs/skills/draft-docs ~/.claude/skills/draft-docsDen draft-docs Skill in Claude Code (project) installieren
.claude/skills/draft-docs/SKILL.md
$ npx degit existential-birds/beagle/plugins/beagle-docs/skills/draft-docs .claude/skills/draft-docsDen draft-docs Skill in Codex installieren
~/.agents/skills/draft-docs/SKILL.md
$ npx degit existential-birds/beagle/plugins/beagle-docs/skills/draft-docs ~/.agents/skills/draft-docsDen draft-docs Skill in Gemini CLI installieren
~/.gemini/skills/draft-docs/SKILL.md
$ npx degit existential-birds/beagle/plugins/beagle-docs/skills/draft-docs ~/.gemini/skills/draft-docsDen draft-docs Skill in Claude.ai installieren
npx degit existential-birds/beagle/plugins/beagle-docs/skills/draft-docs draft-docs && zip -r draft-docs.zip draft-docs # claude.ai → Customize → Skills → + → Create skill → Upload a skill → draft-docs.zip
Automatisierte Checks
Geluften am 16. Nov. 2026Vollständiger Bericht →Hat unsere automatischen Prüfungen bestanden. Das ist kein Sicherheitsaudit: Lesen Sie die Skripte, bevor ein Agent sie ausführt. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarexistential-birds/beagle/plugins/beagle-docs/skills/draft-docs is public and reachablegithub.com/existential-birds/beagle/tree/HEAD/plugins/beagle ↗Bestanden
- Open Source Lizenz (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit 2026-09-15github.com/existential-birds/beagle/commits ↗Bestanden
- Keine Download-und-Ausführen-Muster oder Zugangsdatendiebstahl in SkriptenNo scripts in the skill folderBestanden
- Keine versteckten Anweisungen in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/existential-birds/beagle/blob/HEAD/plugins/beagle ↗Bestanden
- Vorab erlaubte Tools sind eingeschränktNo pre-approved tools; the agent asks before using onegithub.com/existential-birds/beagle/blob/HEAD/plugins/beagle ↗Bestanden
- SKILL.md folgt dem Agent-Skills-Formatthe description does not say when to use the skillgithub.com/existential-birds/beagle/blob/HEAD/plugins/beagle ↗Befund
SKILL.md
Auf GitHub ansehenDraft Docs
Generate Tutorial, How-To, Reference, or Explanation documentation drafts to docs/drafts/ for review before publishing. These are the four Diataxis types — see docs-style/references/diataxis-compass.md for the full type-selection procedure.
Arguments
- Topic prompt: Description of what to document (e.g., "Document the WebSocket API")
- --publish [file]: Move reviewed draft to final location and update navigation
Mode 1: Generate Draft
Invoke the draft-docs skill with a topic prompt, e.g. draft-docs "Document the authentication middleware".
Step 0: Gather Context
Before parsing input, gather project context:
# Check for existing docs structure
ls -la docs/ 2>/dev/null || echo "No docs/ directory found"
# Identify documentation framework
ls docs/navigation.json docs/mint.json docs/docusaurus.config.js docs/mkdocs.yml 2>/dev/null | head -1
# Check for existing drafts
ls docs/drafts/*.md 2>/dev/null || echo "No existing drafts"
# Get recent code changes for context
git diff --name-only $(git merge-base HEAD main)..HEAD 2>/dev/null | head -20
Capture:
- Docs structure:
docs/subdirectories present - Navigation system:
navigation.json,mint.json, or other config - Tech stack hints: from file extensions and imports in changed files
- Existing drafts: to avoid duplicates
Step 1: Parse Input
Extract from the prompt:
- Topic: What to document (e.g., "authentication middleware")
- Content type: Detect from keywords:
| Keywords | Type | Skill |
|---|---|---|
| "tutorial", "learn", "getting started", "first", "onboarding", "introduction", "build a/your" | Tutorial | tutorial-docs |
| "how to", "guide", "steps", "configure", "set up" | How-To | howto-docs |
| "API", "reference", "parameters", "function", "endpoint" | Reference | reference-docs |
| "why", "how does it work", "concept", "background", "rationale", "design decision", "architecture", "trade-offs" | Explanation | explanation-docs |
These four types are the quadrants of the Diátaxis framework — Tutorial (learning), How-To (task), Reference (information), and Explanation (understanding). Decide with the two compass questions — action or cognition? acquisition or application? — detailed in docs-style/references/diataxis-compass.md. Two distinctions resolve most ambiguity:
- Tutorial vs. How-To both give action steps, but a Tutorial teaches a beginner through a guaranteed-to-succeed lesson (study), while a How-To directs a competent user toward a real goal (work). If the reader is learning the product for the first time, it's a Tutorial; if they already know it and want to get a task done, it's a How-To.
- Reference vs. Explanation both serve theoretical knowledge, but Reference states neutral facts to consult at the keyboard, while Explanation discusses reasoning and context to read away from it. If the request wants opinions, history, or trade-offs, it's Explanation; if it wants an authoritative spec, it's Reference.
If ambiguous, ask: "Should this be a Tutorial (learning by doing), a How-To guide (task completion), a Reference doc (technical lookup), or an Explanation (understanding the why behind a concept)?"
Step 2: Load Skills
Always load both:
- docs-style - Core writing principles
- Detected type skill:
- tutorial-docs for Tutorial
- howto-docs for How-To
- reference-docs for Reference
- explanation-docs for Explanation
Step 3: Analyze Code
Search the codebase for relevant code:
- Symbol search: Find functions, classes, types matching the topic
- File search: Locate related files by name patterns
- Reference search: Find usage examples
Gather:
- Function/method signatures
- Type definitions
- Existing comments/docstrings
- Usage patterns in tests or examples
Step 4: Generate Draft
Apply the loaded skills to generate documentation:
For Tutorial docs:
- Follow
tutorial-docstemplate structure - Title names what the reader will build ("Build your first X"), not what they'll learn
- Use first-person plural — "In this tutorial, we will…" — to keep the teacher/learner narrative
- Give one clear path with no choices or alternatives
- After every step, state what the reader should see ("You should see…")
- Ruthlessly minimize explanation; link out to Explanation docs for the "why"
For Reference docs:
- Follow
reference-docstemplate structure - Document all parameters with types
- Include complete, runnable examples from actual code
- Add Related section linking to connected symbols
For How-To docs:
- Follow
howto-docstemplate structure - Start title with "How to"
- List concrete prerequisites
- Break into single-action steps
- Include verification section
For Explanation docs:
- Follow
explanation-docstemplate structure - Frame the title around understanding a concept ("Understanding X"), not a task
- Open by stating what the reader will understand after reading
- Explain the why behind design decisions, not just what exists
- Discuss trade-offs honestly and acknowledge alternatives that were considered
- Write flowing prose for reading away from the keyboard — no steps to follow
Step 5: Write Draft
-
Create output path:
docs/drafts/{slug}.md- Slug from topic: "WebSocket API" →
websocket-api.md
-
Ensure directory exists:
mkdir -p docs/drafts -
Write the draft file (see Hard gates → Write gate: confirm file on disk before the next step)
-
Report to user:
## Draft Created **File:** `docs/drafts/{slug}.md` **Type:** Tutorial | How-To | Reference | Explanation **Based on:** [list of analyzed symbols/files] ### Next Steps 1. Review the draft for accuracy 2. Add any missing context or examples 3. When ready, publish by invoking the **draft-docs** skill with `--publish docs/drafts/{slug}.md`
Step 6: End-of-Run Verification
Verify draft generation completed successfully:
# Confirm draft file exists
ls -la docs/drafts/{slug}.md
# Validate frontmatter (YAML header)
head -10 docs/drafts/{slug}.md | grep -E "^---$|^title:|^description:"
# Check markdown syntax (if markdownlint available)
markdownlint docs/drafts/{slug}.md 2>/dev/null || echo "markdownlint not available"
Verification Checklist:
- Draft file created at
docs/drafts/{slug}.md - Frontmatter includes
titleanddescription - Content type matches detected type (Tutorial, How-To, Reference, or Explanation)
- Code examples are complete and runnable (Tutorial/How-To/Reference); concepts grounded in real design decisions (Explanation)
- Tutorial drafts give a single path with observable "You should see…" outcomes at each step
- All analyzed symbols referenced in draft
If any verification fails, report the specific issue and offer to regenerate.
Mode 2: Publish Draft
Invoke the draft-docs skill with the --publish flag, e.g. draft-docs --publish docs/drafts/websocket-api.md.
Step 1: Read Draft
Read the draft file and extract:
- Title
- Content type (from frontmatter or structure)
Step 2: Determine Destination
Ask user which section:
Where should this document go?
1. **Tutorials** → `docs/tutorials/{slug}.md`
2. **API Reference** → `docs/api/{slug}.md`
3. **Guides** → `docs/guides/{slug}.md`
4. **How-To** → `docs/how-to/{slug}.md`
5. **Concepts / Explanation** → `docs/concepts/{slug}.md`
6. **Other** → Specify path
Step 3: Move File
mv docs/drafts/{slug}.md {destination}/{slug}.md
Step 4: Update Navigation
Check for docs/navigation.json and update navigation:
- Read current navigation.json
- Find appropriate navigation group
- Add new page entry
- Write updated navigation.json
Example update:
{
"navigation": [
{
"group": "API Reference",
"pages": [
"api/existing-page",
"api/websocket-api"
]
}
]
}
Step 5: Report
## Published
**From:** `docs/drafts/{slug}.md`
**To:** `{destination}/{slug}.md`
**Navigation:** Updated `docs/navigation.json`
The document is now live in your docs.
Step 6: End-of-Run Verification
Verify publish completed successfully:
# Confirm file moved to destination
ls -la {destination}/{slug}.md
# Confirm draft removed
ls docs/drafts/{slug}.md 2>/dev/null && echo "WARNING: Draft still exists" || echo "Draft cleaned up"
# Verify navigation updated
grep -q "{slug}" docs/navigation.json && echo "Navigation includes new page" || echo "WARNING: Navigation may need manual update"
# Check markdown syntax at final location
markdownlint {destination}/{slug}.md 2>/dev/null || echo "markdownlint not available"
Verification Checklist:
- Document moved to
{destination}/{slug}.md - Draft removed from
docs/drafts/ - Navigation file updated with new page entry
- No broken links in navigation structure
- Document accessible at expected URL path
If any verification fails, report the specific issue and offer remediation steps.
Content Type Detection
Tutorial Indicators
- Prompt mentions: tutorial, learn, getting started, first, onboarding, introduction, "build a/your"
- Target is a beginner's first successful experience with the product
- User wants a guided, learn-by-doing lesson, not a task or a lookup
Reference Indicators
- Prompt mentions: API, endpoint, function, method, class, type, parameters, returns
- Target is a specific symbol or set of symbols
- User wants technical specification
How-To Indicators
- Prompt mentions: how to, guide, steps, configure, set up, integrate
- Target is a task or workflow
- User wants procedural instructions
Explanation Indicators
- Prompt mentions: why, how it works, concept, background, rationale, design decision, architecture, trade-offs
- Target is a concept or system the reader wants to understand, not operate
- User wants context and reasoning to read away from the keyboard, not steps to follow
Rules
- Always load
docs-styleskill for every draft - Generate to
docs/drafts/- never directly to final location - Include frontmatter with title and description
- Use realistic examples from actual codebase
- Reference analyzed symbols in draft metadata
- Preserve existing navigation structure when publishing
- Ask before overwriting existing files
Hard gates (sequenced)
Do not skip ahead: each Pass must be true before the next step. Use commands or explicit artifacts—not internal assurance.
Generate draft (Mode 1)
- Context gate — Pass: Step 0 commands ran (or equivalent) and you recorded at least one concrete outcome: e.g.
docs/listing snippet, or explicit note thatdocs/is missing and will be created. - Type gate — Pass: Tutorial vs How-To vs Reference vs Explanation is decided using the keyword table and the two compass questions or the user’s explicit answer (quote or paraphrase with “user chose …”). Do not start Step 3: Analyze Code until this is locked.
- Skills gate — Pass: Before analysis, both are in play: docs-style and the type skill (tutorial-docs, howto-docs, reference-docs, or explanation-docs). In your run, name the two skills loaded (paths)—not “I reviewed writing guidelines.”
- Write gate — Pass: After writing the draft,
test -f docs/drafts/{slug}.mdsucceeds (orlsshows the file). Only then emit the Draft Created block.
Publish draft (Mode 2)
- Destination gate — Pass: User chose a destination (from the menu or a specific path). Resolve
{destination}to a full path; Pass when the parent directory exists (test -d "$(dirname "$path")"or project-appropriate check) and you are not overwriting an existing file without explicit user approval. - Move gate — Pass: After
mv, the file exists at{destination}/{slug}.md(test -f) and navigation updates (if applicable) are applied before claiming Published.
Dateien in diesem Skill
1draft-docs Skill-Fragen
Wie installiere ich den draft-docs Skill in Claude Code?
Führe npx degit existential-birds/beagle/plugins/beagle-docs/skills/draft-docs ~/.claude/skills/draft-docs aus. Claude Code lädt Skills aus ~/.claude/skills (alle Projekte) oder .claude/skills (ein Projekt) und nutzt einen Skill, wenn seine Beschreibung zur Aufgabe passt.
Welche Clients können den draft-docs Skill nutzen?
Jeder Client, der das Agent Skills-Format liest: Claude Code, Codex, Gemini CLI und claude.ai (als ZIP hochladen). Skripte im Skill laufen nur dort, wo der Client Codeausführung erlaubt.
Welche Arten von Dokumentation kann dieser Skill generieren?
Er generiert vier spezifische Typen basierend auf dem Diátaxis-Framework: Tutorials, How-to-Guides, Referenzdokumentationen und Erklärungen (Explanations).
Wo werden die generierten Dokumentationsentwürfe gespeichert?
Alle initialen Entwürfe werden im Verzeichnis docs/drafts/ gespeichert, damit sie vor der Veröffentlichung an ihrem endgültigen Ort überprüft werden können.
Wie veröffentliche ich einen Entwurf auf der finalen Dokumentationsseite?
Du kannst einen geprüften Entwurf veröffentlichen, indem du den Skill mit dem Flag --publish gefolgt vom Dateipfad aufrufst.
Wie entscheidet der Skill, welcher Dokumentationstyp erstellt werden soll?
Der Skill analysiert den User-Prompt nach spezifischen Keywords und nutzt die Diátaxis-Leitfragen, um zwischen Lernen, Aufgaben, technischem Nachschlagen und konzeptionellem Verständnis zu unterscheiden.