Skip to content

Commit 0ee4b6e

Browse files
shettigarcclaude
shettigarc
and
claude
committed
feat: register slash commands as skills and reorganize internal docs
Move STYLE_GUIDE.md and COMPONENTS.md under .claude/docs/ as internal authoring specs. Create five Claude Code skills (newguide, publish, updateguide, listguides, previewguide) with full workflow detail from the original requirements. Add tmp/ to gitignore. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 8836ebc commit 0ee4b6e

File tree

10 files changed

+497
-63
lines changed

10 files changed

+497
-63
lines changed

COMPONENTS.md renamed to .claude/docs/COMPONENTS.md

File renamed without changes.

STYLE_GUIDE.md renamed to .claude/docs/STYLE_GUIDE.md

File renamed without changes.

‎.claude/skills/listguides/SKILL.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: listguides
3+
description: List all guides with slug, title, status (published/draft), and updated date
4+
disable-model-invocation: true
5+
---
6+
7+
# List All Guides
8+
9+
Scan the `guides/` directory and display a table of all guides.
10+
11+
## Steps
12+
13+
1. **Scan guides/** — Find all subdirectories that contain a `meta.json` file.
14+
15+
2. **Load metadata** — Read each `meta.json` and extract: slug, title, category, updated date.
16+
17+
3. **Determine status** — Check git status for each guide:
18+
- `published` — if the guide files are committed and pushed
19+
- `draft` — if the guide files are not yet committed
20+
21+
4. **Display table** — Show in this format, sorted by updated date (newest first):
22+
23+
```
24+
Slug Title Status Updated
25+
──────────────────────────────────────────────────────────────────────────────
26+
tmux-claude-cli tmux × Claude CLI Cheatsheet published 2026-03-27
27+
docker-compose-basics Docker Compose Basics draft 2026-03-28
28+
```
29+
30+
5. **Handle empty state** — If no guides exist:
31+
```
32+
No guides found. Run /newguide to create your first guide.
33+
```
34+
35+
6. **Handle errors** — If any meta.json is missing or has invalid JSON, note the issue in the output but continue listing the rest.

‎.claude/skills/newguide/SKILL.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
name: newguide
3+
description: Create a new developer knowledge guide from scratch — interactive workflow with plan, preview, and iteration
4+
disable-model-invocation: true
5+
argument-hint: "[topic]"
6+
---
7+
8+
# Create a New Guide
9+
10+
This is the primary authoring workflow. It is interactive, confirmation-gated, and always produces one guide HTML file and one `meta.json` file.
11+
12+
If the user provided a topic as `$ARGUMENTS`, use it as the starting point for Step 1.
13+
14+
---
15+
16+
## Step 1 — Gather Intent
17+
18+
Respond with:
19+
20+
```
21+
What would you like a guide for?
22+
23+
Describe the topic, the audience, and the format you want.
24+
Examples:
25+
"A cheatsheet for Docker Compose commands for backend devs"
26+
"A step-by-step tutorial on setting up k8s ingress with nginx"
27+
"A reference guide for kubectl commands organized by resource type"
28+
```
29+
30+
Wait for the user's free-text response.
31+
32+
---
33+
34+
## Step 2 — Analyze and Plan
35+
36+
Read the user's input and produce a **Guide Plan** covering:
37+
38+
1. **Proposed title** — clear, specific, suitable for a browser tab
39+
2. **Proposed slug** — kebab-case, 2-5 words, lowercase, hyphen-separated, no spaces or special characters. Must be unique — check `guides/` directory before proposing.
40+
3. **Proposed category** — one of: Developer Tools, Containerization, Orchestration, Cloud & Infrastructure, AI & Agents, Git & Version Control, Languages & Frameworks, System Design
41+
4. **Proposed tags** — 3-6 relevant lowercase tags
42+
5. **Proposed description** — 1-2 sentences, max 160 chars, for index card
43+
6. **Format** — one of:
44+
- `cheatsheet` — keyboard shortcuts, commands in a scannable grid layout
45+
- `tutorial` — step-by-step instructions with numbered sections
46+
- `reference` — organized lookup reference, table-heavy
47+
- `explainer` — conceptual explanation with diagrams and analogies
48+
- `recipe-book` — collection of workflow recipes, copy-paste focused
49+
7. **Proposed sections** — bullet list of sections with one-line descriptions
50+
8. **Estimated size** — rough count of commands/sections
51+
52+
Present the plan in this format:
53+
54+
```
55+
Guide Plan
56+
──────────────────────────────────────────
57+
Title: [title]
58+
Slug: [slug]
59+
Category: [category]
60+
Tags: [tag1], [tag2], [tag3]
61+
Description: [description]
62+
Format: [format]
63+
64+
Sections:
65+
• [Section 1] — [description]
66+
• [Section 2] — [description]
67+
...
68+
69+
Estimated: ~[N] items across [M] sections
70+
──────────────────────────────────────────
71+
Does this look right? (yes to proceed / describe changes)
72+
```
73+
74+
Wait for confirmation. If the user requests changes, revise and re-present. Loop until user says yes.
75+
76+
---
77+
78+
## Step 3 — Generate HTML
79+
80+
Once the plan is confirmed:
81+
82+
1. Read `.claude/docs/STYLE_GUIDE.md` fully
83+
2. Read `.claude/docs/COMPONENTS.md` fully
84+
3. Generate the complete guide HTML using the confirmed plan
85+
86+
Tell the user: `Reading style guide and components... generating guide HTML.`
87+
88+
Generate the full HTML file. Write to `guides/[slug]/index.html`.
89+
90+
HTML rules:
91+
- Must be 100% standalone — no external file references within the repo
92+
- Google Fonts CDN link is allowed (single link tag): IBM Plex Mono, Syne, Inter
93+
- All CSS in a `<style>` block in `<head>`
94+
- All JS in a `<script>` block at end of `<body>`
95+
- Use `<pre>` tags for code blocks (never `<div>`)
96+
- Include meta description tag using the guide's description field
97+
- Set `<title>` to "[guide title] — DevGuides"
98+
- Include a back link to index: `../../index.html` (relative, works on file://)
99+
- Include working search if guide has more than 15 items
100+
- Must render correctly via file:// and GitHub Pages
101+
- NEVER copy from a previous guide — always generate fresh from the spec
102+
103+
Also write `guides/[slug]/meta.json`:
104+
```json
105+
{
106+
"title": "string",
107+
"slug": "string — must match directory name",
108+
"description": "string — max 160 chars",
109+
"tags": ["lowercase", "strings"],
110+
"category": "string — from defined categories",
111+
"created": "YYYY-MM-DD",
112+
"updated": "YYYY-MM-DD",
113+
"author": "string"
114+
}
115+
```
116+
117+
After writing, report:
118+
```
119+
Guide written:
120+
guides/[slug]/index.html ([size])
121+
guides/[slug]/meta.json
122+
123+
Ready to preview.
124+
```
125+
126+
---
127+
128+
## Step 4 — Preview
129+
130+
Automatically open preview:
131+
132+
```
133+
Opening preview in your browser...
134+
```
135+
136+
Run: `open guides/[slug]/index.html` (macOS) or `xdg-open` (Linux)
137+
138+
If the command fails, tell the user:
139+
```
140+
Could not auto-open. Run this to preview:
141+
open guides/[slug]/index.html # macOS
142+
xdg-open guides/[slug]/index.html # Linux
143+
```
144+
145+
After opening, prompt:
146+
```
147+
Review the guide in your browser.
148+
• "looks good" or "yes" → proceed to publish
149+
• Describe any changes → I'll update and re-preview
150+
• "cancel" → save draft without publishing
151+
```
152+
153+
---
154+
155+
## Step 5 — Iterate (if needed)
156+
157+
If the user requests changes:
158+
1. Understand the requested changes
159+
2. Summarize what will change
160+
3. Update the HTML file in place
161+
4. Re-open the browser preview
162+
5. Return to Step 4 prompt
163+
164+
Loop until the user is satisfied.
165+
166+
---
167+
168+
## Step 6 — Hand off to Publish
169+
170+
When the user approves:
171+
```
172+
Guide approved. Run /publish [slug] to push it live.
173+
```
174+
175+
The guide is now a draft — written to disk, not yet committed or pushed.

‎.claude/skills/previewguide/SKILL.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: previewguide
3+
description: Open a guide in the browser for local preview
4+
disable-model-invocation: true
5+
argument-hint: "<slug>"
6+
---
7+
8+
# Preview a Guide
9+
10+
Open `guides/$ARGUMENTS/index.html` in the default browser immediately.
11+
12+
## With a slug
13+
14+
1. Check that `guides/[slug]/index.html` exists. If not:
15+
```
16+
No guide found at guides/[slug]/. Run /listguides to see available guides.
17+
```
18+
19+
2. Open in browser:
20+
- macOS: `open guides/[slug]/index.html`
21+
- Linux: `xdg-open guides/[slug]/index.html`
22+
23+
## Without a slug (preview the index)
24+
25+
If no slug is provided, suggest previewing the index page:
26+
27+
```
28+
To preview the index page with working links between guides:
29+
python3 -m http.server 8080
30+
Then open http://localhost:8080
31+
```

‎.claude/skills/publish/SKILL.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
name: publish
3+
description: Publish a guide to GitHub Pages — commits, rebuilds index, and pushes
4+
disable-model-invocation: true
5+
argument-hint: "<slug>"
6+
---
7+
8+
# Publish a Guide
9+
10+
Publish the guide with slug `$ARGUMENTS` to GitHub Pages.
11+
12+
If no slug is provided, list unpublished (uncommitted) guides in `guides/` and ask the user which one to publish.
13+
14+
---
15+
16+
## Step 1 — Pre-publish Check
17+
18+
Run these checks in order. If any fail, report the specific issue and stop.
19+
20+
1. Does `guides/[slug]/index.html` exist? If not: `No guide found at guides/[slug]/. Run /newguide to create one.`
21+
2. Does `guides/[slug]/meta.json` exist and contain valid JSON with all 8 required fields (title, slug, description, tags, category, created, updated, author)? If a field is missing: identify it and offer to fix it interactively.
22+
3. Is there a git repo initialized? (`git rev-parse --git-dir`)
23+
4. Is there a remote named `origin`? If not:
24+
```
25+
No git remote found. Set up GitHub Pages first:
26+
1. Create a repo on GitHub
27+
2. git remote add origin https://github.com/[user]/devpages.git
28+
3. git push -u origin main
29+
4. Enable Pages: repo Settings → Pages → Deploy from branch → main
30+
```
31+
5. Are there any merge conflicts in the working tree?
32+
33+
---
34+
35+
## Step 2 — Confirm Publish
36+
37+
Read meta.json to get the title. Determine if this is a new guide or an update (check git status).
38+
39+
Present the publish summary:
40+
41+
```
42+
Publish Summary
43+
──────────────────────────────────────────
44+
Guide: [title]
45+
Slug: [slug]
46+
URL after publish:
47+
https://[username].github.io/devpages/guides/[slug]/
48+
49+
Files to commit:
50+
+ guides/[slug]/index.html
51+
+ guides/[slug]/meta.json
52+
~ index.html (will be regenerated)
53+
54+
Commit message:
55+
feat(guide): add [title]
56+
57+
This will push to origin/main and trigger GitHub Pages deployment.
58+
Deployment takes ~30 seconds after push.
59+
──────────────────────────────────────────
60+
Proceed? (yes / no)
61+
```
62+
63+
For updates to existing guides, use commit message: `fix(guide): update [title]`
64+
65+
Wait for explicit confirmation.
66+
- Accept: "yes", "go ahead", "do it", "looks good", "ship it", "publish it"
67+
- Reject: "no", "stop", "cancel", "abort", "never mind" → stop and report what was/wasn't done
68+
69+
---
70+
71+
## Step 3 — Regenerate Index
72+
73+
Run:
74+
```bash
75+
node scripts/build-index.js
76+
```
77+
78+
Report: `Index regenerated: N guides indexed.`
79+
80+
If build fails:
81+
```
82+
Index build failed. Error:
83+
[error output]
84+
The guide files are intact. Fix the error above and re-run:
85+
node scripts/build-index.js
86+
Then commit and push manually.
87+
```
88+
89+
---
90+
91+
## Step 4 — Git Commit and Push
92+
93+
Run:
94+
```bash
95+
git pull --rebase origin main
96+
git add guides/[slug]/index.html
97+
git add guides/[slug]/meta.json
98+
git add index.html
99+
git commit -m "feat(guide): add [title]"
100+
git push origin main
101+
```
102+
103+
For updates, use: `git commit -m "fix(guide): update [title]"`
104+
105+
Show the git output and report:
106+
```
107+
Pushed to origin/main.
108+
GitHub Pages deploying... (~30 seconds)
109+
110+
Live URL:
111+
https://[username].github.io/devpages/guides/[slug]/
112+
113+
Index:
114+
https://[username].github.io/devpages/
115+
```
116+
117+
Rules:
118+
- Never force push
119+
- One commit per publish — do not bundle unrelated changes
120+
- Never commit node_modules, .DS_Store, or other junk

0 commit comments

Comments
 (0)