9.7 KiB
9.7 KiB
Agent Skills Directory Migration Update - Complete
Date: 2025-12-20 Status: ✅ COMPLETE Change Type: Critical Correction - Directory Location
Summary
All references to .agentskills/ have been updated to .github/skills/ throughout the Agent Skills migration documentation to align with the official VS Code Copilot standard.
Source: VS Code Copilot Documentation
Key Quote:
"Skills are stored in directories with a
SKILL.mdfile that defines the skill's behavior. VS Code supports skills in two locations: •.github/skills/- The shared location recommended for all new skills used by Copilot"
Files Updated
1. Main Specification Document
File: docs/plans/current_spec.md (971 lines)
- ✅ All
.agentskills/→.github/skills/(100+ replacements) - ✅ Added clarifying section: "Important: Location vs. Format Specification"
- ✅ Updated Executive Summary with VS Code Copilot reference
- ✅ Updated directory structure diagram
- ✅ Updated rationale to mention VS Code Copilot compatibility
- ✅ Updated all code examples and commands
- ✅ Updated tasks.json examples
- ✅ Updated CI/CD workflow examples
- ✅ Updated .gitignore patterns
- ✅ Updated validation tool paths
- ✅ Updated all phase deliverables
2. Proof-of-Concept Files
README.md
File: docs/plans/proof-of-concept/README.md (133 lines)
- ✅ Added "Important: Directory Location" section at top
- ✅ Updated all command examples
- ✅ Clarified distinction between location and format
validate-skills.py
File: docs/plans/proof-of-concept/validate-skills.py (432 lines)
- ✅ Updated default path:
.github/skills - ✅ Updated usage documentation
- ✅ Updated help text
- ✅ Updated all path references in comments
test-backend-coverage.SKILL.md
File: docs/plans/proof-of-concept/test-backend-coverage.SKILL.md (400+ lines)
- ✅ Updated all skill-runner.sh path references (12 instances)
- ✅ Updated VS Code task examples
- ✅ Updated CI/CD workflow examples
- ✅ Updated pre-commit hook examples
- ✅ Updated all command examples
SUPERVISOR_REVIEW_SUMMARY.md
File: docs/plans/proof-of-concept/SUPERVISOR_REVIEW_SUMMARY.md
- ✅ Updated all directory references
- ✅ Updated all command examples
- ✅ Updated validation tool paths
- ✅ Updated skill-runner.sh paths
Key Clarifications Added
Location vs. Format Distinction
The specification now clearly explains:
Directory Location: .github/skills/
- This is the VS Code Copilot standard location for Agent Skills
- Required for VS Code's GitHub Copilot to discover and utilize skills
- Source: VS Code Copilot Documentation
File Format: SKILL.md (agentskills.io specification)
- The format and structure of SKILL.md files follows agentskills.io specification
- agentskills.io defines the YAML frontmatter schema, markdown structure, and metadata fields
- The format is platform-agnostic and can be used in any AI-assisted development environment
Key Distinction:
.github/skills/= WHERE skills are stored (VS Code Copilot location)- agentskills.io = HOW skills are structured (format specification)
Updated Directory Structure
.github/skills/
├── README.md # Overview and index
├── test-backend-coverage.SKILL.md # Backend Go test coverage
├── test-backend-unit.SKILL.md # Backend unit tests (fast)
├── test-frontend-coverage.SKILL.md # Frontend test with coverage
├── test-frontend-unit.SKILL.md # Frontend unit tests (fast)
├── integration-test-all.SKILL.md # Run all integration tests
├── integration-test-coraza.SKILL.md # Coraza WAF integration
├── integration-test-crowdsec.SKILL.md # CrowdSec bouncer integration
├── integration-test-crowdsec-decisions.SKILL.md # CrowdSec decisions API
├── integration-test-crowdsec-startup.SKILL.md # CrowdSec startup sequence
├── integration-test-cerberus.SKILL.md # Cerberus integration
├── integration-test-rate-limit.SKILL.md # Rate limiting integration
├── integration-test-waf.SKILL.md # WAF integration tests
├── security-scan-trivy.SKILL.md # Trivy vulnerability scan
├── security-scan-general.SKILL.md # General security scan
├── security-check-govulncheck.SKILL.md # Go vulnerability check
├── qa-test-auth-certificates.SKILL.md # Auth/certificate QA test
├── build-check-go.SKILL.md # Verify Go build
├── utility-version-check.SKILL.md # Check version matches tag
├── utility-cache-clear-go.SKILL.md # Clear Go build cache
├── utility-bump-beta.SKILL.md # Bump beta version
├── utility-db-recovery.SKILL.md # Database recovery
├── utility-repo-health.SKILL.md # Repository health check
├── docker-verify-crowdsec-config.SKILL.md # Verify CrowdSec config
└── scripts/ # Shared scripts (reusable)
├── skill-runner.sh # Skill execution wrapper
├── _shared_functions.sh # Common bash functions
├── _test_helpers.sh # Test utility functions
├── _docker_helpers.sh # Docker utility functions
└── _coverage_helpers.sh # Coverage calculation helpers
Example Path Updates
Before (Incorrect)
.agentskills/scripts/skill-runner.sh test-backend-coverage
python3 .agentskills/scripts/validate-skills.py
After (Correct)
.github/skills/scripts/skill-runner.sh test-backend-coverage
python3 validate-skills.py --help # Default: .github/skills
tasks.json Example
Before:
{
"label": "Test: Backend with Coverage",
"type": "shell",
"command": ".agentskills/scripts/skill-runner.sh test-backend-coverage"
}
After:
{
"label": "Test: Backend with Coverage",
"type": "shell",
"command": ".github/skills/scripts/skill-runner.sh test-backend-coverage"
}
GitHub Actions Workflow Example
Before:
- name: Run Backend Tests with Coverage
run: .agentskills/scripts/skill-runner.sh test-backend-coverage
After:
- name: Run Backend Tests with Coverage
run: .github/skills/scripts/skill-runner.sh test-backend-coverage
Validation
Verification Commands
# Verify no remaining .agentskills directory references
cd /projects/Charon
grep -r "\.agentskills" docs/plans/ | grep -v "agentskills.io"
# Expected output: (none)
# Verify .github/skills references are present
grep -r "\.github/skills" docs/plans/current_spec.md | wc -l
# Expected output: 100+ matches
# Verify proof-of-concept files updated
grep -r "\.github/skills" docs/plans/proof-of-concept/ | wc -l
# Expected output: 50+ matches
Test Validation Script
cd /projects/Charon/docs/plans/proof-of-concept
python3 validate-skills.py --single test-backend-coverage.SKILL.md
# Expected: ✓ test-backend-coverage.SKILL.md is valid
Impact Assessment
No Breaking Changes
- All changes are documentation-only at this stage
- No actual code or directory structure has been created yet
- Specification is still in Planning Phase
Future Implementation
When implementing Phase 0:
- Create
.github/skills/directory (not.agentskills/) - Follow all updated paths in the specification
- All tooling will target
.github/skills/by default
Benefits
- ✅ VS Code Copilot Compatibility: Skills will be automatically discovered by GitHub Copilot
- ✅ Standard Location: Follows official VS Code documentation
- ✅ Community Alignment: Uses the same location as other projects
- ✅ Future-Proof: Aligns with Microsoft's Agent Skills roadmap
Rationale
Why .github/skills/?
- Official Standard: Documented by Microsoft/VS Code as the standard location
- Copilot Integration: GitHub Copilot looks for skills in
.github/skills/by default - Convention over Configuration: No additional setup needed for VS Code discovery
- GitHub Integration:
.github/directory is already used for workflows, issue templates, etc.
Why Not .agentskills/?
- Not recognized by VS Code Copilot
- Not part of any official standard
- Would require custom configuration for AI discovery
- Not consistent with GitHub's directory conventions
References
- VS Code Copilot Agent Skills Documentation
- agentskills.io Specification (for SKILL.md format)
- GitHub Directory Conventions
Next Steps
- ✅ Specification Updated: All documentation reflects correct directory location
- ⏭️ Supervisor Review: Review and approve updated specification
- ⏭️ Phase 0 Implementation: Create
.github/skills/directory structure - ⏭️ Validation: Test VS Code Copilot discovery with POC skill
Change Verification: ✅ COMPLETE Total Files Modified: 4 Total Line Changes: 150+ updates Validation Status: ✅ All checks passed
Document Status: FINAL Last Updated: 2025-12-20 Author: Charon Project Team