Restructure skills to GitHub Agent Skills specification format

[Copilot]

The skills in .github/skills/ were flat markdown files without YAML frontmatter, preventing GitHub Copilot agents from properly recognizing and selecting them.

Changes

Directory Structure

• Converted flat files to subdirectory format (e.g., backend-api.md → backend-api/SKILL.md)
• All skill files now named SKILL.md (uppercase, per spec)

YAML Frontmatter

Added required frontmatter to all skills:

---
name: backend-api
description: FastAPI patterns with layered architecture, typing, and dependency injection. Use when creating new API endpoints, implementing REST APIs, or structuring service layers.
---

• name: lowercase-with-hyphens format
• description: explains what the skill does and when to use it (enables automatic skill selection by context)

Skills Updated

• backend-api - FastAPI patterns with layered architecture
• error-handling - Exception handling and JSON error responses
• frontend-react - React component patterns with TypeScript
• git-workflow - Git workflow and conventional commits
• infrastructure - Docker and container orchestration
• multiarch-cicd - Multi-arch Docker CI/CD with GHCR
• testing - Unit, integration, and E2E test patterns

All original content (examples, checklists, code blocks) preserved unchanged.

Original prompt

Fix GitHub Agent Skills Format

Problem

The current skills in .github/skills/ are not following the official GitHub Agent Skills format specification, which means they may not be recognized or used by GitHub Copilot agents.

Required Changes

1. Directory Structure

Restructure skills from flat files to subdirectory format:

Current (incorrect):

.github/skills/
├── backend-api.md
├── error-handling.md
├── frontend-react.md
├── git-workflow.md
├── infrastructure.md
├── multiarch-cicd.md
└── testing.md

Required:

.github/skills/
├── backend-api/
│   └── SKILL.md
├── error-handling/
│   └── SKILL.md
├── frontend-react/
│   └── SKILL.md
├── git-workflow/
│   └── SKILL.md
├── infrastructure/
│   └── SKILL.md
├── multiarch-cicd/
│   └── SKILL.md
└── testing/
    └── SKILL.md

2. File Format Requirements

Each SKILL.md file must have:

• YAML frontmatter with name and description fields
• File name must be SKILL.md (all caps)
• Name field: lowercase with hyphens (e.g., backend-api)
• Description field: Clear explanation of what the skill does and when to use it

Template:

---
name: skill-name-here
description: What this skill does and when Copilot should use it
---

# Skill Title

Rest of content...

3. Specific Transformations

backend-api.md → backend-api/SKILL.md

Add frontmatter:

---
name: backend-api
description: FastAPI patterns with layered architecture, typing, and dependency injection. Use when creating new API endpoints, implementing REST APIs, or structuring service layers.
---

error-handling.md → error-handling/SKILL.md

Add frontmatter:

---
name: error-handling
description: Exception handling and JSON error response patterns. Use when implementing API error handling, creating custom exception classes, or standardizing error responses.
---

frontend-react.md → frontend-react/SKILL.md

Add frontmatter:

---
name: frontend-react
description: React component patterns with TypeScript, hooks, and composition. Use when creating new React components, managing component state, or implementing hooks.
---

git-workflow.md → git-workflow/SKILL.md

Add frontmatter:

---
name: git-workflow
description: Git workflow and deployment patterns using conventional commits. Use when making commits, creating branches, or opening pull requests.
---

infrastructure.md → infrastructure/SKILL.md

Add frontmatter:

---
name: infrastructure
description: Docker, container orchestration, and deployment patterns. Use when creating Dockerfiles, configuring docker-compose, setting up CI/CD, or managing container resources.
---

multiarch-cicd.md → multiarch-cicd/SKILL.md

Add frontmatter (update the existing description):

---
name: multiarch-cicd
description: Multi-arch Docker CI/CD with GitHub Actions and GHCR deployment. Use when setting up Docker-based projects for multiple architectures (amd64/arm64), supporting ARM devices, or creating production-ready deployment with pre-built images.
---

testing.md → testing/SKILL.md

Add frontmatter:

---
name: testing
description: Unit, integration, and E2E test patterns using pytest and Jest. Use when writing tests for features, debugging failing tests, or setting up test infrastructure.
---

4. Content Preservation

• Keep ALL existing content in each file
• Only add YAML frontmatter at the top
• Keep all examples, checklists, and documentation unchanged
• Preserve all code blocks and formatting

5. Cleanup

After moving files to the new structure, delete the old flat files:

• Delete .github/skills/backend-api.md
• Delete .github/skills/error-handling.md
• Delete .github/skills/frontend-react.md
• Delete .github/skills/git-workflow.md
• Delete .github/skills/infrastructure.md
• Delete .github/skills/multiarch-cicd.md
• Delete .github/skills/testing.md

Expected Outcome

After this PR:

• ✅ All skills follow GitHub Agent Skills specification
• ✅ Skills will be properly recognized by GitHub Copilot agents
• ✅ Skills can be automatically selected based on task context
• ✅ Skills can be manually invoked by name
• ✅ All existing content is preserved

Reference

• GitHub Docs: About Agent Skills

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.