skills.rest
semaphoreui
semaphoreuiOFFICIAL
Explore all skills by this author →
Website𝕏@semaphoreuiGitHub

semaphore-cli-docs

Generate and synchronize CLI documentation pages from Cobra command code.

14.1k|1.3k|Updated Aug 23, 2014
Search Tags:#CLI#docusaurus#Golang#Documentation#docs generation#Semaphore#COBRA
One-click install
npx skills add https://github.com/semaphoreui/semaphore --skill semaphore-cli-docs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: semaphore-cli-docs
Source: https://github.com/semaphoreui/semaphore/tree/main/.claude/skills/semaphore-cli-docs
Command: npx skills add https://github.com/semaphoreui/semaphore --skill semaphore-cli-docs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

CLI documentation drifts out of sync with the actual Cobra command code whenever commands, flags, or aliases change, leaving users with inaccurate reference pages. This Skill regenerates the Semaphore CLI docs directly from the Go source so the docs always match the code.

Core Features & Use Cases

  • Code-derived documentation: Extracts command names, aliases, flags, defaults, and required-argument rules from cli/cmd/ Cobra definitions and their tests.
  • Full doc maintenance: Updates command-group pages, the CLI index page, and the docs/sidebars.js navigation registration, then builds the Docusaurus site to catch broken links.
  • Drift and pitfall detection: Identifies dead flags, stale help strings, and removed features, applying version-gated warnings instead of silent deletion.
  • Use Case: After adding a new PersistentFlags() option to the runner register command, ask the Skill to sync the CLI docs and it updates runners.md, verifies the sidebar entry, and runs the docs build.

Quick Start

Update the CLI documentation to match the current Cobra commands under cli/cmd and rebuild the docs site.

Frequently Asked Questions about semaphore-cli-docs

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

FAQPage Schema
How do I update CLI documentation from Cobra command code?▼

Enumerate the command tree with greps for cobra.Command definitions and AddCommand wiring, extract flags and required-argument rules from each command's Run body, then rewrite the corresponding Markdown pages. Finish by building the Docusaurus site to catch broken links.

How to keep CLI docs in sync after adding a new Cobra flag?▼

Re-read the command's init() for the new PersistentFlags entry and its Run body to confirm the flag is actually consumed, then add a row to the flag table on the matching docs page. Dead flags that are registered but never read should not be documented.

Does this handle removed CLI commands or flags?▼

Yes, removed features are version-gated with a Docusaurus warning admonition rather than silently deleted, so users on older releases still get accurate guidance. Whole removed command groups are proposed explicitly before deletion.

Why do documented flags sometimes not match actual CLI behavior?▼

Help strings in Cobra commands can drift from the real implementation, so the source of truth is the Run body and the config structs in util/, not the Short or Long text. Tests like runner_register_test.go encode exact behavior and are cross-checked.

What are the limitations of generating docs from Cobra code?▼

Commands whose behavior spans packages that cannot be traced quickly are flagged for user clarification rather than guessed. Requests to document commands or flags that do not exist in cli/cmd are refused, since docs are derived from code.

Related Skills

Explore More Software Engineering Skills→
monforjemonforje

golang-spf13-cobra

Design and manage Go CLI command trees with spf13/cobra.

Community
Advanced
hatch3rhatch3r
26

h4tcher-docusaurus-generator

Generate a Docusaurus 3.x documentation site from a repository.

Official
Intermediate
andreashasseandreashasse
7

release

Automate Elixir library releases with versioning, changelog updates, and pull requests.

Community
Advanced
alxxpersonalalxxpersonal
12

charm-fang

Wrap Cobra-based Go CLIs with styled help, errors, and versioning.

Community
Advanced