Draft Docs

Generate first-draft technical documentation from code analysis

Security Scan

The skill's requested actions (reading the repo, creating/moving docs files, and updating navigation.json) match its stated purpose of drafting and publishing documentation and there are no extraneous installs or secret requests.

Purpose & Capability

The name/description (generate docs drafts from code) aligns with the actions the SKILL.md instructs (scan code, gather symbols, create docs/drafts/*.md, move drafts into docs/* and update navigation.json). There are no unrelated environment variables, binaries, or installs requested.

Instruction Scope

Instructions explicitly read the repository (docs/, navigation.json, code files, git diff) and write/move files (mkdir, write drafts, mv, update navigation.json). This is expected for a doc-generation skill, but it means the agent will be performing file I/O and modifying repo state — review and approve those file changes before committing. The SKILL.md does not instruct executing user code, but it does request extracting runnable examples from source (which could encourage running code if implemented elsewhere).

Install Mechanism

This is an instruction-only skill with no install spec and no downloaded code. That minimizes supply-chain risk.

Credentials

No environment variables, credentials, or config paths are requested. The skill's needs are proportional to its purpose.

Persistence & Privilege

The skill does write and move files inside the repository and updates navigation.json (normal for a docs tool). It does not request always:true and has disable-model-invocation:true (so it will not autonomously call models). Confirm you are comfortable with repo file modifications when invoking this skill.

Assessment

This skill is coherent for generating and publishing docs, but it will read your repository and write/move files (docs/drafts/* → docs/*) and modify docs/navigation.json. Before using it: (1) run it on a feature branch or a copy so you can review changes; (2) inspect any updated navigation.json and generated examples to ensure no accidental data leakage or incorrect code execution; (3) be aware the skill will load other beagle-docs helper skills (review those if present); and (4) do not grant additional credentials or elevated environment access — none are required by this skill.

Generate Reference or How-To documentation drafts to docs/drafts/ for review before publishing.

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

/beagle-docs: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:

1. Topic: What to document (e.g., "authentication middleware")
2. Content type: Detect from keywords:

Keywords	Type	Skill
"how to", "guide", "steps", "configure", "set up"	How-To	howto-docs
"API", "reference", "parameters", "function", "endpoint"	Reference	reference-docs

If ambiguous, ask: "Should this be a Reference doc (technical lookup) or How-To guide (task completion)?"

Step 2: Load Skills

Always load both:

1. beagle-docs:docs-style - Core writing principles
2. Detected type skill:
   • beagle-docs:reference-docs for Reference
   • beagle-docs:howto-docs for How-To

Step 3: Analyze Code

Search the codebase for relevant code:

1. Symbol search: Find functions, classes, types matching the topic
2. File search: Locate related files by name patterns
3. 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 Reference docs:

• Follow reference-docs template 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-docs template structure
• Start title with "How to"
• List concrete prerequisites
• Break into single-action steps
• Include verification section

Step 5: Write Draft

1. Create output path:

   • docs/drafts/{slug}.md
   • Slug from topic: "WebSocket API" → websocket-api.md

2. Ensure directory exists:

   mkdir -p docs/drafts
   

3. Write the draft file (see Hard gates → Write gate: confirm file on disk before the next step)

4. Report to user:

   ## Draft Created
   
   **File:** `docs/drafts/{slug}.md`
   **Type:** Reference | How-To
   **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 with:
   

   /beagle-docs:draft-docs --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 title and description
• Content type matches detected type (Reference or How-To)
• Code examples are complete and runnable
• All analyzed symbols referenced in draft

If any verification fails, report the specific issue and offer to regenerate.

Mode 2: Publish Draft

/beagle-docs: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. **API Reference** → `docs/api/{slug}.md`
2. **Guides** → `docs/guides/{slug}.md`
3. **How-To** → `docs/how-to/{slug}.md`
4. **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:

1. Read current navigation.json
2. Find appropriate navigation group
3. Add new page entry
4. 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

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

Rules

• Always load docs-style skill 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)

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 that docs/ is missing and will be created.
2. Type gate — Pass: Reference vs How-To is decided using the keyword table or the user’s explicit answer (quote or paraphrase with “user chose …”). Do not start Step 3: Analyze Code until this is locked.
3. Skills gate — Pass: Before analysis, both are in play: beagle-docs:docs-style and the type skill (beagle-docs:reference-docs or beagle-docs:howto-docs). In your run, name the two skills loaded (IDs/paths)—not “I reviewed writing guidelines.”
4. Write gate — Pass: After writing the draft, test -f docs/drafts/{slug}.md succeeds (or ls shows the file). Only then emit the Draft Created block.

Publish draft (Mode 2)

1. 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.
2. Move gate — Pass: After mv, the file exists at {destination}/{slug}.md (test -f) and navigation updates (if applicable) are applied before claiming Published.