skills.rest
browseros-ai
browseros-aiOFFICIAL
Explore all skills by this author →
WebsiteGitHub

write-internal-docs

Writes internal documentation as Markdown and HTML, then opens a pull request to the internal-docs repository.

13.4k|1.4k|Updated May 18, 2025
Search Tags:#HTML#Git#Markdown#Documentation#internal docs#gitHub#Pull request
One-click install
npx skills add https://github.com/browseros-ai/BrowserOS --skill write-internal-docs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-internal-docs
Source: https://github.com/browseros-ai/BrowserOS/tree/main/.claude/skills/write-internal-docs
Command: npx skills add https://github.com/browseros-ai/BrowserOS --skill write-internal-docs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Writing and publishing internal engineering docs involves repetitive manual steps: drafting Markdown, rendering an HTML sibling, keeping the repo index tidy, and opening a pull request. This Skill automates that entire workflow for the private browseros-ai/internal-docs repository while enforcing consistent voice and structure rules.

Core Features & Use Cases

  • Guided doc authoring: Scopes the subject, type (setup, features, architecture, designs), filename, and owner, then drafts from repo templates with file-and-line citations.
  • Markdown plus HTML output: Writes the .md source and renders a self-contained .html sibling from a bundled template, with the Markdown always treated as the source of truth.
  • Repo hygiene and PR automation: Runs a tidy pass for dead links, missing index entries, and misfiled docs, then commits changes separately and opens a PR via the GitHub CLI.
  • Use Case: After merging a feature branch, invoke the skill with a topic like "nightly signing" to produce a cited feature note, update the README index, and land a reviewable PR without touching your local submodule checkout.

Quick Start

Ask the assistant to write an internal doc about a specific topic, for example by saying: use the write-internal-docs skill to document the nightly signing pipeline.

Frequently Asked Questions about write-internal-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an internal doc and open a PR automatically?▼

Invoke the skill with a topic, such as a feature name, or run it on a feature branch so it derives the subject from the branch diff. It drafts the Markdown from a template, renders the HTML sibling, updates the index, and opens a PR with gh.

How does the skill generate the HTML version of a doc?▼

It converts the Markdown body to HTML using pandoc if installed, or manually otherwise, then fills a bundled self-contained template with the title, source path, and body. The Markdown file remains the source of truth and the HTML is never hand-edited.

What prerequisites are needed before running this documentation workflow?▼

You need the .internal-docs submodule initialized, the GitHub CLI authenticated via gh auth login, and SSH access to the internal-docs repository. The pre-flight step checks all three and prints the exact fix command if any fail.

Does the skill modify my local internal-docs submodule checkout?▼

No. All writes happen in a separate work clone under the temp directory, never in your checkout. The clone is removed after the PR is opened, and the skill never pushes directly to main.

What writing style rules does the doc output enforce?▼

Docs must lead with the point, use concrete file and function names, keep sentences under 20 words on average, and avoid a list of banned words and filler intros. Feature notes are capped at 60 body lines, and a voice check rewrites violations up to three passes.

Related Skills

Explore More Software Engineering Skills→
mauriciodelriomauriciodelrio
3

project-resumption

Resumes a project by scanning .docs/memory, .docs/context, .docs/rules and summarizing its status for developers.

Community
Advanced
cookeyholdercookeyholder

squash-pr

Squash and merge a GitHub pull request into main after validating review feedback.

Community
Advanced
akaszubskiakaszubski
32

cross-reference-validation

Validate documentation file paths, links, line numbers, and code imports across repositories and branches.

Community
Intermediate
microsoftmicrosoft
2.9k

wiki-vitepress

Package wiki Markdown into a VitePress static site with dark theme and Mermaid diagrams.

Official
Advanced