Establish two-tier skill directory structure and canonical skill interface

[ahouseholder]

Summary

Bootstrap the skills infrastructure in the SSVC repository by establishing a two-tier directory structure (skills/dev/ and skills/ssvc/) and defining a canonical SKILL.md format. This replaces the informal .agents/skills/ layout and lays the groundwork for SSVC domain skills.

Background

The repository currently has 4 project skills under .agents/skills/ (load-specs, study-project-docs, ingest-idea, process-concerns). These are dev-workflow skills — they support SSVC development itself. A second category is needed: SSVC domain skills that help users do SSVC work (e.g., evaluate a decision point for a vulnerability, build a custom decision table). The two tiers have different audiences, lifecycles, and discovery contexts.

The existing SKILL.md frontmatter format is also inconsistent across the 4 skills. A canonical format is needed before the skill surface grows further.

What already exists (not in scope)

• specs/ directory with 9 YAML spec files — established ✅
• docs/reference/codebase/ architecture docs — established ✅
• Domain registry: specs/registry.yaml + src/ssvc/registry/ — established ✅
• Several CI/CD workflows (pytest, doctools, lint) — established ✅

Proposed deliverables

1. Restructure skill directories

• Move .agents/skills/{load-specs,study-project-docs,ingest-idea,process-concerns} → skills/dev/
• Create skills/ssvc/ as the home for SSVC domain skills

2. Placeholder domain skill

• Add skills/ssvc/evaluate-decision-point/SKILL.md as a WIP stub
• Purpose: walk through evaluating a single SSVC decision point for a vulnerability (not "a CVE" — CVE IDs are not synonymous with vulnerabilities)
• Stub should have complete frontmatter but minimal procedure, clearly marked as WIP

3. Canonical SKILL.md format

Define a canonical frontmatter schema. Required fields: name, description. Optional/recommended: id, version, runtime (language, package_manager, framework), capabilities, prerequisites, env, usage_examples, tags. Example:

---
name: "Python Pytest Runner"
id: "python-pytest-uv"
description: "Executes Python unit and integration tests using pytest within a uv virtual environment."
version: "1.0.0"
runtime:
  language: "python"
  package_manager: "uv"
  framework: "pytest"
capabilities:
  - "Run specific test files or directories using `uv run pytest`"
prerequisites:
  - "uv installed on the host system"
usage_examples:
  - prompt: "run the authentication tests"
    command: "uv run pytest tests/test_auth.py"
tags:
  - "python"
  - "testing"
---

4. Update existing dev skills

Update all 4 dev skills to conform to the canonical format.

5. skills/README.md

Document the dev/ vs ssvc/ split, the canonical SKILL.md format, and how to add new skills.

6. specs/skills.yaml

Formalize skill conformance requirements as a spec (YAML, same pattern as other specs in specs/).

7. CI validation

Add a CI check that validates all skills/**/SKILL.md files: valid YAML frontmatter + required fields present.

Out of scope / future directions

• Shared dev-skills repo (cross-pollination with Vultron) — noted as future direction
• Skill discovery registry — not needed (agents self-discover from directory structure)
• Local skill testing fixtures / replay / debugging — separate future idea
• Porting additional dev skills from Vultron — separate follow-up

Notes

This work does NOT touch the existing specs/ system, domain registry, or Python source. It is purely about the skills/ directory structure, SKILL.md format, and CI enforcement.

[ahouseholder]

✅ Ingested.

• PR: Bootstrap formal specification infrastructure, agent skills, and codebase reference docs #1142 (specs_bootstrap — added in commit 36bfa68)
• Implementation issue: Implement two-tier skill directory structure and canonical SKILL.md (SK spec) #1154

Design decisions captured in specs/skills.yaml and notes/skills.md.