Skip to content

Commit a609109

Browse files
yepzdkyepzdk
authored
Merge pull request #16 from itk-dev/feature/issue-6-documentation-skill
feat: add documentation skill for README and technical docs
2 parents c94e919 + 5984b37 commit a609109

2 files changed

Lines changed: 336 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
- Drupal development skill for code auditing, module/theme development, and configuration management (Drupal 10/11)
1318
- ADR (Architecture Decision Record) skill for creating and managing architectural decisions
1419
- Auto-release workflow for MCP dependency updates

‎skills/itkdev-documentation.md‎

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

0 commit comments

Comments
 (0)