Align all skills with agentskills.io specification

[JacobPEvans]

Problem

Raw Idea

All skills should fully comply with the agentskills.io specification and pass skills-ref validation (pre-commit and GitHub Actions). This is a coordinated effort with the ai-assistant-instructions repository.

Pain Points

1. Incorrect directory structure: Skills live in agentsmd/skills/ with symlinks to .claude/skills/ - this is backwards. Per the spec and Copilot docs, skills should be in .copilot/skills/, .claude/skills/, or .github/skills/ directly
2. No validation tooling: No skills-ref validation in pre-commit or GitHub Actions
3. Progressive disclosure not enforced: Token limits (name: 64 chars, description: 1024 chars, body: <5000 tokens soft, 500 lines hard) are not validated
4. No reusable GitHub Action: No centralized action for skills validation across repos with custom skills
5. Missing self-referencing: Skills don't consistently have "Related Skills" sections for cross-referencing by name (and plugin if available), never by path

Size

size:m (3-5 days) - directory restructuring, tooling integration, updating all existing skills

Solution Sketch

Concept

Restructure skills to be spec-compliant and add comprehensive validation. Consume the reusable GitHub Action from ai-assistant-instructions.

Key Changes

1. Canonical location: Move skills to .github/skills/ (works with Copilot) and symlink to .claude/skills/ and .copilot/skills/ (if needed)
2. Pre-commit validation: Add skills-ref validate hook for all skill directories
3. GitHub Action: Consume reusable workflow from ai-assistant-instructions or create local _validate-skills.yml that:
   • Runs skills-ref validate on all skills
   • Enforces progressive disclosure hard limits
   • Warns on soft limit violations
4. Progressive disclosure enforcement:
   • Hard limits: fail CI on violation
   • Soft limits: warning annotations
5. Self-referencing requirement: All skills must have a "Related Skills" section at bottom referencing related skills by name (and plugin if available), never by path

Out of Scope

• Migrating commands or agents to new locations
• Changes to plugin manifest structure
• Skill versioning or publishing

Rabbit Holes

Complexity Traps

1. Symlink compatibility: Copilot may not follow symlinks - test both approaches
2. skills-ref installation: May need Python setup in CI - consider caching
3. Token counting: skills-ref may not count tokens - may need tiktoken or similar
4. Plugin-specific considerations: Claude Code plugins may have different skill discovery

Mitigation

• Test symlink behavior with actual Copilot before committing to structure
• Use uv for fast Python dependency installation in CI
• Implement token counting as separate step if skills-ref lacks it
• Verify Claude Code plugin skill loading matches spec requirements

Done Looks Like

Acceptance Criteria

• Skills in spec-compliant directory structure (.github/skills/ or vendor-specific)
• Pre-commit hook validates skills with skills-ref
• GitHub Action validates skills (reusable or local)
• Progressive disclosure limits enforced:
  • name: max 64 chars (hard)
  • description: max 1024 chars (hard)
  • SKILL.md body: 500 lines (hard), <5000 tokens (soft warning)
• All skills have "Related Skills" section with name-based references
• All existing skills pass validation
• Documentation updated with new skill creation guidelines

Related

• Linked issue: Align all skills with agentskills.io specification ai-assistant-instructions#425
• Reference: https://agentskills.io/specification
• Reference: https://github.com/agentskills/agentskills/tree/main/skills-ref
• Reference: https://docs.github.com/en/copilot/concepts/agents/about-agent-skills