EPIC: Adopt Agent Skills Specification

[josecelano]

Overview

agentskills.io is an open format for extending AI agent capabilities with specialized knowledge and workflows. This epic tracks the adoption of the Agent Skills specification as a supplement to our existing AGENTS.md - not a replacement.

Key Insight: Skills vs Rules

After research, the relationship is clear:

Aspect	AGENTS.md (Rules)	Skills (SKILL.md)
Loading	Always-on, every conversation	On-demand, when task matches
Purpose	Baseline conventions, constraints	Specialist workflows, templates
Token usage	Constant overhead	Only when needed
Best for	"Always do X, never do Y"	Multi-step repeatable workflows
Updates	Rarely changes	Can be added/refined frequently

Our AGENTS.md is excellent for rules - it has 20 essential rules that should apply to every AI interaction. Skills would handle the complex workflows that we find ourselves explaining repeatedly.

Approach

This epic tracks the adoption of Agent Skills on an on-demand basis. Rather than committing to implement all potential skills upfront, we:

1. Start with scaffolding (Infrastructure Scaffolding and Foundational Skills #320): Set up infrastructure, tooling, and create two foundational skills
2. Add skills as needed: Create new skills when workflows become repetitive or complex
3. Evolve organically: The list of potential skills may change based on actual needs
4. Close when mature: Eventually close this epic and add new skills independently

Tasks

Completed

• Infrastructure Scaffolding and Foundational Skills #320 - Infrastructure Scaffolding and Foundational Skills (run-linters + add-new-skill)

Future Skills (On-Demand)

These may be implemented as separate issues when needed:

• create-environment-config - Generate valid environment configurations
• add-feature-to-deployer - Add features following DDD architecture
• troubleshoot-deployment - Systematic debugging workflows
• git-pr-workflow - Bundle commit/branch/PR conventions
• write-issue-spec - Guide using issue templates
• run-e2e-tests - E2E testing workflows with expected warnings

Goals

• Set up .github/skills/ infrastructure
• Create validation tooling integration (skills-ref)
• Add foundational skills (run-linters + add-new-skill)
• Document skills integration in AGENTS.md
• Test with GitHub Copilot

Recommended AGENTS.md Addition

Once skills are implemented, add this section to AGENTS.md:

## Auto-Invoke Skills

The project provides Agent Skills in `.github/skills/` for specialized workflows. Skills are loaded on-demand when tasks match their descriptions.

Available skills:

| Task                 | Skill to Load                               |
| -------------------- | ------------------------------------------- |
| Running linters      | `.github/skills/run-linters/skill.md`       |
| Creating new skills  | `.github/skills/add-new-skill/skill.md`     |

Skills supplement (not replace) the rules in this file. Rules apply always; skills activate when their workflows are needed.

For VS Code: Enable `chat.useAgentSkills` in settings to activate skill discovery.

Acceptance Criteria

• .github/skills/ directory exists with proper structure
• skills-ref validation tool integration documented
• At least two foundational skills created and validated
• AGENTS.md updated with Auto-Invoke Skills section
• Skills work with GitHub Copilot (tested with trigger phrases)
• Pre-commit checks pass: ./scripts/pre-commit.sh

Related Documentation

• agentskills.io Specification
• What are Skills?
• How to Create Custom Skills (Claude)
• Skill Authoring Best Practices (Claude Platform)
• Anthropic skill-creator Example
• VS Code Skills Documentation

Detailed Specification

See: docs/issues/274-consider-using-agentskills-io.md

[josecelano]

• https://github.com/eferro/augmentedcode-skills
• https://skills.sh/