tools-only Add Documentation Updater
Orchestrate adding automated documentation updater to target Claude skills. Follow the proven pattern from gitlab-skill's sync_gitlab_docs.py.
Purpose: Create a self-maintaining documentation pipeline that downloads upstream docs, processes markdown for AI consumption, transforms links for local navigation, and enforces cooldown periods between updates.
Template: doc-updater-template.md
Process: Collect 6 template variables from the user, substitute into template, delegate implementation through 5-phase workflow with quality gates at each stage.
Orchestration Workflow
flowchart TD
Start([Skill invoked with target path]) --> P0[Phase 0: Collect Variables<br>via AskUserQuestion]
P0 --> P1[Phase 1: Implementation<br>delegate to @python-cli-architect]
P1 --> P2[Phase 2: Code Review<br>delegate to @python-code-reviewer]
P2 --> P3[Phase 3: Quality Gates<br>ruff, mypy, pyright, prek]
P3 --> P4[Phase 4: Testing & Validation<br>7-point checklist]
P4 --> P5[Phase 5: Integration<br>SKILL.md, .gitignore, integration test]
P5 --> Complete([Documentation updater ready])
P1 -.->|Failure| Loop1[Return to Phase 1<br>with error context]
P2 -.->|Failure| Loop1
P3 -.->|Failure| Loop1
P4 -.->|Failure| Loop1
P5 -.->|Failure| Loop1
Loop1 -.-> P1
Phase 0 — Collect Variables
Step 1: Validate target path
Read the path from $ARGUMENTS:
- Verify directory exists and contains SKILL.md
- If path missing or invalid, use AskUserQuestion to request correct path
Step 2: Infer defaults
Extract reasonable defaults to reduce user input:
- SKILL_NAME: Extract from target directory name
- COOLDOWN_DAYS: Default to 7
Step 3: Collect all 6 template variables
Use AskUserQuestion for each variable. Present defaults where available.
1. SKILL_NAME — Skill identifier
- Default: inferred from target directory name
- Example:
gitlab-skill - Used for: script naming, gitignore comments
2. DOC_SOURCE_URL — Documentation archive URL
- Must be downloadable tar.gz or zip containing markdown files
- Example:
https://gitlab.com/gitlab-org/cli/-/archive/main/cli-main.tar.gz?path=docs - Supports: GitHub, GitLab, direct archive links
3. DOC_PATH_IN_ARCHIVE — Path to extract from archive
- Relative path within the downloaded archive
- Example:
docsordoc/ci - Leave empty to extract entire archive
4. LOCAL_DOC_DIR — Local directory name for downloaded docs
- Stored under
{target-path}/references/{LOCAL_DOC_DIR}/ - Example:
ciorglab-cli - Keep short, descriptive, filesystem-safe
5. DOC_DESCRIPTION — Brief description
- Used in: execution protocol comments, gitignore annotations
- Example:
GitLab CI/CD pipeline documentation - Keep under 80 characters
6. COOLDOWN_DAYS — Days between automatic updates
- Typical range: 3-7
- Default: 7
- Prevents excessive upstream requests
Step 4: Confirm before proceeding
Display all collected values in structured format. Ask user to confirm before entering Phase 1.
Phase 1 — Implementation
Activate Python development workflow
Invoke /python3-development skill to load Python development orchestration standards.
Prepare substituted template
- Read doc-updater-template.md
- Extract content from
## Full Prompt Templatesection (between 5-backtick code fence delimiters) - Substitute all 6
{VARIABLE}placeholders with collected values:{SKILL_NAME}→ collected SKILL_NAME{DOC_SOURCE_URL}→ collected DOC_SOURCE_URL{DOC_PATH_IN_ARCHIVE}→ collected DOC_PATH_IN_ARCHIVE{LOCAL_DOC_DIR}→ collected LOCAL_DOC_DIR{DOC_DESCRIPTION}→ collected DOC_DESCRIPTION{COOLDOWN_DAYS}→ collected COOLDOWN_DAYS
Delegate to Python CLI architect
Use Task tool to delegate to @python-cli-architect agent:
- Prompt: The complete substituted template
- Context: Target script path is
{target-path}/scripts/update-{LOCAL_DOC_DIR}-docs.py - Requirements: All technical specifications from template (PEP 723, atomic operations, link transformation, cooldown logic)
Wait for implementation completion before proceeding to Phase 2.
Phase 2 — Code Review
Delegate to code reviewer
Use Task tool to delegate to @python-code-reviewer agent:
- Target: Script created in Phase 1
- Review criteria:
- Correctness: Logic matches requirements
- Performance: Efficient file operations, appropriate caching
- Security: ReDoS-safe regex patterns, safe path operations
- Atomicity: Lock file writes use atomic operations
- Link transformation: Path-aware relative link handling
Critical review points
- Regex patterns: Check for catastrophic backtracking vulnerabilities
- Path operations: Verify use of
pathlib.Path, no string concatenation for paths - Lock file handling: Confirm atomic write-then-rename pattern
- Error handling: Appropriate exceptions, no silent failures
- Link transformation: Correct handling of
./,../, absolute paths
On failure: Loop back to Phase 1 with specific review feedback. Pass reviewer comments to @python-cli-architect along with original template.
Phase 3 — Quality Gates
Execute sequentially. Each step gates the next. All must pass before proceeding to Phase 4.
Step 1: Format
ruff format {script-path}
Rationale: Format first to prevent lint errors on whitespace and style issues.
Step 2: Lint
ruff check {script-path}
Rationale: Catch code smells, style violations, common bugs after formatting.
Step 3: Type checking
mypy {script-path}
pyright {script-path}
Rationale: Validate type annotations and inference after style compliance.
Step 4: Pre-commit hooks
uv run prek run --files {script-path}
Rationale: Final validation against all repository standards (YAML, markdown, executables, shebangs).
On failure: Loop back to Phase 1. Pass specific error output to @python-cli-architect along with original template and instruction to fix the identified issue.
Phase 4 — Testing & Validation
Execute 7-point validation checklist. All must pass.
1. Initial execution
uv run {script-path} --working-dir {target-path}
Expected: Script completes successfully, exit code 0.
2. File existence verification
ls -la {target-path}/references/{LOCAL_DOC_DIR}/
Expected: Downloaded markdown files present in target directory.
3. Hugo shortcode removal
grep -r "{{< details" {target-path}/references/{LOCAL_DOC_DIR}/ | wc -l
Expected: 0 matches. All Hugo-specific syntax removed.
4. Link transformation sampling
Read 3-5 random markdown files from downloaded docs. Verify:
- Internal links use
./relative paths - External links use raw repository URLs (not web UI URLs)
- No broken link references
5. SKILL.md integration
Verify Documentation Index section created or updated in target SKILL.md with correct file references.
6. Cooldown enforcement
uv run {script-path} --working-dir {target-path}
Expected: Script exits with code 0 and message indicating update blocked by cooldown.
7. Force flag bypass
uv run {script-path} --working-dir {target-path} --force
Expected: Script re-downloads and processes documentation despite cooldown.
On failure: Loop back to Phase 1 with specific failure details. Include: which validation step failed, observed behavior, expected behavior.
Phase 5 — Integration
5a. Update target SKILL.md
Add or update ## Execution Protocol section in target skill's SKILL.md:
## Execution Protocol
1. Update documentation (enforces {COOLDOWN_DAYS}-day cooldown):
```bash
uv run scripts/update-{LOCAL_DOC_DIR}-docs.py --working-dir .
Use --force flag to bypass cooldown and force immediate update.
- [Rest of existing execution protocol steps...]
Position documentation update as first step in execution protocol. Include cooldown information and force flag usage.
**5b. Update .gitignore**
Add entries for lock files and downloaded documentation:
```text
# {SKILL_NAME} documentation sync
*/.update-{LOCAL_DOC_DIR}-docs.lock
{target-path}/references/{LOCAL_DOC_DIR}/
Ensure paths are relative to repository root. Add section header comment for clarity.
5c. Integration test
Use Task tool to spawn general-purpose agent with minimal WHAT-only prompt:
Use the {SKILL_NAME} skill to [accomplish task requiring documentation access].
Do NOT tell the agent:
- WHERE the documentation is located
- HOW to access it
- THAT an updater exists
Verify agent:
- Discovers skill naturally
- Follows execution protocol automatically
- Accesses downloaded documentation without guidance
- Completes task successfully
On failure: Loop back to Phase 1 if integration test reveals missing execution protocol steps, incorrect documentation paths, or inaccessible references.
Error Handling
Phase 0 failures (invalid path, missing variables):
- Resolve interactively with user via AskUserQuestion
- Do not proceed to Phase 1 until all variables collected and confirmed
Phase 1-5 failures (implementation, review, quality, testing, integration):
- All loop back to Phase 1 with error context
- Pass to
@python-cli-architectagent:- Original substituted template (full requirements)
- Specific error context from failing phase
- Instruction to fix identified issue
- Restart workflow from Phase 1 with updated implementation
Maximum iterations:
- No hard limit on loop-back iterations
- Each iteration includes progressively more context about previous failure modes
- If 3+ iterations fail at same phase, escalate to user with detailed failure analysis
Success Criteria
Documentation updater integration complete when:
- Script passes all quality gates (ruff, mypy, pyright, prek)
- All 7 validation tests pass
- Target SKILL.md includes execution protocol with documentation update step
- .gitignore entries prevent committing lock files and downloaded docs
- Integration test demonstrates autonomous skill discovery and documentation access
- Cooldown mechanism prevents excessive upstream requests
- Force flag allows manual override when needed
Report completion with summary of created/modified files and next steps for user.