Agent skill

artifact-metadata

View SKILL.md on GitHub Repository
Stars 107
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/jmagly/aiwg/tree/main/agentic/code/addons/aiwg-utils/skills/artifact-metadata

SKILL.md

artifact-metadata

Manage artifact metadata, versioning, ownership, and history tracking.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

  • "tag this artifact" → metadata tagging
  • "classify [artifact]" → artifact metadata assignment

Purpose

This skill provides consistent metadata management for all SDLC and marketing artifacts. It tracks ownership, versioning, review history, and status across the artifact lifecycle.

Behavior

When triggered, this skill:

  1. Locates or creates metadata:

    • Check for existing metadata.json alongside artifact
    • Create new metadata if none exists
    • Validate against metadata schema

  2. Updates metadata fields:

    • Version (semantic versioning)
    • Status (draft, review, baselined, deprecated)
    • Owner (agent or user)
    • Reviewers (list of reviewing agents)
    • Timestamps (created, modified, baselined)

  3. Tracks history:

    • Version history with change summaries
    • Review records with reviewer and outcome
    • Approval records

  4. Validates relationships:

    • Parent/child artifact links
    • Requirement traceability links
    • Cross-references to related artifacts

Metadata Schema

json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["artifact_id", "name", "type", "version", "status", "owner"],
  "properties": {
    "artifact_id": {
      "type": "string",
      "description": "Unique identifier (e.g., SAD-001, UC-003)"
    },
    "name": {
      "type": "string",
      "description": "Human-readable artifact name"
    },
    "type": {
      "type": "string",
      "enum": ["requirements", "architecture", "test", "security", "deployment", "marketing", "report"]
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Semantic version"
    },
    "status": {
      "type": "string",
      "enum": ["draft", "review", "approved", "baselined", "deprecated"]
    },
    "owner": {
      "type": "string",
      "description": "Primary owner (agent name or user)"
    },
    "created": {
      "type": "string",
      "format": "date-time"
    },
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "baselined": {
      "type": "string",
      "format": "date-time"
    },
    "reviewers": {
      "type": "array",
      "items": {"type": "string"}
    },
    "history": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "version": {"type": "string"},
          "date": {"type": "string", "format": "date-time"},
          "author": {"type": "string"},
          "summary": {"type": "string"}
        }
      }
    },
    "reviews": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "reviewer": {"type": "string"},
          "date": {"type": "string", "format": "date-time"},
          "outcome": {"type": "string", "enum": ["approved", "conditional", "rejected"]},
          "comments": {"type": "string"}
        }
      }
    },
    "traceability": {
      "type": "object",
      "properties": {
        "requirements": {"type": "array", "items": {"type": "string"}},
        "parent": {"type": "string"},
        "children": {"type": "array", "items": {"type": "string"}}
      }
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

Usage Examples

Create New Metadata

User: "Create metadata for the SAD"

Skill creates:
.aiwg/architecture/sad/metadata.json
{
  "artifact_id": "SAD-001",
  "name": "Software Architecture Document",
  "type": "architecture",
  "version": "0.1.0",
  "status": "draft",
  "owner": "architecture-designer",
  "created": "2025-12-08T14:30:00Z",
  "modified": "2025-12-08T14:30:00Z",
  "reviewers": [],
  "history": [],
  "reviews": []
}

Update Version After Changes

User: "Version the SAD to 1.0.0 with summary 'Initial baseline'"

Skill updates:
- version: "1.0.0"
- status: "baselined"
- baselined: "2025-12-08T16:45:00Z"
- history: [adds entry with version, date, summary]

Record Review

User: "Record security-architect review as approved"

Skill updates:
- reviews: [adds review record]
- reviewers: [adds "security-architect" if not present]
- modified: [updates timestamp]

Query Ownership

User: "Who owns the test plan?"

Skill responds:
"Test Plan (TP-001) is owned by test-architect.
Status: review
Version: 0.3.0
Last modified: 2025-12-07
Reviewers: security-auditor, requirements-analyst"

Status Lifecycle

draft → review → approved → baselined
  ↑        ↓
  └── rejected (returns to draft)

baselined → deprecated (end of life)

Status Transitions

From To Triggered By
draft review Submit for review
review approved All reviewers approve
review draft Any reviewer rejects
approved baselined Formal baseline action
baselined deprecated Superseded or retired

Version Conventions

  • 0.x.x: Draft versions (not baselined)
  • 1.0.0: First baseline
  • x.y.0: Minor changes (compatible)
  • x.0.0: Major changes (may break traceability)

Auto-Version Rules

Change Type Version Bump
Typo fix patch (0.0.x)
Section update minor (0.x.0)
Structure change major (x.0.0)
Initial baseline 1.0.0

Artifact Type Conventions

Type ID Prefix Location
requirements UC-, REQ-, NFR- .aiwg/requirements/
architecture SAD-, ADR-, API- .aiwg/architecture/
test TP-, TC-, TS- .aiwg/testing/
security TM-, SEC- .aiwg/security/
deployment DP-, RN- .aiwg/deployment/
marketing CB-, CA- .aiwg/marketing/
report RPT- .aiwg/reports/

CLI Usage

bash
# Create metadata for artifact
python artifact_metadata.py --create --artifact ".aiwg/architecture/sad.md" --type architecture

# Update version
python artifact_metadata.py --version "1.0.0" --artifact ".aiwg/architecture/sad.md" --summary "Initial baseline"

# Record review
python artifact_metadata.py --review --artifact ".aiwg/architecture/sad.md" \
  --reviewer "security-architect" --outcome "approved" --comments "LGTM"

# Query metadata
python artifact_metadata.py --query --artifact ".aiwg/architecture/sad.md"

# List all artifacts by status
python artifact_metadata.py --list --status "review"

# Validate all metadata
python artifact_metadata.py --validate-all

Integration

This skill integrates with:

  • artifact-orchestration: Sets initial metadata when creating artifacts
  • gate-evaluation: Checks artifact status for gate criteria
  • traceability-check: Uses traceability links in metadata
  • template-engine: Copies metadata template on instantiation

Output Locations

  • Metadata file: {artifact-dir}/metadata.json
  • Alternatively: {artifact-dir}/{artifact-name}.metadata.json
  • Index file: .aiwg/reports/artifact-index.json

References

  • Schema: schemas/artifact-metadata.schema.json
  • Conventions: AIWG Artifact Naming Guide

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

jmagly/aiwg

research-document

Generate summaries and literature notes from research papers

107 15
Explore
jmagly/aiwg

research-archive

Package research artifacts for long-term archival

107 15
Explore
jmagly/aiwg

research-cite

Format citations and generate bibliographies

107 15
Explore
jmagly/aiwg

induct-research

Induct research sources into a research repository. Point at an issue, a single file, a directory of papers, or a URI and the skill reads, annotates, and files structured induction tasks — one per source. Similar to address-issues but for research corpora instead of code backlogs.

107 15
Explore
jmagly/aiwg

research-provenance

Query provenance chains and artifact relationships

107 15
Explore
jmagly/aiwg

research-quality

Assess source quality using GRADE methodology

107 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results