docs: Phase 1 - Documentation & Standards Foundation

[mcj-coder]

Summary

Establish foundation documentation for consistent skills by creating the local skill format specification and skill dependency matrix.

Scope

New Files to Create

• docs/SKILL-FORMAT.md - Local specification defining required/optional sections and frontmatter fields
• docs/skill-dependency-matrix.md - Visual Mermaid diagram of skill relationships and interaction matrix

Updates Required

• Add references/README.md to all 37 skill directories with references folders

Acceptance Criteria

• docs/SKILL-FORMAT.md defines:
  • Required sections: Frontmatter, Overview, When to Use, Core Workflow
  • Optional sections: Red Flags, Examples, References
  • Frontmatter fields: name, description, priority, category, requires
• docs/skill-dependency-matrix.md contains:
  • Mermaid diagram showing skill relationships
  • Matrix showing: invokes, requires, incompatible-with relationships
• All 37 references/ directories have a README.md index file
• npm run lint passes with zero errors/warnings

Test Plan

• Lint passes: npm run lint
• All internal links in new docs resolve correctly
• References/README.md files accurately list contents of each directory

Related

Part of Skills Repository Improvement Plan (Phase 1 of 4)

[mcj-coder]

Plan

Phase 1 implementation plan from the Skills Repository Improvement Plan.

Tasks

1. Create docs/SKILL-FORMAT.md - Local skill specification extending agentskills.io

   • Required/optional sections
   • Frontmatter fields with priority model
   • Validation checklist

2. Create docs/skill-dependency-matrix.md - Dependency documentation

   • Mermaid diagrams showing relationships
   • External dependencies (Superpowers)
   • Internal dependencies matrix
   • Invocation order guidance

3. Add references/README.md to 37 skill directories

   • Index files for each references folder
   • File descriptions derived from content

Verification

• npm run lint must pass with 0 errors
• All 37 README files must be created
• Pre-commit hooks must pass

Evidence

Implementation tracked in PR #380

[mcj-coder]

Plan approved - proceeding with implementation per the Skills Repository Improvement Plan.