Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-03-24 10:05:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: update documentation and add contribution guidelines for agents, hooks, instructions, plugins, skills, and workflows; enhance actions-lock.json with additional actions

Browse Source
This commit is contained in:
Bruno Borges
2026-02-24 12:47:16 -05:00
parent fa538a037a
commit 6103b17ba2
12 changed files with 180 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.github/aw/actions-lock.json vendored
View File

@@ -1,14 +1,34 @@
{
"entries": {
"actions/checkout@v6.0.2": {
"repo": "actions/checkout",
"version": "v6.0.2",
"sha": "de0fac2e4500dabe0009e67214ff5f5447ce83dd"
},
"actions/download-artifact@v6": {
"repo": "actions/download-artifact",
"version": "v6",
"sha": "018cc2cf5baa6db3ef3c5f8a56943fffe632ef53"
},
"actions/github-script@v8": {
"repo": "actions/github-script",
"version": "v8",
"sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd"
},
"actions/upload-artifact@v6": {
"repo": "actions/upload-artifact",
"version": "v6",
"sha": "b7c566a772e6b6bfb58ed0dc250532a479d7789f"
},
"github/gh-aw/actions/setup@v0.45.7": {
"repo": "github/gh-aw/actions/setup",
"version": "v0.45.7",
"sha": "5d8900eb6f6230c9d41a3c30af320150a2361285"
},
"github/gh-aw/actions/setup@v0.46.1": {
"repo": "github/gh-aw/actions/setup",
"version": "v0.46.1",
"sha": "874bdd8271bf8c21902b068fb1ca6a22d2dc4b7a"
}
}
}

10
AGENTS.md
View File

@@ -102,12 +102,10 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi
- Each workflow is a standalone `.md` file in the `workflows/` directory
- Must have `name` field (human-readable name)
- Must have `description` field (wrapped in single quotes, not empty)
- Should have `triggers` field (array of trigger types, e.g., `['schedule', 'issues']`)
- Contains agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions
- File names should be lower case with words separated by hyphens
- Only `.md` files are accepted — `.yml`, `.yaml`, and `.lock.yml` files are blocked by CI
- Optionally includes `tags` field for categorization
- Follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw)
- Follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw/reference/workflow-structure/)
#### Plugin Folders (plugins/*)
- Each plugin is a folder containing a `.github/plugin/plugin.json` file with metadata
@@ -140,7 +138,7 @@ When adding a new agent, prompt, instruction, skill, hook, workflow, or plugin:
**For Workflows:**
1. Create a new `.md` file in `workflows/` with a descriptive name (e.g., `daily-issues-report.md`)
2. Include frontmatter with `name`, `description`, `triggers`, plus agentic workflow fields (`on`, `permissions`, `safe-outputs`)
2. Include frontmatter with `name` and `description`, plus agentic workflow fields (`on`, `permissions`, `safe-outputs`)
3. Compile with `gh aw compile --validate` to verify it's valid
4. Update the README.md by running: `npm run build`
5. Verify the workflow appears in the generated README
@@ -266,13 +264,11 @@ For workflow files (workflows/*.md):
- [ ] File has markdown front matter
- [ ] Has `name` field with human-readable name
- [ ] Has non-empty `description` field wrapped in single quotes
- [ ] Has `triggers` array field listing workflow trigger types
- [ ] File name is lower case with hyphens
- [ ] Contains `on` and `permissions` in frontmatter
- [ ] Workflow uses least-privilege permissions and safe outputs
- [ ] No `.yml`, `.yaml`, or `.lock.yml` files included
- [ ] Follows [GitHub Agentic Workflows specification](https://github.github.com/gh-aw)
- [ ] Optionally includes `tags` array field for categorization
- [ ] Follows [GitHub Agentic Workflows specification](https://github.github.com/gh-aw/reference/workflow-structure/)
For plugins (plugins/*/):
- [ ] Directory contains a `.github/plugin/plugin.json` file

