Documentation Automation Skill

Automate documentation maintenance with consistent versioning and metadata.

Core Functions

1. File Metadata Standard

Every tracked file should have metadata. Format depends on file type:

Markdown Files (.md)

---
version: "1.0.0"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
author: "agent-name or user"
status: "draft|active|deprecated"
---

JSON Files (.json)

{
  "_meta": {
    "version": "1.0.0",
    "created": "YYYY-MM-DD",
    "updated": "YYYY-MM-DD",
    "schema": "schema-name"
  }
}

TypeScript/JavaScript (in comments)

/**
 * @version 1.0.0
 * @created YYYY-MM-DD
 * @updated YYYY-MM-DD
 * @author agent-name
 */

2. Versioning Rules

Follow semantic versioning:

• Major (X.0.0): Breaking changes, complete rewrites
• Minor (0.X.0): New features, significant additions
• Patch (0.0.X): Bug fixes, small updates, metadata changes

3. Automatic Metadata Updates

When editing files:

1. Check if metadata exists
2. If missing, add with version 1.0.0
3. If exists, increment version appropriately
4. Update updated date to today
5. Keep created date unchanged

4. Version Tracking File

Maintain .ai/versions.json for project-wide version tracking:

{
  "_meta": {
    "version": "1.0.0",
    "updated": "YYYY-MM-DD"
  },
  "files": {
    "path/to/file.md": {
      "version": "1.2.0",
      "created": "YYYY-MM-DD",
      "updated": "YYYY-MM-DD",
      "changelog": [
        {
          "version": "1.2.0",
          "date": "YYYY-MM-DD",
          "change": "Added section X"
        },
        {
          "version": "1.1.0",
          "date": "YYYY-MM-DD",
          "change": "Expanded examples"
        },
        {
          "version": "1.0.0",
          "date": "YYYY-MM-DD",
          "change": "Initial creation"
        }
      ]
    }
  }
}

Tracked File Types

| Type | Track Versions | Metadata Location | | --------- | -------------- | ----------------- | | .md | Yes | YAML frontmatter | | .json | Yes | _meta property | | .ts/.js | Optional | JSDoc header | | .py | Optional | Module docstring | | Skills | Yes | YAML frontmatter | | Agents | Yes | YAML frontmatter |

Commands

Add Metadata to File

When creating or significantly updating a file:

1. Add appropriate metadata header
2. Set version to 1.0.0 if new, increment if existing
3. Update versions.json

Validate Documentation

Check all tracked files:

• Have proper metadata
• Versions match versions.json
• No stale files (updated > 90 days ago)

Generate Changelog

Extract changes from versions.json for release notes

Hook Integration

This skill works with the progress-save hook to automatically:

1. Track files modified in session
2. Update versions.json on session end
3. Ensure metadata consistency

Token Efficiency

• Metadata adds ~50 tokens per MD file
• versions.json is centralized, not loaded per-file
• Only load file versions when needed for comparison