Infrastructure Scaffolding and Foundational Skills

[josecelano]

Overview

This issue sets up the complete infrastructure for Agent Skills and creates two foundational skills. This includes directory structure, integration tooling, validation setup, and documentation.

Two foundational skills:

1. run-linters: Simple, frequently-used workflow to validate the format
2. add-new-skill: Meta-skill documenting how to create new skills (makes the system self-documenting)

Why these two?: run-linters proves the basic concept with a simple workflow, while add-new-skill enables easy addition of future skills without returning to this documentation.

Specification

See detailed specification: docs/issues/320-infrastructure-scaffolding-and-foundational-skills.md

Goals

Infrastructure

• Create .github/skills/ directory structure
• Install and configure skills-ref validation tool
• Document VS Code configuration for Agent Skills (chat.useAgentSkills setting)
• Add "Auto-Invoke Skills" section to AGENTS.md

Skills

• Create run-linters skill with proper frontmatter and instructions
• Create add-new-skill meta-skill
• Validate both skills using skills-ref tool

Testing & Validation

• Test skills with GitHub Copilot
• Verify skills activate on trigger phrases
• Ensure all validations pass

Implementation Plan

Phase 1: Infrastructure Setup

1. Create directory structure
2. Install validation tools (skills-ref)
3. Configure VS Code
4. Update AGENTS.md

Phase 2: Create run-linters Skill

1. Create skill.md with frontmatter and instructions
2. Optionally create references/linters.md with detailed linter information
3. Validate with skills-ref validate
4. Test with GitHub Copilot

Phase 3: Create add-new-skill Skill

1. Create skill.md following Anthropic's skill-creator pattern
2. Create reference files with specification, patterns, and examples
3. Validate with skills-ref validate
4. Test with GitHub Copilot

Phase 4: Documentation

1. Update AGENTS.md with Auto-Invoke Skills section
2. Document the scaffolding for future contributors
3. Test end-to-end workflow

Phase 5: Final Validation

1. Run skills-ref validate on all skills
2. Test both skills with various trigger phrases
3. Verify GitHub Copilot discovers and activates skills correctly

Acceptance Criteria

Infrastructure

• .github/skills/ directory exists with proper structure
• skills-ref tool is installed and documented
• VS Code configuration is documented
• AGENTS.md includes "Auto-Invoke Skills" section

Skills Created

• .github/skills/run-linters/skill.md exists with valid frontmatter
• run-linters skill passes validation
• run-linters skill activates on trigger phrases
• run-linters skill successfully guides linting workflow
• Optional references/linters.md created with detailed information
• .github/skills/add-new-skill/skill.md exists with valid frontmatter
• add-new-skill follows Anthropic's skill-creator pattern
• Reference files created (specification.md, patterns.md, examples.md)
• add-new-skill skill passes validation
• add-new-skill skill activates on trigger phrases

Validation

• Both skills pass skills-ref validate with no errors
• Frontmatter YAML is valid for both skills
• Names follow naming rules (lowercase, hyphens only, 1-64 chars)
• All file references use relative paths from skill root

Quality Checks

• Pre-commit checks pass: ./scripts/pre-commit.sh

Related Links

• Parent Epic: EPIC: Adopt Agent Skills Specification #274 - Adopt Agent Skills Specification
• Specification: docs/issues/320-infrastructure-scaffolding-and-foundational-skills.md
• Agent Skills Specification: https://agentskills.io/specification
• Anthropic skill-creator: https://github.com/anthropics/skills/tree/main/skills/skill-creator

Labels

task, roadmap, documentation, agent-skills