# How Skill Versioning and Date Tracking Work in Antigravity Awesome Skills

> Understand skill versioning and date tracking in Antigravity Awesome Skills. Learn how YAML metadata and Python scripts ensure data accuracy and manage skill updates effectively.

- Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)
- Tags: internals
- Published: 2026-03-18

---

**Skill versioning and date tracking in the Antigravity Awesome Skills repository rely on YAML front-matter metadata in [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) files, where the `version` field accepts any string format while `date_added` requires strict ISO-8601 validation, enforced by [`validate_skills.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/validate_skills.py) and managed through the [`manage_skill_dates.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/validate_skills.py).

```yaml
---
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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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:

```python
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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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 <skill-id> YYYY-MM-DD**: Changes a single skill's date

```bash

# 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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/generate_index.py) (lines 84-92) constructs skill dictionaries that include both fields:

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

```

The resulting [`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json) is consumed by the web application at [`apps/web-app/public/skills.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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:

```json
{
  "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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/generate_index.py) (lines 84-92) exports metadata to JSON for web UI consumption
- **Reporting** via [`tools/scripts/generate_skills_report.py`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/tools/scripts/generate_index.py) into [`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/generate_skills_report.py) also uses this data for coverage analytics and timeline generation.