How Skill Versioning and Date Tracking Work in Antigravity Awesome Skills

Skill versioning and date tracking in the Antigravity Awesome Skills repository rely on YAML front-matter metadata in SKILL.md files, where the version field accepts any string format while date_added requires strict ISO-8601 validation, enforced by validate_skills.py and managed through the manage_skill_dates.py CLI.

The Antigravity Awesome Skills system tracks the evolution of capabilities through declarative metadata embedded in each skill definition. Skill versioning and date tracking are implemented via front-matter fields parsed by shared utilities in tools/scripts/validate_skills.py, then consumed by index generators to power the web interface and analytics dashboards.

Metadata Storage in SKILL.md Front-Matter

Each skill is defined by a SKILL.md file containing a YAML front-matter block that stores both versioning and chronological metadata.

The version Field

The version field is an optional string indicating the skill's release version. Unlike date_added, this field is deliberately lenient and accepts any format—semantic versioning (1.0.0), simple increments, or custom tags—without breaking CI validation. According to the source code in tools/scripts/validate_skills.py, the field is treated as an opaque string and carried through to the generated JSON index and web UI.

The date_added Field

The date_added field stores the calendar date when the skill was first added to the collection, formatted as ISO-8601 (YYYY-MM-DD). This field is optional but strongly recommended for changelog generation and coverage reporting. The validator enforces strict format compliance using the regex ^\d{4}-\d{2}-\d{2}$ at line 94 in tools/scripts/validate_skills.py.

---
name: data-cleaner
description: "Cleans CSV/JSON datasets using configurable pipelines."
version: 0.4.1
date_added: "2025-09-12"
risk: safe
source: community
---

Validation and Enforcement

The repository maintains data integrity through automated validation scripts that check metadata formats during CI and local development.

Strict Date Format Enforcement

In tools/scripts/validate_skills.py, the validation logic checks for date_added presence and format compliance. Lines 55-58 implement the ISO-8601 pattern matching, while lines 60-63 handle strict mode behavior:

if "date_added" in metadata:
    if not date_pattern.match(metadata["date_added"]):
        errors.append(
            f"❌ {rel_path}: Invalid 'date_added' format. Must be YYYY-MM-DD …"
        )
else:
    msg = f"ℹ️  {rel_path}: Missing 'date_added' field (optional, but recommended)"
    if strict_mode: warnings.append(msg)

When running with the --strict flag in CI mode, missing dates trigger hard errors; in normal mode, they emit informational warnings.

Lenient Version Handling

The version field bypasses format validation entirely. This design choice allows skill maintainers to adopt any versioning scheme without constraints, ensuring backward compatibility while still surfacing version information in the web UI and exported indices.

Managing Dates with the CLI Tool

The tools/scripts/manage_skill_dates.py utility provides bulk management capabilities for date_added metadata across the skill collection.

Available Commands

The CLI exposes four primary operations for date management:

• list: Prints all skills with their dates and coverage percentage
• add-missing [--date YYYY-MM-DD]: Inserts date_added into skills missing the field (defaults to today)
• add-all [--date YYYY-MM-DD]: Overwrites all skills' dates with the supplied value
• update YYYY-MM-DD: Changes a single skill's date

# Add missing dates with today's date

python tools/scripts/manage_skill_dates.py add-missing

# Force a specific date for all skills

python tools/scripts/manage_skill_dates.py add-all --date 2024-01-01

# Update a specific skill

python tools/scripts/manage_skill_dates.py update my-skill 2024-12-31

Implementation Details

The script parses each SKILL.md using the shared parse_frontmatter() function, merges a {"date_added": <value>} dictionary into the metadata, and rewrites the file using reconstruct_frontmatter() (lines 45-61) to preserve front-matter ordering and formatting.

Exporting Metadata to the Index and UI

Once validated, versioning and date metadata flow through the build pipeline into consumable JSON formats.

Index Generation

During the indexing process, tools/scripts/generate_index.py (lines 84-92) constructs skill dictionaries that include both fields:

if "date_added" in metadata:
    skill_info["date_added"] = metadata["date_added"]

The resulting skills_index.json is consumed by the web application at apps/web-app/public/skills.json, enabling sorting, filtering, and timeline visualizations in the UI.

Reporting and Coverage Statistics

The tools/scripts/generate_skills_report.py script aggregates metadata for analytics (lines 70-84), generating coverage reports that track what percentage of skills include date information:

{
  "generated_at": "2026-03-06T10:30:00.123456",
  "total_skills": 1234,
  "skills_with_dates": 1200,
  "skills_without_dates": 34,
  "coverage_percentage": 97.2,
  "skills": [
    {
      "id": "recent-skill",
      "name": "Recent Skill",
      "date_added": "2026-03-06",
      "version": "1.0.0"
    }
  ]
}

Typical Workflow for Maintainers

A complete workflow for adding or updating skill metadata follows this sequence:

1. Create or edit a SKILL.md file, adding version and date_added to the front-matter
2. Validate locally using npm run validate or python tools/scripts/validate_skills.py
3. Commit changes; CI runs the validator in --strict mode, rejecting malformed dates
4. Generate the index via npm run generate-index or python tools/scripts/generate_index.py
5. Deploy the web application, which automatically surfaces version badges and creation dates

Summary

• SKILL.md front-matter stores both version (lenient string) and date_added (strict ISO-8601) metadata for each skill
• Validation occurs in tools/scripts/validate_skills.py, which enforces date formatting via regex at line 94 and supports strict CI mode
• CLI management is handled by tools/scripts/manage_skill_dates.py, offering bulk add, update, and list operations while preserving file formatting through reconstruct_frontmatter()
• Index generation in tools/scripts/generate_index.py (lines 84-92) exports metadata to JSON for web UI consumption
• Reporting via tools/scripts/generate_skills_report.py tracks coverage statistics and aggregates skill timelines

Frequently Asked Questions

What happens if I omit the date_added field in my SKILL.md?

Omitting date_added is allowed but triggers an informational warning during validation. In CI environments running with --strict mode, missing dates may cause build failures depending on configuration. The web UI gracefully handles missing dates by displaying a "missing date" placeholder or null value without breaking the interface.

Can I use semantic versioning (SemVer) for the version field?

Yes. The version field accepts any string format, including semantic versioning like 1.0.0 or 2.3.5-beta. The validator in tools/scripts/validate_skills.py deliberately treats this field as an opaque string, allowing maintainers to choose their preferred versioning scheme without constraints.

How do I bulk update dates for multiple skills at once?

Use the manage_skill_dates.py CLI with the add-missing or add-all commands. Running python tools/scripts/manage_skill_dates.py add-missing inserts today's date into all skills lacking the field, while add-all --date YYYY-MM-DD overwrites every skill's date. Both commands use reconstruct_frontmatter() to preserve YAML formatting and front-matter order.

Where does the date and version information appear in the final application?

The metadata flows through tools/scripts/generate_index.py into skills_index.json, which the web application consumes to display version badges next to skill cards and creation dates in detail views. The reporting script generate_skills_report.py also uses this data for coverage analytics and timeline generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}