{"owner":"github","repo":"awesome-copilot","hasSkills":true,"hasMcp":true,"mcpConfig":{"mcpServers":{"awesome-copilot":{"command":"npx","args":["-y","@modelcontextprotocol/server-awesome-copilot"]}}},"found":["AGENTS.md","mcp.json",".github/copilot-instructions.md"],"files":{"AGENTS.md":"# AGENTS.md\n\n## Project Overview\n\nThe Awesome GitHub Copilot repository is a community-driven collection of custom agents and instructions designed to enhance GitHub Copilot experiences across various domains, languages, and use cases. The project includes:\n\n- **Agents** - Specialized GitHub Copilot agents that integrate with MCP servers\n- **Instructions** - Coding standards and best practices applied to specific file patterns\n- **Skills** - Self-contained folders with instructions and bundled resources for specialized tasks\n- **Hooks** - Automated workflows triggered by specific events during development\n- **Workflows** - [Agentic Workflows](https://github.github.com/gh-aw) for AI-powered repository automation in GitHub Actions\n- **Plugins** - Installable packages that group related agents, hooks, and skills around specific themes\n\n## Repository Structure\n\n```\n.\n├── agents/           # Custom GitHub Copilot agent definitions (.agent.md files)\n├── instructions/     # Coding standards and guidelines (.instructions.md files)\n├── skills/           # Agent Skills folders (each with SKILL.md and optional bundled assets)\n├── hooks/            # Automated workflow hooks (folders with README.md + hooks.json)\n├── workflows/        # Agentic Workflows (.md files for GitHub Actions automation)\n├── plugins/          # Installable plugin packages (folders with plugin.json)\n├── extensions/       # Reusable canvas extension sources (extension.mjs and assets)\n├── docs/             # Documentation for different resource types\n├── eng/              # Build and automation scripts\n└── scripts/          # Utility scripts\n```\n\n## Setup Commands\n\n```bash\n# Install dependencies\nnpm ci\n\n# Build the project (generates README.md and marketplace.json)\nnpm run build\n\n# Validate plugin manifests\nnpm run plugin:validate\n\n# Generate marketplace.json only\nnpm run plugin:generate-marketplace\n\n# Create a new plugin\nnpm run plugin:create -- --name <plugin-name>\n\n# Validate agent skills\nnpm run skill:validate\n\n# Create a new skill\nnpm run skill:create -- --name <skill-name>\n```\n\n## Development Workflow\n\n### Working with Agents, Instructions, Skills, and Hooks\n\nAll agent files (`*.agent.md`) and instruction files (`*.instructions.md`) must include proper markdown front matter. Agent Skills are folders containing a `SKILL.md` file with frontmatter and optional bundled assets. Hooks are folders containing a `README.md` with frontmatter and a `hooks.json` configuration file:\n\n#### Agent Files (\\*.agent.md)\n\n- Must have `description` field (wrapped in single quotes)\n- File names should be lower case with words separated by hyphens\n- Recommended to include `tools` field\n- Strongly recommended to specify `model` field\n\n#### Instruction Files (\\*.instructions.md)\n\n- Must have `description` field (wrapped in single quotes, not empty)\n- Must have `applyTo` field specifying file patterns (e.g., `'**.js, **.ts'`)\n- File names should be lower case with words separated by hyphens\n\n#### Agent Skills (skills/\\*/SKILL.md)\n\n- Each skill is a folder containing a `SKILL.md` file\n- SKILL.md must have `name` field (lowercase with hyphens, matching folder name, max 64 characters)\n- SKILL.md must have `description` field (wrapped in single quotes, 10-1024 characters)\n- Folder names should be lower case with words separated by hyphens\n- Skills can include bundled assets (scripts, templates, data files)\n- Bundled assets should be referenced in the SKILL.md instructions\n- Asset files should be reasonably sized (under 5MB per file)\n- Skills follow the [Agent Skills specification](https://agentskills.io/specification)\n\n#### Canvas Extensions (extensions/\\*)\n\n- Each extension folder must include `extension.mjs`\n- Extensions are reusable source components, not standalone plugins\n- A shippable extension plugin is registered by a matching `plugins/<extension-id>/plugin.json`\n- A plugin can bundle additional reusable extensions by listing `./extensions/<name>` paths in `extensions.com.github.awesome-copilot.extensions`\n- Each extension must have `assets/preview.png` as the primary visual asset\n- Extension metadata is sourced from the matching plugin manifest in `plugins/`\n\n#### Hook Folders (hooks/\\*/README.md)\n\n- Each hook is a folder containing a `README.md` file with frontmatter\n- README.md must have `name` field (human-readable name)\n- README.md must have `description` field (wrapped in single quotes, not empty)\n- Must include a `hooks.json` file with hook configuration (hook events extracted from this file)\n- Folder names should be lower case with words separated by hyphens\n- Can include bundled assets (scripts, utilities, configuration files)\n- Bundled scripts should be referenced in the README.md and hooks.json\n- Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)\n- Optionally includes `tags` field for categorization\n\n#### Workflow Files (workflows/\\*.md)\n\n- Each workflow is a standalone `.md` file in the `workflows/` directory\n- Must have `name` field (human-readable name)\n- Must have `description` field (wrapped in single quotes, not empty)\n- Contains agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions\n- File names should be lower case with words separated by hyphens\n- Only `.md` files are accepted — `.yml`, `.yaml`, and `.lock.yml` files are blocked by CI\n- Follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw/reference/workflow-structure/)\n\n#### Plugin Folders (plugins/\\*)\n\n- Each plugin is a folder containing a root `plugin.json` file with metadata\n- plugin.json **must** have `\"$schema\": \"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json\"` (Agent Plugins v1.0.0)\n- plugin.json must have `name` field (matching the folder name)\n- plugin.json must have `description` field (describing the plugin's purpose)\n- plugin.json must have `version` field (semantic version, e.g., \"1.0.0\")\n- Plugin content is defined declaratively in plugin.json under `extensions.com.github.awesome-copilot` using source-only composition fields (`agents`, `hooks`, `skills`, and `extensions`). Source files live in top-level directories and are materialized into plugins by CI. This namespace is stripped from the served manifest — skills use the standard `skills/` directory and Copilot-specific content uses `com.github.copilot/`.\n- The `marketplace.json` file is automatically generated from all plugins during build\n- Plugins are discoverable and installable via GitHub Copilot CLI\n\n### Adding New Resources\n\nWhen adding a new agent, instruction, skill, hook, workflow, or plugin:\n\n**For Agents and Instructions:**\n\n1. Create the file with proper front matter\n2. Add the file to the appropriate directory\n3. Update the README.md by running: `npm run build`\n4. Verify the resource appears in the generated README\n\n**For Hooks:**\n\n1. Create a new folder in `hooks/` with a descriptive name\n2. Create `README.md` with proper frontmatter (name, description, hooks, tags)\n3. Create `hooks.json` with hook configuration following GitHub Copilot hooks spec\n4. Add any bundled scripts or assets to the folder\n5. Make scripts executable: `chmod +x script.sh`\n6. Update the README.md by running: `npm run build`\n7. Verify the hook appears in the generated README\n\n**For Workflows:**\n\n1. Create a new `.md` file in `workflows/` with a descriptive name (e.g., `daily-issues-report.md`)\n2. Include frontmatter with `name` and `description`, plus agentic workflow fields (`on`, `permissions`, `safe-outputs`)\n3. Compile with `gh aw compile --validate` to verify it's valid\n4. Update the README.md by running: `npm run build`\n5. Verify the workflow appears in the generated README\n\n**For Skills:**\n\n1. Run `npm run skill:create` to scaffold a new skill folder\n2. Edit the generated SKILL.md file with your instructions\n3. Add any bundled assets (scripts, templates, data) to the skill folder\n4. Run `npm run skill:validate` to validate the skill structure\n5. Update the README.md by running: `npm run build`\n6. Verify the skill appears in the generated README\n\n**For Plugins:**\n\n1. Run `npm run plugin:create -- --name <plugin-name>` to scaffold a new plugin\n2. Define agents, hooks, skills, and reusable extensions under `extensions.com.github.awesome-copilot` in `plugin.json`\n3. Edit the generated `plugin.json` with your metadata\n4. Run `npm run plugin:validate` to validate the plugin structure\n5. Run `npm run build` to update README.md and marketplace.json\n6. Verify the plugin appears in `.github/plugin/marketplace.json`\n\n**For Canvas Extensions:**\n\n1. Create/update the extension in `extensions/<extension-id>/` with `extension.mjs`\n2. Add the matching plugin manifest under `plugins/<extension-id>/plugin.json`:\n   ```json\n   {\n     \"$schema\": \"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json\",\n     \"name\": \"<extension-id>\",\n     \"description\": \"...\",\n     \"version\": \"1.0.0\",\n     \"extensions\": {\n       \"com.github.copilot\": {\n         \"logo\": \"assets/preview.png\"\n       }\n     }\n   }\n   ```\n3. Ensure `assets/preview.png` exists as the primary visual asset\n4. Run `npm run plugin:validate` to validate plugin and extension metadata\n5. Run `npm run build` to regenerate website data and marketplace output\n\nTo bundle an extension into another plugin without making a second source copy, add sorted `./extensions/<name>` paths to `plugins/<plugin-id>/plugin.json` under `extensions.com.github.awesome-copilot.extensions`.\n\n**For External Plugins:**\n\n1. Do not open a direct PR that edits `plugins/external.json` for a public third-party plugin submission\n2. Public external plugin submissions use the external plugin issue workflow documented in [CONTRIBUTING.md](CONTRIBUTING.md#adding-external-plugins)\n3. In v1, only GitHub-hosted plugins are accepted for public submission, using a public repo plus an immutable `ref`, `sha`, or both\n4. The shared validator in `eng/external-plugin-validation.mjs` is the canonical source of truth for external plugin data rules; reuse it instead of duplicating checks in scripts or workflows\n5. Submission issues move through `external-plugin` + `awaiting-review` and then either `ready-for-review` or `requires-submitter-fixes` based on automated quality gates\n6. After issue edits, the issue author or a maintainer can comment `/rerun-intake` to re-run automated intake and quality gates without opening a new submission issue\n7. Maintainers can explicitly override a quality-gate blocker with `/mark-ready-for-review [optional reason]`, which moves the issue to `ready-for-review`\n8. Maintainers make the decision with `/approve` or `/reject <reason>` issue comments once the issue is in `ready-for-review`; approved issues are closed and used as the six-month re-review anchor\n9. Approval automation creates or updates the PR against `main`, updates `plugins/external.json`, and regenerates marketplace outputs\n10. Nightly re-review automation finds closed `external-plugin` + `approved` issues that are at least six months old, applies `re-review-due`, and opens or updates a tracking issue for maintainers\n11. Maintainers complete re-review on the original approved submission issue with `/re-review-keep`, `/re-review-needs-changes`, or `/re-review-remove`; keep resets the issue `closed_at`, and remove opens a PR against `main`\n\n### Testing Instructions\n\n```bash\n# Run all validation checks\nnpm run plugin:validate\nnpm run skill:validate\n\n# Build and verify README generation\nnpm run build\n\n# Fix line endings (required before committing)\nbash eng/fix-line-endings.sh\n```\n\nBefore committing:\n\n- Ensure all markdown front matter is correctly formatted\n- Verify file names follow the lower-case-with-hyphens convention\n- Run `npm run build` to update the README\n- **Always run `bash eng/fix-line-endings.sh`** to normalize line endings (CRLF → LF)\n- Check that your new resource appears correctly in the README\n\n## Code Style Guidelines\n\n### Markdown Files\n\n- Use proper front matter with required fields\n- Keep descriptions concise and informative\n- Wrap description field values in single quotes\n- Use lower-case file names with hyphens as separators\n\n### JavaScript/Node.js Scripts\n\n- Located in `eng/` and `scripts/` directories\n- Follow Node.js ES module conventions (`.mjs` extension)\n- Use clear, descriptive function and variable names\n\n## Pull Request Guidelines\n\nWhen creating a pull request:\n\n> **Important:** All pull requests should target the **`main`** branch, not `staged`.\n\n1. **README updates**: New files should automatically be added to the README when you run `npm run build`\n2. **Front matter validation**: Ensure all markdown files have the required front matter fields\n3. **File naming**: Verify all new files follow the lower-case-with-hyphens naming convention\n4. **Build check**: Run `npm run build` before committing to verify README generation\n5. **Line endings**: **Always run `bash eng/fix-line-endings.sh`** to normalize line endings to LF (Unix-style)\n6. **Description**: Provide a clear description of what your agent/instruction does\n7. **Testing**: If adding a plugin, run `npm run plugin:validate` to ensure validity\n\n### Pre-commit Checklist\n\nBefore submitting your PR, ensure you have:\n\n- [ ] Run `npm install` (or `npm ci`) to install dependencies\n- [ ] Run `npm run build` to generate the updated README.md\n- [ ] Run `bash eng/fix-line-endings.sh` to normalize line endings\n- [ ] Verified that all new files have proper front matter\n- [ ] Tested that your contribution works with GitHub Copilot\n- [ ] Checked that file names follow the naming convention\n\n### Code Review Checklist\n\nFor instruction files (\\*.instructions.md):\n\n- [ ] Has markdown front matter\n- [ ] Has non-empty `description` field wrapped in single quotes\n- [ ] Has `applyTo` field with file patterns\n- [ ] File name is lower case with hyphens\n\nFor agent files (\\*.agent.md):\n\n- [ ] Has markdown front matter\n- [ ] Has non-empty `description` field wrapped in single quotes\n- [ ] Has `name` field with human-readable name (e.g., \"Address Comments\" not \"address-comments\")\n- [ ] File name is lower case with hyphens\n- [ ] Includes `model` field (strongly recommended)\n- [ ] Considers using `tools` field\n\nFor skills (skills/\\*/):\n\n- [ ] Folder contains a SKILL.md file\n- [ ] SKILL.md has markdown front matter\n- [ ] Has `name` field matching folder name (lowercase with hyphens, max 64 characters)\n- [ ] Has non-empty `description` field wrapped in single quotes (10-1024 characters)\n- [ ] Folder name is lower case with hyphens\n- [ ] Any bundled assets are referenced in SKILL.md\n- [ ] Bundled assets are under 5MB per file\n\nFor hook folders (hooks/\\*/):\n\n- [ ] Folder contains a README.md file with markdown front matter\n- [ ] Has `name` field with human-readable name\n- [ ] Has non-empty `description` field wrapped in single quotes\n- [ ] Has `hooks.json` file with valid hook configuration (hook events extracted from this file)\n- [ ] Folder name is lower case with hyphens\n- [ ] Any bundled scripts are executable and referenced in README.md\n- [ ] Follows [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)\n- [ ] Optionally includes `tags` array field for categorization\n\nFor workflow files (workflows/\\*.md):\n\n- [ ] File has markdown front matter\n- [ ] Has `name` field with human-readable name\n- [ ] Has non-empty `description` field wrapped in single quotes\n- [ ] File name is lower case with hyphens\n- [ ] Contains `on` and `permissions` in frontmatter\n- [ ] Workflow uses least-privilege permissions and safe outputs\n- [ ] No `.yml`, `.yaml`, or `.lock.yml` files included\n- [ ] Follows [GitHub Agentic Workflows specification](https://github.github.com/gh-aw/reference/workflow-structure/)\n\nFor plugins (plugins/\\*/):\n\n- [ ] Directory contains a root `plugin.json` file\n- [ ] Directory contains a `README.md` file\n- [ ] `plugin.json` has `\"$schema\": \"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json\"`\n- [ ] `plugin.json` has `name` field matching the directory name (lowercase with hyphens)\n- [ ] `plugin.json` has non-empty `description` field\n- [ ] `plugin.json` has `version` field (semantic version, e.g., \"1.0.0\")\n- [ ] Directory name is lower case with hyphens\n- [ ] If `keywords` is present, it is an array of lowercase hyphenated strings\n- [ ] If composition arrays are present under `extensions.com.github.awesome-copilot`, each entry is a valid relative path\n- [ ] The plugin does not reference non-existent files\n- [ ] Run `npm run plugin:validate` and `npm run build` to verify the plugin passes all checks\n\n## Contributing\n\nThis is a community-driven project. Contributions are welcome! Please see:\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines\n- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards\n- [SECURITY.md](SECURITY.md) for security policies\n\n## MCP Server\n\nThe repository includes an MCP (Model Context Protocol) Server for searching and installing resources directly from this repository. Docker is required to run the server.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n","mcp.json":"{\n  \"mcpServers\": {\n    \"github-agentic-workflows\": {\n      \"type\": \"local\",\n      \"command\": \"gh\",\n      \"args\": [\n        \"aw\",\n        \"mcp-server\"\n      ],\n      \"tools\": [\n        \"compile\",\n        \"audit\",\n        \"logs\",\n        \"inspect\",\n        \"status\",\n        \"audit-diff\"\n      ]\n    }\n  }\n}",".github/copilot-instructions.md":"The following instructions are only to be applied when performing a code review.\n\n## README updates\n\n- [ ] The new file should be added to the `docs/README.<type>.md`.\n\n## Prompt file guide\n\n**Only apply to files that end in `.prompt.md`**\n\n- [ ] The prompt has markdown front matter.\n- [ ] The prompt has a `agent` field specified of either `agent`, `ask`, or `Plan`.\n- [ ] The prompt has a `description` field.\n- [ ] The `description` field is not empty.\n- [ ] The file name is lower case, with words separated by hyphens.\n- [ ] Encourage the use of `tools`, but it's not required.\n- [ ] Strongly encourage the use of `model` to specify the model that the prompt is optimised for.\n- [ ] Strongly encourage the use of `name` to set the name for the prompt.\n\n## Instruction file guide\n\n**Only apply to files that end in `.instructions.md`**\n\n- [ ] The instruction has markdown front matter.\n- [ ] The instruction has a `description` field.\n- [ ] The `description` field is not empty.\n- [ ] The file name is lower case, with words separated by hyphens.\n- [ ] The instruction has an `applyTo` field that specifies the file or files to which the instructions apply. If they wish to specify multiple file paths they should formatted like `'**.js, **.ts'`.\n\n## Agent file guide\n\n**Only apply to files that end in `.agent.md`**\n\n- [ ] The agent has markdown front matter.\n- [ ] The agent has a `description` field.\n- [ ] The `description` field is not empty.\n- [ ] The file name is lower case, with words separated by hyphens.\n- [ ] Encourage the use of `tools`, but it's not required.\n- [ ] Strongly encourage the use of `model` to specify the model that the agent is optimised for.\n- [ ] Strongly encourage the use of `name` to set the name for the agent.\n\n## Agent Skills guide\n\n**Only apply to folders in the `skills/` directory**\n\n- [ ] The skill folder contains a `SKILL.md` file.\n- [ ] The SKILL.md has markdown front matter.\n- [ ] The SKILL.md has a `name` field.\n- [ ] The `name` field value is lowercase with words separated by hyphens.\n- [ ] The `name` field matches the folder name.\n- [ ] The SKILL.md has a `description` field.\n- [ ] The `description` field is not empty, at least 10 characters, and maximum 1024 characters.\n- [ ] The `description` field value is wrapped in single quotes.\n- [ ] The folder name is lower case, with words separated by hyphens.\n- [ ] Any bundled assets (scripts, templates, data files) are referenced in the SKILL.md instructions.\n- [ ] Bundled assets are reasonably sized (under 5MB per file).\n\n## Plugin guide\n\n**Only apply to directories in the `plugins/` directory**\n\n- [ ] The plugin directory contains a root `plugin.json` file.\n- [ ] The plugin directory contains a `README.md` file.\n- [ ] The plugin.json has a `name` field matching the directory name.\n- [ ] The plugin.json has a `description` field.\n- [ ] The `description` field is not empty.\n- [ ] The directory name is lower case, with words separated by hyphens.\n- [ ] If `tags` is present, it is an array of lowercase hyphenated strings.\n- [ ] If `items` is present, each item has `path` and `kind` fields.\n- [ ] The `kind` field value is one of: `prompt`, `agent`, `instruction`, `skill`, or `hook`.\n- [ ] The plugin does not reference non-existent files.\n"}}