From yellow-docs
Shared documentation conventions — templates, diagram type selection, staleness detection, severity classification. Use when agents need doc generation or audit context.
How this skill is triggered — by the user, by Claude, or both
Slash command
/yellow-docs:docs-conventionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Shared patterns for yellow-docs agents and commands.
Shared patterns for yellow-docs agents and commands.
| Level | Meaning | Examples |
|---|---|---|
| P1 | Missing critical docs | No README, undocumented public API, no architecture overview |
| P2 | Stale docs | Code changed but docs not updated, broken references |
| P3 | Structural improvements | Missing sections, no cross-links, inconsistent formatting |
score = max(0, 100 - (P1_count * 15 + P2_count * 5 + P3_count * 1))
Primary output is the findings list; the score is a secondary summary metric.
# {Project Name}
{One-line description.}
## Installation
{Install instructions.}
## Usage
{Basic usage with code examples.}
## API
{Public API surface — functions, classes, endpoints.}
## Contributing
{How to contribute.}
## License
{License type.}
# {Module Name}
{Purpose — what this module does and why it exists.}
## Exports
{List of exported functions, classes, types.}
## Dependencies
{What this module depends on.}
## Usage
{How to use this module, with examples.}
# Architecture
{High-level description of the system.}
## Components
{Mermaid diagram of components.}
{Description of each component.}
## Data Flow
{How data moves through the system.}
## Key Decisions
{Architectural decisions and rationale.}
# API Reference
## {Function/Endpoint Name}
{Description.}
**Parameters:**
- `{name}` ({type}) — {description}
**Returns:** {type} — {description}
**Example:**
```
{Usage example}
```
Select the Mermaid diagram type based on what is being visualized:
| Scenario | Diagram Type | Mermaid Syntax |
|---|---|---|
| Module dependencies / imports | Flowchart | flowchart LR |
| API call sequences / message exchange | Sequence | sequenceDiagram |
| Class / type hierarchies | Class | classDiagram |
| State machines / workflows | State | stateDiagram-v2 |
| Database schemas / entity relationships | ER | erDiagram |
| System architecture (high-level) | Flowchart | flowchart TB + subgraphs |
| Directory / file layout | Mindmap | mindmap |
| Data flow / pipelines | Flowchart | flowchart LR |
| Git branching strategies | Gitgraph | gitgraph (if supported) |
LR (left-to-right) for process flows, pipelines, data flowTB (top-to-bottom) for hierarchies, architectures, org chartsdensity = 2 * edges / (nodes * (nodes - 1))classDef for semantic coloring: green=active, gray=deprecated, red=errorlinkStyle sparingly — only for critical pathsaccTitle and accDescr for accessibilityComposite signal with multiple factors:
git log --format='%aI' -1 -- <file>Detect project type from manifest files (most specific wins):
| Signal | Project Type | Doc Strategy |
|---|---|---|
.claude-plugin/plugin.json | Claude Code plugin | CLAUDE.md, command/agent docs |
Cargo.toml | Rust | README, crate docs, #[deny(missing_docs)] |
pyproject.toml / setup.py | Python | README, docstring coverage |
go.mod | Go | README, godoc conventions |
package.json + tsconfig.json | TypeScript | README, TSDoc/JSDoc coverage |
package.json (no tsconfig) | JavaScript | README, JSDoc coverage |
pnpm-workspace.yaml → pnpm workspacespackage.json with workspaces → npm/yarn workspacesCargo.toml with [workspace] → Rust workspacego.work → Go workspaceEach entry in the staleness JSON array returned by doc-auditor in refresh
mode:
{
"doc_path": "string — relative path from repo root",
"source_files": ["string — relative paths of changed source files"],
"last_doc_update": "string — ISO 8601 date from git log",
"last_source_update": "string — ISO 8601 date from git log",
"staleness_signal": "string — one of: age_exceeded, source_newer, broken_ref"
}
docs/architecture.mddocs/dependencies.mddocs/structure.mdAll generated files include provenance comment. Resolve the values first with
git rev-parse --short HEAD and date -u +%Y-%m-%dT%H:%M:%SZ (fall back to
unknown and a local date if needed), then write:
<!-- generated by yellow-docs at ${COMMIT_SHA} on ${DOC_DATE} -->
All commands that accept a path argument must validate it with this pattern:
# Neutralize leading-dash paths
case "$TARGET" in -*) TARGET="./$TARGET" ;; esac
# Resolve to absolute
case "$TARGET" in
/*) target_path="$TARGET" ;;
*) [ -e "$repo_top/$TARGET" ] && target_path="$repo_top/$TARGET" || target_path="$TARGET" ;;
esac
[ -e "$target_path" ] || { printf '[CMD] Error: path not found: %s\n' "$TARGET" >&2; exit 1; }
if [ -d "$target_path" ]; then
resolved=$(cd "$target_path" && pwd -P)
else
resolved=$(cd "$(dirname "$target_path")" && printf '%s/%s' "$(pwd -P)" "$(basename "$target_path")")
fi
case "$resolved" in
"$repo_top"|"$repo_top"/*) ;;
*) printf '[CMD] Error: path escapes repository: %s\n' "$TARGET" >&2; exit 1 ;;
esac
Replace [CMD] with the command name prefix (e.g., docs:audit).
AKIA[0-9A-Z]{16}postgres://, mongodb://, mysql://process.env.* in code snippets.gitignore — never scan ignored paths--- begin/end --- security fencing delimitersnpx claudepluginhub kinginyellows/yellow-plugins --plugin yellow-docsScaffolds project documentation (README, ARCHITECTURE, API, CODE_COMMENTS) from templates with placeholders and standards. Use for bootstrapping docs in new or under-documented codebases.
Scaffolds starter documentation (README, ARCHITECTURE, API, CODE_COMMENTS) from templates with placeholders and standards. For new or under-documented codebases.
Generates API docs, architecture diagrams, user guides, and technical references from code using AI analysis and best practices. Useful for documentation pipelines and repo standardization.