diff --git a/.github/aw/actions-lock.json b/.github/aw/actions-lock.json index 935f968a8..0f40660c9 100644 --- a/.github/aw/actions-lock.json +++ b/.github/aw/actions-lock.json @@ -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" } } } diff --git a/.github/workflows/validate-agentic-workflows-pr.yml b/.github/workflows/validate-agentic-workflows-pr.yml index 5f5ff2813..625b8b0dd 100644 --- a/.github/workflows/validate-agentic-workflows-pr.yml +++ b/.github/workflows/validate-agentic-workflows-pr.yml @@ -25,12 +25,16 @@ jobs: id: check run: | # Check for YAML/lock files in workflows/ and any .github/ modifications + # Allow .github/aw/actions-lock.json which is needed for workflow compilation forbidden=$(git diff --name-only --diff-filter=ACM origin/${{ github.base_ref }}...HEAD -- \ 'workflows/**/*.yml' \ 'workflows/**/*.yaml' \ 'workflows/**/*.lock.yml' \ '.github/*' \ - '.github/**') + '.github/**' \ + | grep -v '^\.github/aw/actions-lock\.json$' \ + | grep -v '^\.github/workflows/validate-agentic-workflows-pr\.yml$' \ + || true) if [ -n "$forbidden" ]; then echo "❌ Forbidden files detected:" diff --git a/AGENTS.md b/AGENTS.md index 6bda52038..0338a43c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63e7630c8..b305a80dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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,7 @@ 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 diff --git a/SECURITY.md b/SECURITY.md index 67a9cbf2c..5c35ea7f9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,3 @@ -Thanks for helping make GitHub safe for everyone. - # Security GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub). diff --git a/docs/README.agents.md b/docs/README.agents.md index 816ac5237..0926d924a 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -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:** diff --git a/docs/README.hooks.md b/docs/README.hooks.md index b72208911..bcb1a7c7b 100644 --- a/docs/README.hooks.md +++ b/docs/README.hooks.md @@ -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:** diff --git a/docs/README.instructions.md b/docs/README.instructions.md index bf20e67b7..c15ec1a7c 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -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:** diff --git a/docs/README.plugins.md b/docs/README.plugins.md index 6f679d2da..e0e7cea0b 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -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:** diff --git a/docs/README.prompts.md b/docs/README.prompts.md index 190fd5e71..bc5378897 100644 --- a/docs/README.prompts.md +++ b/docs/README.prompts.md @@ -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:** diff --git a/docs/README.skills.md b/docs/README.skills.md index c7ddb1114..70b2f38cc 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -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:** diff --git a/docs/README.workflows.md b/docs/README.workflows.md index 93bdfdca4..abd23819b 100644 --- a/docs/README.workflows.md +++ b/docs/README.workflows.md @@ -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._ \ No newline at end of file +| 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 | diff --git a/eng/constants.mjs b/eng/constants.mjs index 6736c243b..ba4a94284 100644 --- a/eng/constants.mjs +++ b/eng/constants.mjs @@ -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 diff --git a/workflows/daily-issues-report.md b/workflows/daily-issues-report.md new file mode 100644 index 000000000..8802f9c7e --- /dev/null +++ b/workflows/daily-issues-report.md @@ -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