Merge pull request #805 from brunoborges/fix-aw-readme

docs: improve CONTRIBUTING.md and add "How to Contribute" links across docs

.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"
     }
   }
 }

.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:"

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

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
 

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).

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:**

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:**

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:**

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:**

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:**

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:**

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._
+| 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 |

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

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