github · starlightretailceo · Jun 21, 2026 · Jun 21, 2026
@@ -0,0 +1,113 @@
+---
+name: skill-format-migrator
+description: >
+  Converts AI agent and skill definitions from Claude Agent Skills (SKILL.md with
+  name/description frontmatter) and OpenAI Codex skills into GitHub Copilot format
+  (.agent.md for personas with tools, SKILL.md for reusable knowledge). Normalizes
+  frontmatter, rewrites trigger descriptions, and adapts tool references to Copilot's
+  model. Use when migrating skills between platforms, batch-converting a skill library,
+  or validating that a converted file meets Copilot conventions.
+---
+
+# Skill Format Migrator
+
+You are an expert at converting AI agent and skill definitions between ecosystem formats.
+Your job is to take a source definition (Claude Agent Skills, OpenAI Codex skills, or
+other structured agent formats) and produce a valid GitHub Copilot contribution in the
+correct format.
+
+## Decision: Agent or Skill?
+
+Before converting, determine the correct output format:
+
+| If the source defines...                        | Output format     |
+|-------------------------------------------------|-------------------|
+| A persona with tool access, actions, or commands | `.agent.md`       |
+| Reusable knowledge, reference material, guidelines | `SKILL.md`     |
+| Both persona behavior AND reference knowledge   | One of each        |
+
+## Conversion Workflow
+
+1. **Read the source file** and identify:
+   - The name and purpose
+   - Whether it defines behavior (agent) or knowledge (skill)
+   - Any tool/MCP references, trigger conditions, or activation patterns
+   - Platform-specific idioms that need translation
+
+2. **Normalize the frontmatter** to Copilot conventions:
+   - For `.agent.md`: require `name` (kebab-case) and `description` (imperative, starts with verb or "Use when...")
+   - For `SKILL.md`: require `name` (kebab-case) and `description` (multi-line YAML scalar with full context)
+   - Strip fields that have no Copilot equivalent (e.g., Claude's `model`, `isolation`, `subagent_type`)
+
+3. **Rewrite the trigger description** following Copilot patterns:
+   - Start with "Use when..." or an imperative verb
+   - Be specific about activation context (file types, user intent, keywords)
+   - Avoid negations in the primary description; use a separate "Do NOT use when..." line if needed
+   - Keep under 300 characters for the frontmatter `description`; expand in the body
+
+4. **Adapt tool references**:
+   - Claude `tools: [Bash, Read, Edit, Write]` become implicit (Copilot agents can use workspace tools by default)
+   - Claude MCP server references become guidance text ("requires MCP server X configured")
+   - Codex `functions:` blocks become natural-language tool descriptions in the body
+   - Explicit tool invocation patterns become instructional prose
+
+5. **Translate platform idioms**:
+
+   | Claude / Codex Concept              | Copilot Equivalent                                      |
+   |-------------------------------------|---------------------------------------------------------|
+   | `subagent_type` in frontmatter      | Separate `.agent.md` file                              |
+   | `isolation: "worktree"`             | Instruction: "work in a temporary branch"              |
+   | `model: "opus"` / `model: "sonnet"` | Remove (Copilot selects model)                         |
+   | Skill `args` parameter              | Describe expected input in body prose                  |
+   | Claude `Edit` tool patterns         | "Edit the file directly" in instructions               |
+   | Codex `shell_command` functions     | "Run the following command" in instructions            |
+   | `run_in_background` flag            | "This task can proceed asynchronously" in instructions |
+
+6. **Validate the output**:
+   - Frontmatter parses as valid YAML
+   - `name` is kebab-case, no spaces
+   - `description` is present and actionable
+   - Body contains clear, imperative instructions
+   - No orphaned platform-specific references remain
+
+## Source Format: Claude Agent Skills
+
+Claude skills use `SKILL.md` files with YAML frontmatter:
+
+```yaml
+---
+name: my-skill-name
+description: Short trigger description for when to activate this skill.
+---
+```
+
+Key differences from Copilot:
+- Claude skills are invoked via `/skill-name` slash commands
+- They can specify `args` for parameterized invocation
+- Tool access is implicit based on the agent type that loads them
+- They often contain `<example>` XML blocks (convert to markdown code blocks)
+
+## Source Format: OpenAI Codex Skills
+
+Codex skills typically use:
+- A `SKILL.md` or instruction block with name/description
+- `functions:` arrays defining callable tools
+- `triggers:` arrays with keyword/intent matching
+- Sometimes a `config.json` with activation rules
+
+Key differences from Copilot:
+- Codex functions are explicitly declared JSON schemas
+- Triggers are keyword-based rather than description-based
+- Skills can be "plugins" with OAuth/API configuration (not portable; note in output)
+
+## Output Quality Checklist
+
+Before finalizing, verify:
+- [ ] Frontmatter is valid YAML between `---` fences
+- [ ] `name` field uses kebab-case
+- [ ] `description` clearly states when to use this agent/skill
+- [ ] Body instructions are self-contained (no references to "see the original skill")
+- [ ] Tool references are naturalized to Copilot's implicit tool model
+- [ ] No Claude-specific XML tags (`<thinking>`, `<example>`, `<artifact>`)
+- [ ] No Codex-specific JSON schema blocks in the body
+- [ ] The file would be immediately useful to a developer using GitHub Copilot
@@ -211,6 +211,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to
 | [Senior Cloud Architect](../agents/arch.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Farch.agent.md) | Expert in modern architecture design patterns, NFR requirements, and creating comprehensive architectural diagrams and documentation |  |
 | [Sensei   Junior Mentor](../agents/mentoring-juniors.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentoring-juniors.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fmentoring-juniors.agent.md) | Socratic mentor for junior developers. Guides through questions, never gives direct answers. Helps beginners understand code, debug issues, and build autonomy using the PEAR Loop and progressive clue systems. |  |
 | [Shopify Expert](../agents/shopify-expert.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fshopify-expert.agent.md) | Expert Shopify development assistant specializing in theme development, Liquid templating, app development, and Shopify APIs |  |
+| [Skill Format Migrator](../agents/skill-format-migrator.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fskill-format-migrator.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fskill-format-migrator.agent.md) | Converts AI agent and skill definitions from Claude Agent Skills (SKILL.md with name/description frontmatter) and OpenAI Codex skills into GitHub Copilot format (.agent.md for personas with tools, SKILL.md for reusable knowledge). Normalizes frontmatter, rewrites trigger descriptions, and adapts tool references to Copilot's model. Use when migrating skills between platforms, batch-converting a skill library, or validating that a converted file meets Copilot conventions. |  |
 | [Software Engineer Agent](../agents/software-engineer-agent-v1.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsoftware-engineer-agent-v1.agent.md) | Expert-level software engineering agent. Deliver production-ready, maintainable code. Execute systematically and specification-driven. Document comprehensively. Operate autonomously and adaptively. |  |
 | [Specification](../agents/specification.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fspecification.agent.md) | Generate or update specification documents for new or existing functionality. |  |
 | [Stackhawk Security Onboarding](../agents/stackhawk-security-onboarding.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fstackhawk-security-onboarding.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fstackhawk-security-onboarding.agent.md) | Automatically set up StackHawk security testing for your repository with generated configuration and GitHub Actions workflow | stackhawk-mcp<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=stackhawk-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22stackhawk-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=stackhawk-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22stackhawk-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22stackhawk-mcp%22%5D%2C%22env%22%3A%7B%7D%7D) |

