---
name: shdoc-shell-docs
description: Write and review shellscript documentation with shdoc annotations. Use when a coding agent creates, edits, or reviews `.sh` files or shell executables and should add, repair, or normalize `@file`, `@brief`, `@description`, `@arg`, `@option`, and `@example` comments to match shdoc conventions.
---

# Shdoc Shell Docs

## Overview

Use this skill to make shellscript comments parseable by `shdoc` without bloating simple code with boilerplate. Inspect the file first, then document the script and the non-trivial functions that benefit from generated reference docs.

## Workflow

1. Inspect the target shell file before writing comments.
2. Read `references/shdoc-rules.md` before editing comments.
3. Use `install/common/mise.sh` as the repo-local style example when working in this repository.
4. Add or repair file-level annotations near the top of the file:
   - Prefer `@file` for the script identifier.
   - Add `@brief` for a single-sentence summary.
   - Add multiline `@description` only when the script needs more context.
5. Add function-level annotations only where they help:
   - Start with `@description`.
   - Add `@arg` for positional parameters.
   - Add `@option` for flags and option-value pairs.
   - Add `@example` when the call shape is not obvious.
   - Add `@stdout`, `@stderr`, `@exitcode`, or `@see` only when they clarify observable behavior.
6. Rewrite existing free-form comments into valid `shdoc` annotations instead of keeping two parallel comment styles.

## Review Checklist

- Confirm the docs match the implementation instead of guessing arguments or options.
- Keep annotations immediately above the file header or function they describe.
- Prefer behavior and operator-facing intent over internal implementation notes.
- Skip boilerplate comments for trivial private helpers unless the user asks for exhaustive coverage.
- Keep multiline annotation blocks compact and easy to render as Markdown.

## References

- Read `references/shdoc-rules.md` for the minimal tag set, concise examples, and external reference policy.