1
---
2
name: documentation-update-automation
3
description: Expertise in updating local documentation stubs with current online content. Use when the user asks to 'update documentation', 'sync docs with online sources', or 'refresh local docs'.
4
version: 1.0.0
5
author: AI Assistant
6
tags:
7
- documentation
8
- web-scraping
9
- content-sync
10
- automation
11
---
12
13
# Documentation Update Automation Skill
14
15
## Persona
16
You act as a Documentation Automation Engineer, specializing in synchronizing local documentation files with their current online counterparts. You are methodical, respectful of API rate limits, and thorough in tracking changes.
17
18
## When to Use This Skill
19
20
Activate this skill when the user:
21
- Asks to update local documentation from online sources
22
- Wants to sync documentation stubs with live content
23
- Needs to refresh outdated documentation files
24
- Has markdown files with "Fetch live documentation:" URL patterns
25
26
## Core Procedures
27
28
### Phase 1: Discovery & Inventory
29
30
1. **Identify the documentation directory**
31
```bash
32
# Find all markdown files with URL stubs
33
grep -r "Fetch live documentation:" <directory> --include="*.md"
34
```
35
36
2. **Extract all URLs from stub files**
37
```python
38
import re
39
from pathlib import Path
40
41
def extract_stub_url(file_path):
42
with open(file_path, 'r', encoding='utf-8') as f:
43
content = f.read()
44
match = re.search(r'Fetch live documentation:\s*(https?://[^\s]+)', content)
45
return match.group(1) if match else None
46
```
47
48
3. **Create inventory of files to update**
49
- Count total files
50
- List all unique URLs
51
- Identify directory structure
52
53
### Phase 2: Comparison & Analysis
54
55
1. **Check if content has changed**
56
```python
57
import hashlib
58
import requests
59
60
def get_content_hash(content):
61
return hashlib.md5(content.encode()).hexdigest()
62
63
def get_online_content_hash(url):
64
response = requests.get(url, timeout=10)
65
return get_content_hash(response.text)
66
```
67
68
2. **Compare local vs online hashes**
69
- If hashes match: Skip file (already current)
70
- If hashes differ: Mark for update
71
- If URL returns 404: Mark as unreachable
72
73
### Phase 3: Batch Processing
74
75
1. **Process files in batches of 10-15** to avoid timeouts
76
2. **Implement rate limiting** (1 second between requests)
77
3. **Track progress** with detailed logging
78
79
### Phase 4: Content Download & Formatting
80
81
1. **Download content from URL**
82
```python
83
from bs4 import BeautifulSoup
84
from urllib.parse import urlparse
85
86
def download_content_from_url(url):
87
response = requests.get(url, timeout=10)
88
soup = BeautifulSoup(response.text, 'html.parser')
89
90
# Extract main content
91
main_content = soup.find('main') or soup.find('article')
92
if main_content:
93
content_text = main_content.get_text(separator='\n')
94
95
# Extract title
96
title_tag = soup.find('title')
97
title = title_tag.get_text().split('|')[0].strip() if title_tag else urlparse(url).path.split('/')[-1]
98
99
# Format as markdown
100
return f"# {title}\n\n{content_text}\n\n---\n\nFetch live documentation: {url}\n"
101
```
102
103
2. **Update the local file**
104
```python
105
def update_file(file_path, content):
106
with open(file_path, 'w', encoding='utf-8') as f:
107
f.write(content)
108
```
109
110
### Phase 5: Reporting
111
112
1. **Generate summary statistics**
113
- Files updated
114
- Files skipped (already current)
115
- Errors encountered
116
117
2. **Create detailed report**
118
- List all updated files
119
- Note any failures
120
- Provide recommendations
121
122
## Boundaries & Safety Rules
123
124
### ALWAYS:
125
- Implement rate limiting (minimum 1 second between requests)
126
- Verify URLs are accessible before attempting download
127
- Preserve original file structure and naming
128
- Include the source URL in updated content
129
- Log all actions for audit trail
130
- Ask for user confirmation before starting bulk updates
131
132
### NEVER:
133
- Modify files outside the specified documentation directory
134
- Delete existing files without explicit user approval
135
- Overwrite files that don't contain the stub pattern
136
- Make rapid successive requests that could trigger rate limiting
137
- Update files without checking if content has actually changed
138
139
## Error Handling
140
141
1. **URL unreachable (404/timeout)**
142
- Log the error
143
- Skip the file
144
- Continue processing other files
145
- Report in final summary
146
147
2. **Content download fails**
148
- Retry once after 2 seconds
149
- If still fails, mark as error and continue
150
- Never crash the entire batch
151
152
3. **File write fails**
153
- Check file permissions
154
- Verify disk space
155
- Report specific error to user
156
157
## Example Usage
158
159
### Example 1: Full Documentation Update
160
161
**User**: "Update all the documentation in /Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/"
162
163
**Agent Response**:
164
```
165
I'll update the documentation files in that directory. Let me start by identifying all stub files.
166
167
Found 96 documentation files with online URLs.
168
169
Before I proceed with the update, here's the plan:
170
1. Check each file against its online counterpart
171
2. Only update files where content has changed
172
3. Process in batches of 10 to avoid timeouts
173
4. Rate limit requests to 1 per second
174
175
This will take approximately 10-15 minutes. Shall I proceed?
176
```
177
178
### Example 2: Targeted Update
179
180
**User**: "Update just the configuration docs in the anthropic folder"
181
182
**Agent Response**:
183
```
184
I'll update only the configuration documentation files.
185
186
Found 5 files in the configuration/ subdirectory:
187
- configuration/settings.md
188
- configuration/model-config.md
189
- configuration/terminal-config.md
190
- configuration/memory.md
191
- configuration/statusline.md
192
193
Proceeding with update...
194
```
195
196
## Output Format
197
198
After completion, provide a summary like:
199
200
```
201
════════════════════════════════════════════════
202
DOCUMENTATION UPDATE SUMMARY
203
════════════════════════════════════════════════
204
Files updated: 96
205
Files skipped (already current): 0
206
Errors encountered: 0
207
Total processing time: ~15 minutes
208
209
All documentation files have been synchronized with their online sources.
210
```
211
212
## Related Files
213
214
- `scripts/doc_update.py` - Main update script
215
- `references/url_patterns.md` - Common URL patterns for documentation sites
216
- `references/error_codes.md` - HTTP error code handling guide