Skip to content

Commit 5f6110d

Browse files
justin808justin808
authored
Merge pull request #17 from shakacode/jg/add-docs-skill
Add /docs skill for professional documentation generation
2 parents 9fec925 + 78aae1b commit 5f6110d

6 files changed

Lines changed: 929 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,26 @@ Prompt templates are not auto-installed commands. For Codex, point `AGENTS.md` a
5656

5757
Install to `~/.claude/agents/` (personal) or `.claude/agents/` (project).
5858

59+
## Skills
60+
61+
Skills are invoked via `/skill-name` in Claude Code. Install by adding this repo via `--add-dir`:
62+
63+
```bash
64+
claude --add-dir /path/to/claude-code-commands-skills-agents/skills
65+
```
66+
67+
Or configure in your project's `.claude/settings.json`:
68+
69+
```json
70+
{
71+
"additionalDirectories": ["/path/to/claude-code-commands-skills-agents/skills"]
72+
}
73+
```
74+
75+
| Skill | Description |
76+
| --- | --- |
77+
| [`/docs`](skills/docs/SKILL.md) | Generate, audit, or update project documentation to a professional open-source standard. Covers README, quick start, API reference, config reference, migration guides, troubleshooting, LLMs.txt, and inline code docs (YARD/TSDoc). Benchmarked against Inertia Rails and Vite Ruby documentation. |
78+
5979
## Templates
6080

6181
Starter templates for new projects:
@@ -80,6 +100,7 @@ Starter templates for new projects:
80100
| Script | Description |
81101
|--------|-------------|
82102
| [`bin/sync-commands`](bin/sync-commands) | Sync commands from this repo into a target project's `.claude/commands/` |
103+
| [`bin/sync-skills`](bin/sync-skills) | Sync skills from this repo into a target project's `.claude/skills/` |
83104
| [`bin/chrome-mcp`](bin/chrome-mcp) | Launch Chrome with a separate profile for MCP browser debugging |
84105
| `bin/set-review-instructions` | Initialize file-by-file review with instructions and changed file list |
85106
| `bin/print-git-diff` | Print diff, before/after, and review instructions for a single file |
@@ -96,9 +117,9 @@ Starter templates for new projects:
96117
| [Claude Code Review](.github/workflows/claude-code-review.yml) | Automatic PR review on open/sync |
97118
| [Claude Code](.github/workflows/claude.yml) | Respond to `@claude` mentions in issues/PRs |
98119

99-
## Syncing Commands to Your Project
120+
## Syncing to Your Project
100121

101-
This repo is the canonical source for shared commands like `/address-review`. To keep a project in sync:
122+
This repo is the canonical source for shared commands and skills. Use the sync scripts to keep a project up to date.
102123

103124
### One-Time Setup
104125

@@ -120,27 +141,33 @@ cp "$BOOSTERS/commands/address-review.md" .claude/commands/
120141

121142
### Keeping Up to Date
122143

123-
Run `bin/sync-commands` from this repo to pull the latest commands into a target project:
144+
Run the sync scripts from this repo to pull the latest commands or skills into a target project:
124145

125146
```bash
126147
# Sync all commands to a project
127148
./bin/sync-commands ~/projects/my-app
128149

129150
# Sync a specific command
130151
./bin/sync-commands ~/projects/my-app address-review
152+
153+
# Sync all skills to a project
154+
./bin/sync-skills ~/projects/my-app
155+
156+
# Sync a specific skill
157+
./bin/sync-skills ~/projects/my-app docs
131158
```
132159

133160
### For AI Agents in Consuming Repos
134161

135162
Add this to your project's `CLAUDE.md` or `AGENTS.md` so agents know where shared commands come from:
136163

137164
```markdown
138-
## Shared Commands
165+
## Shared Commands and Skills
139166

140-
The `/address-review` command is synced from
167+
Commands and skills are synced from
141168
[claude-code-commands-skills-agents](https://github.com/shakacode/claude-code-commands-skills-agents).
142-
Do not edit `.claude/commands/address-review.md` directly — update the
143-
canonical copy in the boosters repo and re-sync.
169+
Do not edit `.claude/commands/` or `.claude/skills/` directly — update the
170+
canonical copies in the boosters repo and re-sync.
144171
```
145172