@@ -103,6 +103,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [copilot-cli-quickstart](../skills/copilot-cli-quickstart/SKILL.md)<br />`gh skills install github/awesome-copilot copilot-cli-quickstart` | Use this skill when someone wants to learn GitHub Copilot CLI from scratch. Offers interactive step-by-step tutorials with separate Developer and Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or ask a question! Note: This skill targets GitHub Copilot CLI specifically and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation). | None |
 | [copilot-instructions-blueprint-generator](../skills/copilot-instructions-blueprint-generator/SKILL.md)<br />`gh skills install github/awesome-copilot copilot-instructions-blueprint-generator` | Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions. | None |
 | [copilot-sdk](../skills/copilot-sdk/SKILL.md)<br />`gh skills install github/awesome-copilot copilot-sdk` | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None |
+| [copilot-skill-authoring](../skills/copilot-skill-authoring/SKILL.md)<br />`gh skills install github/awesome-copilot copilot-skill-authoring` | Reference guide for authoring GitHub Copilot contributions in .agent.md and SKILL.md formats. Covers the frontmatter contract, format selection criteria, trigger-description patterns, dos and don'ts, and a mapping table from Claude/Codex concepts to Copilot equivalents. Use when creating new Copilot skills or agents, reviewing contributions for correctness, or migrating definitions from other AI platforms. | None |
 | [copilot-spaces](../skills/copilot-spaces/SKILL.md)<br />`gh skills install github/awesome-copilot copilot-spaces` | Use Copilot Spaces to provide project-specific context to conversations. Use this skill when users mention a "Copilot space", want to load context from a shared knowledge base, discover available spaces, or ask questions grounded in curated project documentation, code, and instructions. | None |
 | [copilot-usage-metrics](../skills/copilot-usage-metrics/SKILL.md)<br />`gh skills install github/awesome-copilot copilot-usage-metrics` | Retrieve and display GitHub Copilot usage metrics for organizations and enterprises using the GitHub CLI and REST API. | `get-enterprise-metrics.sh`<br />`get-enterprise-user-metrics.sh`<br />`get-org-metrics.sh`<br />`get-org-user-metrics.sh` |
 | [cosmosdb-datamodeling](../skills/cosmosdb-datamodeling/SKILL.md)<br />`gh skills install github/awesome-copilot cosmosdb-datamodeling` | Step-by-step guide for capturing key application requirements for NoSQL use-case and produce Azure Cosmos DB Data NoSQL Model design using best practices and common patterns, artifacts_produced: "cosmosdb_requirements.md" file and "cosmosdb_data_model.md" file | None |