Skip to content

Commit c3952fa

Browse files
yepzdkclaude
yepzdk
and
claude
committed
feat: add documentation skill for README and technical docs
Add itkdev-documentation skill that helps generate README files and technical documentation following AarhusAI documentation style guidelines. Features: - Project type auto-detection (Drupal, Symfony, Node.js, Python) - README template with standard sections - Technical documentation templates (deployment, architecture, API) - ITK Dev Docker project documentation support - Style guide based on AarhusAI documentation conventions Closes #6 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent f57c877 commit c3952fa

2 files changed

Lines changed: 337 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
### Added
1111

12+
- Documentation skill (`itkdev-documentation`) for generating README files and technical documentation
13+
- Follows AarhusAI documentation style guidelines
14+
- Templates for README, deployment guides, architecture docs, and API documentation
15+
- ITK Dev Docker project documentation support
16+
- Project type auto-detection
1217
- Auto-release workflow for MCP dependency updates
1318
- Daily scheduled check for new MCP releases (8:30 UTC)
1419
- Automated version bump and release creation when updates detected

‎skills/itkdev-documentation.md‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
---
2+
name: itkdev-documentation
3+
description: Technical documentation and README generation for ITK Dev projects. Use when asked to create, update, or improve documentation, README files, deployment guides, architecture docs, or API documentation. Follows ITK Dev documentation standards with clear structure and procedural content.
4+
---
5+
6+
# Documentation Generation Guide
7+
8+
You are assisting with technical documentation for ITK Dev projects. This skill covers README files, deployment guides, architecture documentation, and operational runbooks.
9+
10+
## When to Activate
11+
12+
Use this skill when the user asks to:
13+
- Create or update a README file
14+
- Write technical documentation
15+
- Generate deployment or installation guides
16+
- Document architecture or API endpoints
17+
- Create operational runbooks
18+
19+
## Project Detection
20+
21+
Before generating documentation, detect the project type by checking for:
22+
23+
| Project Type | Indicators |
24+
|--------------|------------|
25+
| Drupal | `*.info.yml`, `web/modules/`, `drupal/core` in composer.json |
26+
| Symfony | `symfony/framework-bundle` in composer.json, `config/bundles.php` |
27+
| Node.js | `package.json`, `node_modules/` |
28+
| Python | `requirements.txt`, `pyproject.toml`, `setup.py` |
29+
| Docker | `Dockerfile`, `docker-compose.yml` |
30+
| ITK Dev Docker | `itkdev-docker-compose` references, `.docker/` directory |
31+
32+
Tailor documentation structure and content to the detected project type.
33+
34+
## Documentation Style Guide
35+
36+
Follow these conventions based on the [AarhusAI documentation style](https://aarhusai.github.io/documentation/):
37+
38+
### Structure
39+
40+
1. **Hierarchical headings** with clear navigation
41+
- H1 (`#`): Main document title
42+
- H2 (`##`): Major sections
43+
- H3 (`###`): Subsections
44+
45+
2. **Logical section flow**
46+
- Overview/Introduction first
47+
- Prerequisites and requirements
48+
- Step-by-step procedures
49+
- Configuration reference
50+
- Troubleshooting (if applicable)
51+
52+
### Content Conventions
53+
54+
1. **Variables and placeholders**: Use angle brackets for values that must be replaced
55+
```
56+
<DOMAIN_NAME>
57+
<API_KEY>
58+
<DATABASE_PASSWORD>
59+
```
60+
61+
2. **Code blocks**: Use fenced code blocks with language identifiers
62+
```bash
63+
# Shell commands
64+
docker compose up -d
65+
```
66+
67+
3. **Callouts**: Use bold for important notes
68+
```markdown
69+
**NOTE:** Critical information here.
70+
71+
**WARNING:** Potentially destructive operation.
72+
```
73+
74+
4. **Cross-references**: Link to related documentation and external resources
75+
76+
5. **Procedural format**: Number steps for sequential operations, use bullets for non-sequential items
77+
78+
## README Template
79+
80+
When generating a README, include these sections as appropriate:
81+
82+
```markdown
83+
# Project Name
84+
85+
Brief description of what the project does and its purpose.
86+
87+
## Requirements
88+
89+
- Requirement 1
90+
- Requirement 2
91+
92+
## Installation
93+
94+
Step-by-step installation instructions.
95+
96+
### Development Setup
97+
98+
```bash
99+
# Clone the repository
100+
git clone <REPOSITORY_URL>
101+
cd <PROJECT_NAME>
102+
103+
# Install dependencies
104+
<INSTALL_COMMAND>
105+
106+
# Start development server
107+
<START_COMMAND>
108+
```
109+
110+
## Configuration
111+
112+
| Variable | Description | Default |
113+
|----------|-------------|---------|
114+
| `VAR_NAME` | What it does | `default_value` |
115+
116+
## Usage
117+
118+
How to use the project with examples.
119+
120+
## Development
121+
122+
### Running Tests
123+
124+
```bash
125+
<TEST_COMMAND>
126+
```
127+
128+
### Code Standards
129+
130+
```bash
131+
<LINT_COMMAND>
132+
```
133+
134+
## Deployment
135+
136+
Brief deployment instructions or link to deployment docs.
137+
138+
## Contributing
139+
140+
Link to contribution guidelines or brief instructions.
141+
142+
## License
143+
144+
License information.
145+
```
146+
147+
## Technical Documentation Templates
148+
149+
### Deployment Guide Template
150+
151+
```markdown
152+
# Deployment Guide
153+
154+
## Overview
155+
156+
Brief description of the deployment architecture and process.
157+
158+
## Prerequisites
159+
160+
- Prerequisite 1
161+
- Prerequisite 2
162+
163+
## Variables
164+
165+
| Variable | Description |
166+
|----------|-------------|
167+
| `<VARIABLE>` | What this variable represents |
168+
169+
## Deployment Steps
170+
171+
### 1. Environment Setup
172+
173+
Description of what this step accomplishes.
174+
175+
```bash
176+
# Commands for this step
177+
```
178+
179+
### 2. Configuration
180+
181+
Description of configuration needed.
182+
183+
### 3. Deployment
184+
185+
Actual deployment commands.
186+
187+
### 4. Verification
188+
189+
How to verify the deployment succeeded.
190+
191+
## Troubleshooting
192+
193+
### Common Issue 1
194+
195+
**Symptom:** Description of the problem.
196+
197+
**Solution:** How to fix it.
198+
```
199+
200+
### Architecture Documentation Template
201+
202+
```markdown
203+
# Architecture Overview
204+
205+
## System Components
206+
207+
Description of major system components and their responsibilities.
208+
209+
## Data Flow
210+
211+
How data moves through the system.
212+
213+
## External Dependencies
214+
215+
Services and APIs the system depends on.
216+
217+
## Diagram
218+
219+
Include diagrams where helpful (Mermaid, ASCII, or image references).
220+
```
221+
222+
### API Documentation Template
223+
224+
```markdown
225+
# API Reference
226+
227+
## Authentication
228+
229+
How to authenticate with the API.
230+
231+
## Endpoints
232+
233+
### `GET /endpoint`
234+
235+
**Description:** What this endpoint does.
236+
237+
**Parameters:**
238+
239+
| Name | Type | Required | Description |
240+
|------|------|----------|-------------|
241+
| `param` | string | Yes | Description |
242+
243+
**Response:**
244+
245+
```json
246+
{
247+
"key": "value"
248+
}
249+
```
250+
251+
**Example:**
252+
253+
```bash
254+
curl -X GET https://api.example.com/endpoint
255+
```
256+
```
257+
258+
## ITK Dev Docker Projects
259+
260+
For projects using ITK Dev Docker infrastructure, include:
261+
262+
### Standard README Sections
263+
264+
```markdown
265+
## Development Setup
266+
267+
### Prerequisites
268+
269+
- Docker and Docker Compose
270+
- [itkdev-docker-compose](https://github.com/itk-dev/itkdev-docker-compose) CLI
271+
272+
### Getting Started
273+
274+
1. Clone the repository:
275+
```bash
276+
git clone <REPOSITORY_URL>
277+
cd <PROJECT_NAME>
278+
```
279+
280+
2. Start the Docker environment:
281+
```bash
282+
docker compose up -d
283+
```
284+
285+
3. Install dependencies:
286+
```bash
287+
itkdev-docker-compose composer install
288+
```
289+
290+
4. Access the site:
291+
```bash
292+
itkdev-docker-compose open
293+
```
294+
295+
### Common Tasks
296+
297+
| Task | Command |
298+
|------|---------|
299+
| Clear cache | `itkdev-docker-compose drush cr` |
300+
| Export config | `itkdev-docker-compose drush cex -y` |
301+
| Import config | `itkdev-docker-compose drush cim -y` |
302+
| Run tests | `task ci` |
303+
```
304+
305+
### Taskfile Integration
306+
307+
If a `Taskfile.yml` exists, document available tasks:
308+
309+
```markdown
310+
## Available Tasks
311+
312+
Run `task` to see all available tasks. Common tasks:
313+
314+
| Task | Description |
315+
|------|-------------|
316+
| `task dev:setup` | Initial project setup |
317+
| `task ci` | Run all CI checks |
318+
| `task config:export` | Export Drupal configuration |
319+
```
320+
321+
## Quality Checklist
322+
323+
Before finalizing documentation, verify:
324+
325+
- [ ] All placeholders use angle bracket notation (`<VALUE>`)
326+
- [ ] Code blocks have language identifiers
327+
- [ ] Steps are numbered for sequential operations
328+
- [ ] Prerequisites are listed before instructions
329+
- [ ] Commands are copy-paste ready
330+
- [ ] Links to external resources are included where helpful
331+
- [ ] No sensitive information (passwords, keys) in examples
332+
- [ ] Documentation matches the actual project state

0 commit comments

Comments
 (0)