146173
See the [templates/](templates/) directory for starter `CLAUDE.md` and `AGENTS.md` files that include this pattern.
@@ -150,6 +177,7 @@ See the [templates/](templates/) directory for starter `CLAUDE.md` and `AGENTS.m
150177
1. Add new commands to `commands/`
151178
2. Add new prompt templates to `prompts/` when the workflow targets Codex, GPT, or other non-Claude tools
152179
3. Add new agents to `agents/`
153-
4. Add documentation to `docs/`
154-
5. Keep everything generic -- project-specific instructions belong in project CLAUDE.md files
155-
6. All files must end with a newline character
180+
4. Add new skills to `skills/`
181+
5. Add documentation to `docs/`
182+
6. Keep everything generic -- project-specific instructions belong in project CLAUDE.md files
183+
7. All files must end with a newline character

‎bin/sync-skills‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/usr/bin/env bash
2+
#
3+
# Sync skills from this repo into a target project's .claude/skills/ directory.
4+
#
5+
# Usage:
6+
# ./bin/sync-skills <target-project-path> [skill-name]
7+
#
8+
# Examples:
9+
# ./bin/sync-skills ~/projects/my-app # Sync all skills
10+
# ./bin/sync-skills ~/projects/my-app docs # Sync one skill
11+
12+
set -euo pipefail
13+
14+
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
15+
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
16+
SKILLS_DIR="$REPO_ROOT/skills"
17+
18+
if [ $# -lt 1 ]; then
19+
echo "Usage: $(basename "$0") <target-project-path> [skill-name]"
20+
echo ""
21+
echo "Syncs skills from claude-code-commands-skills-agents into a project."
22+
echo ""
23+
echo "Examples:"
24+
echo " $(basename "$0") ~/projects/my-app"
25+
echo " $(basename "$0") ~/projects/my-app docs"
26+
exit 1
27+
fi
28+
29+
TARGET="$1"
30+
SKILL="${2:-}"
31+
32+
if [ ! -d "$TARGET" ]; then
33+
echo "Error: target directory does not exist: $TARGET"
34+
exit 1
35+
fi
36+
37+
TARGET_DIR="$TARGET/.claude/skills"
38+
mkdir -p "$TARGET_DIR"
39+
40+
if [ -n "$SKILL" ]; then
41+
SOURCE="$SKILLS_DIR/$SKILL"
42+
if [ ! -d "$SOURCE" ]; then
43+
echo "Error: skill not found: $SOURCE"
44+
echo "Available skills:"
45+
for d in "$SKILLS_DIR"/*/; do
46+
[ -d "$d" ] && echo " $(basename "$d")"
47+
done
48+
exit 1
49+
fi
50+
cp -r "$SOURCE" "$TARGET_DIR/"
51+
echo "Synced $SKILL -> $TARGET_DIR/$SKILL/"
52+
else
53+
for d in "$SKILLS_DIR"/*/; do
54+
[ -d "$d" ] || continue
55+
SKILL_NAME="$(basename "$d")"
56+
cp -r "$d" "$TARGET_DIR/"
57+
echo "Synced $SKILL_NAME -> $TARGET_DIR/$SKILL_NAME/"
58+
done
59+
fi
60+
61+
echo ""
62+
echo "Done. Skills are now in $TARGET_DIR/"
63+
echo ""
64+
echo "To use skills, add the skills directory via --add-dir or settings.json:"
65+
echo " claude --add-dir $TARGET_DIR"
66+
echo " Or add to .claude/settings.json: {\"additionalDirectories\": [\"$TARGET_DIR\"]}"

‎skills/docs/SKILL.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
name: docs
3+
description: Generate, audit, or update project documentation to a professional open-source standard. Use this skill whenever the user mentions docs, documentation, README, API reference, guides, migration guides, troubleshooting, llms.txt, doc audit, or wants to improve any written developer-facing content in a repository. Also trigger when the user says things like "document this", "write docs for", "update the docs", "our docs need work", or compares documentation quality to other projects. Covers Ruby (YARD), TypeScript (TSDoc/JSDoc), Markdown guides, configuration references, and doc site structure.
4+
---
5+
6+
# Documentation Skill
7+
8+
Generate and maintain documentation that meets or exceeds the standard set by the best open-source Rails/JS projects (Inertia Rails, Vite Ruby, Rails itself).
9+
10+
## Before You Start
11+
12+
Read these reference files (located in the `references/` subdirectory next to this SKILL.md file) before proceeding:
13+
14+
1. **Quality Standard** — `references/quality-standard.md` — tiered audit checklist (Must-Have / Expected / Differentiator)
15+
2. **Documentation Templates** — `references/templates.md` — structural skeletons for each doc type
16+
3. **Competitive Landscape** — `references/competitive-landscape.md` — benchmarks against peer projects
17+
18+
## Workflow
19+
20+
### Step 1: Assess the current state
21+
22+
- Scan the repo for existing docs: `docs/`, `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, inline code comments, Wiki, and any hosted doc site config (VitePress, Docusaurus, Jekyll, etc.)
23+
- Identify what exists, what is outdated, and what is missing
24+
- Compare against the Quality Standard reference above
25+
26+
### Step 2: Determine scope
27+
28+
If the user gave a specific target (e.g., `/docs $ARGUMENTS`), focus there. Otherwise, present a prioritized gap analysis:
29+
30+
1. **Critical gaps** - Missing README sections, no quick start, no API reference
31+
2. **High-value improvements** - Outdated guides, missing migration/upgrade docs, no troubleshooting
32+
3. **Polish** - LLMs.txt, cookbook/recipes, configuration reference, contributor guide improvements
33+
34+
Ask the user which items to tackle (or do all if they say so).
35+
36+
### Step 3: Generate or rewrite documentation
37+
38+
Follow these principles for ALL documentation:
39+
40+
#### Voice and Style
41+
- **Direct and concise.** Lead with what the reader needs. No filler.
42+
- **Show, don't tell.** Every concept gets a code example. Prefer real-world examples over contrived ones.
43+
- **Progressive disclosure.** Quick start first, then deeper guides, then API reference. Layer complexity.
44+
- **Avoid em dashes** (use commas, parentheses, or separate sentences instead).
45+
- **Use second person** ("you") for guides and tutorials. Use third person for API references.
46+
- **Prefer active voice.** "Run `bundle install`" not "The bundle should be installed."
47+
48+
#### Structure by Doc Type
49+
50+
**README.md** (the front door):
51+
- One-liner description + badges
52+
- "What is this?" in 2-3 sentences
53+
- Quick install (copy-paste ready)
54+
- Minimal "Hello World" example that works
55+
- Link table to deeper docs
56+
- Requirements / compatibility matrix
57+
- Community links (Slack, Discussions, Stack Overflow)
58+
- Contributing pointer
59+
- License
60+
61+
**Quick Start Guide** (< 15 minutes):
62+
- Prerequisites with exact version requirements
63+
- Step-by-step, numbered instructions
64+
- Every command is copy-paste ready
65+
- "You should see..." verification checkpoints after key steps
66+
- Link to "next steps" at the end
67+
68+
**Conceptual Guides** (explain "why" and "how"):
69+
- Start with a one-paragraph summary of what the reader will learn
70+
- Use diagrams (Mermaid or ASCII) for architecture and data flow
71+
- Break into logical sections with clear headings
72+
- End each guide with "Related" links
73+
74+
**API / Helper Reference**:
75+
- One page per module or helper group
76+
- Signature, parameters table, return value, exceptions
77+
- At least one usage example per method
78+
- For Ruby: follow YARD conventions (`@param`, `@return`, `@example`)
79+
- For TypeScript: follow TSDoc conventions (`@param`, `@returns`, `@example`)
80+
81+
**Configuration Reference**:
82+
- Table format: option name, type, default, description
83+
- Group by category
84+
- Include example config file (annotated with comments)
85+
86+
**Migration / Upgrade Guide**:
87+
- Version-to-version, with exact steps
88+
- "Breaking changes" section at top
89+
- "Deprecations" section
90+
- Automated migration commands if available
91+
- Before/after code comparisons
92+
93+
**Troubleshooting / FAQ**:
94+
- Problem statement as the heading (what the user sees or encounters)
95+
- Cause explanation (1-2 sentences)
96+
- Solution with exact commands or code
97+
- "Still stuck?" pointer to community support
98+
99+
**LLMs.txt** (AI-friendly docs):
100+
- `/llms.txt` with a structured overview and links to key pages
101+
- `/llms-full.txt` with complete documentation in a single Markdown file
102+
- Follow the llms.txt specification: title, description, sections with URLs
103+
- Include on every docs page: "Are you an LLM? View /llms.txt for optimized documentation"
104+
105+
### Step 4: Cross-reference and link
106+
107+
- Every guide should link to related guides
108+
- Every API method mentioned in a guide should link to its reference page
109+
- Add a "See also" or "Related" section at the bottom of each page
110+
- Verify no dead links (check file paths exist)
111+
112+
### Step 5: Review with the user
113+
114+
Present the generated docs and ask:
115+
- "Does this match how your project actually works?"
116+
- "Any terminology or naming I got wrong?"
117+
- "Anything missing for your users?"
118+
119+
## Targeting Specific Files
120+
121+
When invoked as `/docs <target>`:
122+
- If `<target>` is a file path: generate/update docs FOR that code file (inline comments, module-level docs, method docs)
123+
- If `<target>` is a directory: generate/update docs for the entire module
124+
- If `<target>` is a doc type keyword (e.g., "readme", "api", "quickstart", "migration", "troubleshooting", "llms.txt", "audit"): generate that specific doc type
125+
- If `<target>` is "audit": run a full gap analysis against the Quality Standard reference above and report findings
126+
127+
## Language-Specific Conventions
128+
129+
### Ruby
130+
- Use YARD doc format for all public methods and classes
131+
- `@param name [Type] description`
132+
- `@return [Type] description`
133+
- `@raise [ExceptionClass] when condition`
134+
- `@example` with realistic usage
135+
- `@see` for cross-references
136+
- Document `@option` for hash parameters
137+
138+
### TypeScript / JavaScript
139+
- Use TSDoc for TypeScript, JSDoc for JavaScript
140+
- `@param name - description`
141+
- `@returns description`
142+
- `@throws {ErrorType} description`
143+
- `@example` blocks with realistic usage
144+
- Export documentation: what is public API vs. internal
145+
- Document generic type parameters
146+
147+
### Markdown Docs
148+
- Use ATX headings (`#`, `##`, `###`) not Setext
149+
- Fenced code blocks with language identifiers (```ruby, ```typescript, ```bash)
150+
- Use reference-style links for repeated URLs
151+
- Tables for configuration options and API parameter lists
152+
- Admonitions for warnings and tips (use blockquote style: `> **Note:** ...` or `> **Warning:** ...`)

0 commit comments

Comments
 (0)