Skip to content

Commit 53096b7

Browse files
GhostTypesGhostTypes
committed
docs: Update README, add skill
1 parent 16c1b66 commit 53096b7

7 files changed

Lines changed: 1160 additions & 41 deletions

File tree

‎.claude/settings.local.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@
1212
"Bash(grep:*)",
1313
"WebFetch(domain:github.blog)",
1414
"Bash(.gradlew dependencies:*)",
15-
"mcp__gradle-mcp-server__gradle_dependencies"
15+
"mcp__gradle-mcp-server__gradle_dependencies",
16+
"Skill(readme-generator)"
1617
],
1718
"deny": [],
1819
"ask": []

‎.claude/skills/readme-generator/SKILL.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
---
2+
name: readme-generator
3+
description: Generate professionally formatted README.md files following a specific centered table-based structure. Use when creating or reformatting README files for GitHub repositories, particularly for Ghost's projects across 48hour-solutions, Automotive-9, LLMTooling, MCDxAI, Orbital-8, Parallel-7, and GhostTypes organizations. Triggers include "create a readme", "reformat this readme", "update the readme", or any request to document a repository.
4+
---
5+
6+
# README Generator
7+
8+
This skill generates README.md files following a specific centered, table-based structure with strict formatting rules.
9+
10+
## Core Layout Structure
11+
12+
Every README follows this exact top section structure:
13+
14+
```markdown
15+
<div align="center">
16+
17+
# Project Title
18+
19+
![Icon](icon-url-here)
20+
_if icon available_
21+
22+
**One-line summary/tagline describing the project**
23+
24+
![Badge1](shield-url) ![Badge2](shield-url) ![Badge3](shield-url)
25+
26+
**Bold statement highlighting the core value proposition**
27+
28+
</div>
29+
```
30+
31+
## Strict Formatting Rules
32+
33+
### NEVER USE
34+
- ❌ Emojis (anywhere in the document)
35+
- ❌ Standalone bulleted lists (bullets within table cells are OK)
36+
37+
### ALWAYS USE
38+
- ✓ Centered layout for all elements except standalone code blocks
39+
- ✓ Tables for all feature lists, steps, workflows, and organized content
40+
- ✓ Markdown formatting within table cells
41+
- ✓ shields.io badges with appropriate colors matching the tech stack
42+
43+
### Special Rules for Code Blocks
44+
45+
**CRITICAL**: Markdown code blocks CANNOT be placed inside `<div align="center">` tags as it breaks GitHub rendering.
46+
47+
- If a code block is needed outside a table → place it WITHOUT center tags
48+
- All other elements → MUST be centered
49+
- Code blocks within table cells → perfectly fine
50+
51+
## Badge Generation
52+
53+
### Always Use shields.io
54+
55+
Format: `https://img.shields.io/badge/{LABEL}-{MESSAGE}-{COLOR}?style=flat`
56+
57+
### Color Selection Strategy
58+
59+
Match colors to the technology/library branding:
60+
- **Status badges**: `purple` for preview/beta, `brightgreen` for stable, `yellow` for experimental
61+
- **Minecraft**: `0ea5e9` (light blue)
62+
- **Fabric Loader**: `f59e0b` (amber)
63+
- **Java**: `orange` or `007396`
64+
- **Python**: `3776ab` or `yellow`
65+
- **TypeScript**: `3178c6`
66+
- **Node.js**: `339933`
67+
- **Vue**: `4fc08d`
68+
- **React**: `61dafb`
69+
70+
### Version Discovery Process
71+
72+
**REQUIRED**: Before generating badges, examine the codebase:
73+
74+
1. **JavaScript/TypeScript projects**: Check `package.json` for dependencies
75+
2. **Java projects**: Check `build.gradle`, `build.gradle.kts`, `pom.xml`
76+
3. **Python projects**: Check `pyproject.toml`, `requirements.txt`, `setup.py`
77+
4. **Other languages**: Look for standard dependency files
78+
79+
**If you cannot find version information → ASK before generating the README**
80+
81+
Use actual version numbers when found, or "latest" as fallback only if user confirms.
82+
83+
## Content Structure
84+
85+
All content sections use clean, centered tables with two columns:
86+
87+
```markdown
88+
<div align="center">
89+
90+
| Category/Label | Details/Description |
91+
| --- | --- |
92+
| **First Item** | Detailed information with **markdown** and `code` |
93+
| **Second Item** | More details • Sub-bullets OK here • Another point |
94+
95+
</div>
96+
```
97+
98+
### Standard Section Pattern
99+
100+
Follow this structure closely (based on meteor-client-webgui):
101+
102+
1. **Feature Highlights** - Key capabilities in table format
103+
2. **Quick Start** - Installation and setup steps in table format
104+
3. **Development Workflow** - Commands and development info in table format
105+
106+
### Table Design Guidelines
107+
108+
- **Left column**: Short, bold labels or categories (1-3 words)
109+
- **Right column**: Detailed information with full markdown support
110+
- **Within cells**: Use `•` for sub-points, `**bold**` for emphasis, `` `code` `` for commands
111+
- **Multi-line content**: Perfectly fine within cells
112+
- **Code blocks in cells**: Use triple backticks with language identifier
113+
114+
Example of rich table cell content:
115+
116+
```markdown
117+
| **Installation** | 1. Download the latest `.jar` from releases<br>2. Copy to `.minecraft/mods/`<br>3. Launch with Fabric profile |
118+
```
119+
120+
## Codebase Analysis Process
121+
122+
### When NO existing README exists
123+
124+
**REQUIRED**: Thoroughly analyze the codebase before writing:
125+
126+
1. **Identify the project type** (library, application, tool, addon, etc.)
127+
2. **Find the tech stack** (languages, frameworks, dependencies)
128+
3. **Discover features** by examining:
129+
- Main source files and their public APIs
130+
- Configuration files and what they configure
131+
- Build scripts and what they produce
132+
- Documentation comments in code
133+
- Example/test files showing usage
134+
4. **Extract version information** from dependency files
135+
5. **Identify setup requirements** (install steps, dependencies, system requirements)
136+
6. **Note any special considerations** (permissions, compatibility, known issues)
137+
138+
**Never guess or hallucinate features** - only document what's actually in the code.
139+
140+
### When existing README exists
141+
142+
**Default behavior**: Reformat to the centered table structure while preserving factual content
143+
144+
Process:
145+
1. Extract all factual information (features, versions, installation steps, etc.)
146+
2. Strip out emojis completely
147+
3. Convert bulleted lists to centered tables
148+
4. Reorganize into the standard section structure
149+
5. Update badge formatting to shields.io style
150+
6. Ensure all elements are properly centered (except standalone code blocks)
151+
7. Keep the same level of technical detail
152+
153+
**Exception**: If user says "rewrite" or indicates content changes needed, then also revise the content itself.
154+
155+
## Section Guidelines
156+
157+
### Features/Highlights Section
158+
159+
Format as a table with specific feature areas:
160+
161+
```markdown
162+
<div align="center">
163+
164+
| Capability | Details |
165+
| --- | --- |
166+
| **Feature Name** | Clear description of what it does and why it matters |
167+
| **Another Feature** | Technical details with code examples if needed |
168+
169+
</div>
170+
```
171+
172+
### Quick Start Section
173+
174+
Format as a table with numbered steps or clear categories:
175+
176+
```markdown
177+
<div align="center">
178+
179+
| Step | Instructions |
180+
| --- | --- |
181+
| **1. Requirements** | List dependencies • version requirements • system requirements |
182+
| **2. Installation** | Download, install, setup commands |
183+
| **3. First Run** | How to verify it works |
184+
185+
</div>
186+
```
187+
188+
### Development Workflow Section
189+
190+
Format as a table organizing by component or task:
191+
192+
```markdown
193+
<div align="center">
194+
195+
| Component | Commands / Actions |
196+
| --- | --- |
197+
| **Build** | `./gradlew build` – Compiles and packages |
198+
| **Test** | `npm test` – Runs test suite |
199+
| **Dev Server** | `npm run dev` – Hot reload on localhost:3000 |
200+
201+
</div>
202+
```
203+
204+
## Tone and Style
205+
206+
- **Professional and technical**: Direct, clear, factual
207+
- **No fluff**: Every sentence should provide value
208+
- **Scannable**: Users should quickly find what they need
209+
- **Complete but concise**: Include necessary details without verbosity
210+
211+
## Contributing Section
212+
213+
**DO NOT INCLUDE** a Contributing section unless explicitly requested.
214+
215+
Ghost adds this manually when needed.
216+
217+
## Example Reference
218+
219+
Reference implementation: https://github.com/MCDxAI/meteor-client-webgui/blob/main/README.md
220+
221+
Study this README closely for:
222+
- Exact centering approach
223+
- Table structure and formatting
224+
- Badge selection and colors
225+
- Section organization
226+
- Markdown within tables
227+
- Professional technical tone
228+
229+
## Validation Checklist
230+
231+
Before presenting the README, verify:
232+
233+
- [ ] All elements centered (except standalone code blocks)
234+
- [ ] Zero emojis anywhere
235+
- [ ] No standalone bulleted lists
236+
- [ ] All features/steps in table format
237+
- [ ] Badges use shields.io with appropriate colors
238+
- [ ] Version numbers are real (from codebase) or confirmed with user
239+
- [ ] Code blocks outside tables are NOT in center tags
240+
- [ ] Professional, technical tone maintained
241+
- [ ] Contributing section NOT included

0 commit comments

Comments
 (0)