79
CONTRIBUTING.md
View File

@@ -2,6 +2,25 @@
Thank you for your interest in contributing to the Awesome GitHub Copilot repository! We welcome contributions from the community to help expand our collection of custom instructions and prompts.
## Table of Contents
- [How to Contribute](#how-to-contribute)
- [Adding Instructions](#adding-instructions)
- [Adding Prompts](#adding-prompts)
- [Adding Agents](#adding-agents)
- [Adding Skills](#adding-skills)
- [Adding Plugins](#adding-plugins)
- [Adding Hooks](#adding-hooks)
- [Adding Agentic Workflows](#adding-agentic-workflows)
- [Submitting Your Contribution](#submitting-your-contribution)
- [What We Accept](#what-we-accept)
- [What We Don't Accept](#what-we-dont-accept)
- [Quality Guidelines](#quality-guidelines)
- [Contributor Recognition](#contributor-recognition)
- [Contribution Types](#contribution-types)
- [Code of Conduct](#code-of-conduct)
- [License](#license)
## How to Contribute
### Adding Instructions
@@ -61,7 +80,7 @@ Your goal is to...
- Include examples where helpful
```
### Adding an Agent
### Adding Agents
Agents are specialized configurations that transform GitHub Copilot Chat into domain-specific assistants or personas for particular development scenarios.
@@ -161,14 +180,55 @@ plugins/my-plugin-id/
- **Clear purpose**: The plugin should solve a specific problem or workflow
- **Validate before submitting**: Run `npm run plugin:validate` to ensure your plugin is valid
### Adding Hooks
Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions, such as session start, session end, user prompts, and tool usage.
1. **Create a new hook folder**: Add a new folder in the `hooks/` directory with a descriptive, lowercase name using hyphens (e.g., `session-logger`)
2. **Create `README.md`**: Add a `README.md` file with frontmatter including `name`, `description`, and optionally `tags`
3. **Create `hooks.json`**: Add a `hooks.json` file with hook configuration following the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
4. **Add bundled scripts**: Include any scripts or assets the hook needs, and make them executable (`chmod +x script.sh`)
5. **Update the README**: Run `npm run build` to update the generated README tables
#### Example hook structure
```
hooks/my-hook/
├── README.md # Hook documentation with frontmatter
├── hooks.json # Hook event configuration
└── my-script.sh # Bundled script(s)
```
#### Example README.md frontmatter
```markdown
---
name: 'My Hook Name'
description: 'Brief description of what this hook does'
tags: ['logging', 'automation']
---
# My Hook Name
Detailed documentation about the hook...
```
#### Hook Guidelines
- **Event configuration**: Define hook events in `hooks.json` — supported events include session start, session end, user prompts, and tool usage
- **Executable scripts**: Ensure all bundled scripts are executable and referenced in both `README.md` and `hooks.json`
- **Privacy aware**: Be mindful of what data your hook collects or logs
- **Clear documentation**: Explain installation steps, configuration options, and what the hook does
- Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
### Adding Agentic Workflows
[Agentic Workflows](https://github.github.com/gh-aw) are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable scheduled and event-triggered automation with built-in guardrails.
1. **Create your workflow file**: Add a new `.md` file in the `workflows/` directory (e.g., `daily-issues-report.md`)
2. **Include frontmatter**: Add `name`, `description`, `triggers`, and optionally `tags` at the top, followed by agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions
3. **Test locally**: Compile with `gh aw compile --validate` to verify it's valid
4. **Update the README**: Run `npm run build` to update the generated README tables
1. **Create your workflow file** with a new `.md` file in the `workflows/` directory (e.g., [`daily-issues-report.md`](./workflows/daily-issues-report.md))
2. **Include frontmatter** with `name` and `description`, followed by agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions
3. **Test locally** with `gh aw compile --validate --no-emit daily-issues-report.md` to verify it's valid
4. **Update the README** with `npm run build` to update the generated README tables
> **Note:** Only `.md` files are accepted — do not include compiled `.lock.yml` or `.yml` files. CI will block them.
@@ -176,10 +236,8 @@ plugins/my-plugin-id/
```markdown
---
name: 'Daily Issues Report'
description: 'Generates a daily summary of open issues and recent activity as a GitHub issue'
triggers: ['schedule']
tags: ['reporting', 'issues', 'automation']
name: "Daily Issues Report"
description: "Generates a daily summary of open issues and recent activity as a GitHub issue"
on:
schedule: daily on weekdays
permissions:
@@ -294,7 +352,8 @@ In addition, all standard contribution types supported by [All Contributors](htt
## Code of Conduct
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
Please note that this project is maintained with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md).
By participating in this project you agree to abide by its terms.
## License

4
docs/README.agents.md
View File

@@ -1,6 +1,10 @@
# 🤖 Custom Agents
Custom agents for GitHub Copilot, making it easy for users and organizations to "specialize" their Copilot coding agent (CCA) through simple file-based configuration.
### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to contribute new agents, improve existing ones, and share your use cases.
### How to Use Custom Agents
**To Install:**

4
docs/README.hooks.md
View File

@@ -1,6 +1,10 @@
# 🪝 Hooks
Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions, such as session start, session end, user prompts, and tool usage.
### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-hooks) for guidelines on how to contribute new hooks, improve existing ones, and share your use cases.
### How to Use Hooks
**What's Included:**

4
docs/README.instructions.md
View File

@@ -1,6 +1,10 @@
# 📋 Custom Instructions
Team and project-specific instructions to enhance GitHub Copilot's behavior for specific technologies and coding practices.
### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on how to contribute new instructions, improve existing ones, and share your use cases.
### How to Use Custom Instructions
**To Install:**

4
docs/README.plugins.md
View File

@@ -1,6 +1,10 @@
# 🔌 Plugins
Curated plugins of related prompts, agents, and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI.
### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how to contribute new plugins, improve existing ones, and share your use cases.
### How to Use Plugins
**Browse Plugins:**

4
docs/README.prompts.md
View File

@@ -1,6 +1,10 @@
# 🎯 Reusable Prompts
Ready-to-use prompt templates for specific development scenarios and tasks, defining prompt text with a specific mode, model, and available set of tools.
### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-prompts) for guidelines on how to contribute new prompts, improve existing ones, and share your use cases.
### How to Use Reusable Prompts
**To Install:**

4
docs/README.skills.md
View File

@@ -3,6 +3,10 @@
Agent Skills are self-contained folders with instructions and bundled resources that enhance AI capabilities for specialized tasks. Based on the [Agent Skills specification](https://agentskills.io/specification), each skill contains a `SKILL.md` file with detailed instructions that agents load on-demand.
Skills differ from other primitives by supporting bundled assets (scripts, code samples, reference data) that agents can utilize when performing specialized tasks.
### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to contribute new agent skills, improve existing ones, and share your use cases.
### How to Use Agent Skills
**What's Included:**

7
docs/README.workflows.md
View File

@@ -1,6 +1,9 @@
# ⚡ Agentic Workflows
[Agentic Workflows](https://github.github.com/gh-aw) are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable event-triggered and scheduled automation with built-in guardrails and security-first design.
### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agentic-workflows) for guidelines on how to contribute new workflows, improve existing ones, and share your use cases.
### How to Use Agentic Workflows
@@ -28,4 +31,6 @@
- Respond to slash commands in issues and PRs
- Orchestrate multi-step repository automation
_No entries found yet._
| Name | Description | Triggers |
| ---- | ----------- | -------- |
| [Daily Issues Report](../workflows/daily-issues-report.md) | Generates a daily summary of open issues and recent activity as a GitHub issue | N/A |

42
eng/constants.mjs
View File

@@ -10,7 +10,11 @@ const TEMPLATES = {
Team and project-specific instructions to enhance GitHub Copilot's behavior for specific technologies and coding practices.`,
instructionsUsage: `### How to Use Custom Instructions
instructionsUsage: `### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on how to contribute new instructions, improve existing ones, and share your use cases.
### How to Use Custom Instructions
**To Install:**
- Click the **VS Code** or **VS Code Insiders** install button for the instruction you want to use
@@ -25,7 +29,11 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
Ready-to-use prompt templates for specific development scenarios and tasks, defining prompt text with a specific mode, model, and available set of tools.`,
promptsUsage: `### How to Use Reusable Prompts
promptsUsage: `### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-prompts) for guidelines on how to contribute new prompts, improve existing ones, and share your use cases.
### How to Use Reusable Prompts
**To Install:**
- Click the **VS Code** or **VS Code Insiders** install button for the prompt you want to use
@@ -40,7 +48,11 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
Curated plugins of related prompts, agents, and skills organized around specific themes, workflows, or use cases. Plugins can be installed directly via GitHub Copilot CLI.`,
pluginsUsage: `### How to Use Plugins
pluginsUsage: `### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how to contribute new plugins, improve existing ones, and share your use cases.
### How to Use Plugins
**Browse Plugins:**
- ⭐ Featured plugins are highlighted and appear at the top of the list
@@ -61,7 +73,11 @@ Discover our curated plugins of prompts, agents, and skills organized around spe
Custom agents for GitHub Copilot, making it easy for users and organizations to "specialize" their Copilot coding agent (CCA) through simple file-based configuration.`,
agentsUsage: `### How to Use Custom Agents
agentsUsage: `### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to contribute new agents, improve existing ones, and share your use cases.
### How to Use Custom Agents
**To Install:**
- Click the **VS Code** or **VS Code Insiders** install button for the agent you want to use
@@ -83,7 +99,11 @@ Agent Skills are self-contained folders with instructions and bundled resources
Skills differ from other primitives by supporting bundled assets (scripts, code samples, reference data) that agents can utilize when performing specialized tasks.`,
skillsUsage: `### How to Use Agent Skills
skillsUsage: `### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to contribute new agent skills, improve existing ones, and share your use cases.
### How to Use Agent Skills
**What's Included:**
- Each skill is a folder containing a \`SKILL.md\` instruction file
@@ -104,7 +124,11 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions, such as session start, session end, user prompts, and tool usage.`,
hooksUsage: `### How to Use Hooks
hooksUsage: `### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-hooks) for guidelines on how to contribute new hooks, improve existing ones, and share your use cases.
### How to Use Hooks
**What's Included:**
- Each hook is a folder containing a \`README.md\` file and a \`hooks.json\` configuration
@@ -132,7 +156,11 @@ Hooks enable automated workflows triggered by specific events during GitHub Copi
[Agentic Workflows](https://github.github.com/gh-aw) are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable event-triggered and scheduled automation with built-in guardrails and security-first design.`,
workflowsUsage: `### How to Use Agentic Workflows
workflowsUsage: `### How to Contribute
See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agentic-workflows) for guidelines on how to contribute new workflows, improve existing ones, and share your use cases.
### How to Use Agentic Workflows
**What's Included:**
- Each workflow is a single \`.md\` file with YAML frontmatter and natural language instructions

23
workflows/daily-issues-report.md Normal file
View File

@@ -0,0 +1,23 @@
---
name: "Daily Issues Report"
description: "Generates a daily summary of open issues and recent activity as a GitHub issue"
on:
schedule: daily on weekdays
permissions:
contents: read
issues: read
safe-outputs:
create-issue:
title-prefix: "[daily-report] "
labels: [report]
---
## Daily Issues Report
Create a daily summary of open issues for the team.
## What to Include
- New issues opened in the last 24 hours
- Issues closed or resolved
- Stale issues that need attention