Merge pull request #685 from github/hooks

Hooks

Author: aaronpowell

AGENTS.md

@@ -8,6 +8,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom
 - **Prompts** - Task-specific prompts for code generation and problem-solving
 - **Instructions** - Coding standards and best practices applied to specific file patterns
 - **Skills** - Self-contained folders with instructions and bundled resources for specialized tasks
+- **Hooks** - Automated workflows triggered by specific events during development
 - **Collections** - Curated collections organized around specific themes and workflows
 
 ## Repository Structure
@@ -18,6 +19,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom
 ├── prompts/          # Task-specific prompts (.prompt.md files)
 ├── instructions/     # Coding standards and guidelines (.instructions.md files)
 ├── skills/           # Agent Skills folders (each with SKILL.md and optional bundled assets)
+├── hooks/            # Automated workflow hooks (folders with README.md + hooks.json)
 ├── collections/      # Curated collections of resources (.md files)
 ├── docs/             # Documentation for different resource types
 ├── eng/              # Build and automation scripts
@@ -48,9 +50,9 @@ npm run skill:create -- --name <skill-name>
 
 ## Development Workflow
 
-### Working with Agents, Prompts, Instructions, and Skills
+### Working with Agents, Prompts, Instructions, Skills, and Hooks
 
-All agent files (`*.agent.md`), prompt files (`*.prompt.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:
+All agent files (`*.agent.md`), prompt files (`*.prompt.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:
 
 #### Agent Files (*.agent.md)
 - Must have `description` field (wrapped in single quotes)
@@ -80,16 +82,37 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi
 - Asset files should be reasonably sized (under 5MB per file)
 - Skills follow the [Agent Skills specification](https://agentskills.io/specification)
 
+#### Hook Folders (hooks/*/README.md)
+- Each hook is a folder containing a `README.md` file with frontmatter
+- README.md must have `name` field (human-readable name)
+- README.md must have `description` field (wrapped in single quotes, not empty)
+- Must include a `hooks.json` file with hook configuration (hook events extracted from this file)
+- Folder names should be lower case with words separated by hyphens
+- Can include bundled assets (scripts, utilities, configuration files)
+- Bundled scripts should be referenced in the README.md and hooks.json
+- Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
+- Optionally includes `tags` field for categorization
+
 ### Adding New Resources
 
-When adding a new agent, prompt, instruction, or skill:
+When adding a new agent, prompt, instruction, skill, or hook:
 
 **For Agents, Prompts, and Instructions:**
 1. Create the file with proper front matter
 2. Add the file to the appropriate directory
 3. Update the README.md by running: `npm run build`
 4. Verify the resource appears in the generated README
 
+**For Hooks:**
+1. Create a new folder in `hooks/` with a descriptive name
+2. Create `README.md` with proper frontmatter (name, description, hooks, tags)
+3. Create `hooks.json` with hook configuration following GitHub Copilot hooks spec
+4. Add any bundled scripts or assets to the folder
+5. Make scripts executable: `chmod +x script.sh`
+6. Update the README.md by running: `npm run build`
+7. Verify the hook appears in the generated README
+
+
 **For Skills:**
 1. Run `npm run skill:create` to scaffold a new skill folder
 2. Edit the generated SKILL.md file with your instructions
@@ -186,6 +209,16 @@ For skills (skills/*/):
 - [ ] Any bundled assets are referenced in SKILL.md
 - [ ] Bundled assets are under 5MB per file
 
+For hook folders (hooks/*/):
+- [ ] Folder contains a README.md file with markdown front matter
+- [ ] Has `name` field with human-readable name
+- [ ] Has non-empty `description` field wrapped in single quotes
+- [ ] Has `hooks.json` file with valid hook configuration (hook events extracted from this file)
+- [ ] Folder name is lower case with hyphens
+- [ ] Any bundled scripts are executable and referenced in README.md
+- [ ] Follows [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
+- [ ] Optionally includes `tags` array field for categorization
+
 ## Contributing
 
 This is a community-driven project. Contributions are welcome! Please see:

README.md

@@ -11,6 +11,7 @@ This repository provides a comprehensive toolkit for enhancing GitHub Copilot wi
 - **👉 [Awesome Agents](docs/README.agents.md)** - Specialized GitHub Copilot agents that integrate with MCP servers to provide enhanced capabilities for specific workflows and tools
 - **👉 [Awesome Prompts](docs/README.prompts.md)** - Focused, task-specific prompts for generating code, documentation, and solving specific problems
 - **👉 [Awesome Instructions](docs/README.instructions.md)** - Comprehensive coding standards and best practices that apply to specific file patterns or entire projects
+- **👉 [Awesome Hooks](docs/README.hooks.md)** - Automated workflows triggered by specific events during development, testing, and deployment
 - **👉 [Awesome Skills](docs/README.skills.md)** - Self-contained folders with instructions and bundled resources that enhance AI capabilities for specialized tasks
 - **👉 [Awesome Collections](docs/README.collections.md)** - Curated collections of related prompts, instructions, agents, and skills organized around specific themes and workflows
 - **👉 [Awesome Cookbook Recipes](cookbook/README.md)** - Practical, copy-paste-ready code snippets and real-world examples for working with GitHub Copilot tools and features
@@ -96,6 +97,10 @@ Use the `/` command in GitHub Copilot Chat to access prompts:
 
 Instructions automatically apply to files based on their patterns and provide contextual guidance for coding standards, frameworks, and best practices.
 
+### 🪝 Hooks
+
+Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions (like sessionStart, sessionEnd, userPromptSubmitted). They can automate tasks like logging, auto-committing changes, or integrating with external services.
+
 ## 🎯 Why Use Awesome GitHub Copilot?
 
 - **Productivity**: Pre-built agents, prompts and instructions save time and provide consistent results.
@@ -107,7 +112,7 @@ Instructions automatically apply to files based on their patterns and provide co
 
 We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to:
 
-- Add new prompts, instructions, agents, or skills
+- Add new prompts, instructions, hooks, agents, or skills
 - Improve existing content
 - Report issues or suggest enhancements
 
@@ -148,7 +153,7 @@ The customizations in this repository are sourced from and created by third-part
 
 ---
 
-**Ready to supercharge your coding experience?** Start exploring our [prompts](docs/README.prompts.md), [instructions](docs/README.instructions.md), and [custom agents](docs/README.agents.md)!
+**Ready to supercharge your coding experience?** Start exploring our [prompts](docs/README.prompts.md), [instructions](docs/README.instructions.md), [hooks](docs/README.hooks.md), and [custom agents](docs/README.agents.md)!
 
 ## Contributors ✨
 

docs/README.hooks.md

@@ -0,0 +1,31 @@
+# 🪝 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 Use Hooks
+
+**What's Included:**
+- Each hook is a folder containing a `README.md` file and a `hooks.json` configuration
+- Hooks may include helper scripts, utilities, or other bundled assets
+- Hooks follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
+
+**To Install:**
+- Copy the hook folder to your repository's `.github/hooks/` directory
+- Ensure any bundled scripts are executable (`chmod +x script.sh`)
+- Commit the hook to your repository's default branch
+
+**To Activate/Use:**
+- Hooks automatically execute during Copilot coding agent sessions
+- Configure hook events in the `hooks.json` file
+- Available events: `sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`, `postToolUse`, `errorOccurred`
+
+**When to Use:**
+- Automate session logging and audit trails
+- Auto-commit changes at session end
+- Track usage analytics
+- Integrate with external tools and services
+- Custom session workflows
+
+| Name | Description | Events | Bundled Assets |
+| ---- | ----------- | ------ | -------------- |
+| [Session Auto-Commit](../hooks/session-auto-commit/README.md) | Automatically commits and pushes changes when a Copilot coding agent session ends | sessionEnd | `auto-commit.sh`<br />`hooks.json` |
+| [Session Logger](../hooks/session-logger/README.md) | Logs all Copilot coding agent session activity for audit and analysis | sessionStart, sessionEnd, userPromptSubmitted | `hooks.json`<br />`log-prompt.sh`<br />`log-session-end.sh`<br />`log-session-start.sh` |

eng/collection-to-plugin.mjs

@@ -4,7 +4,11 @@ import fs from "fs";
 import path from "path";
 import readline from "readline";
 import { COLLECTIONS_DIR, ROOT_FOLDER } from "./constants.mjs";
-import { parseCollectionYaml, parseFrontmatter } from "./yaml-parser.mjs";
+import {
+  parseCollectionYaml,
+  parseFrontmatter,
+  parseHookMetadata,
+} from "./yaml-parser.mjs";
 
 const PLUGINS_DIR = path.join(ROOT_FOLDER, "plugins");
 
@@ -158,6 +162,12 @@ function getDisplayName(filePath, kind) {
     return basename.replace(".agent.md", "");
   } else if (kind === "instruction") {
     return basename.replace(".instructions.md", "");
+  } else if (kind === "hook") {
+    // For folder-based hooks like hooks/<hook>/README.md, use the folder name.
+    if (basename.toLowerCase() === "readme.md") {
+      return path.basename(path.dirname(filePath));
+    }
+    return basename.replace(".hook.md", "");
   } else if (kind === "skill") {
     return path.basename(filePath);
   }
@@ -221,6 +231,27 @@ function generateReadme(collection, items) {
     lines.push("");
   }
 
+  // Hooks
+  const hooks = items.filter((item) => item.kind === "hook");
+  if (hooks.length > 0) {
+    lines.push("### Hooks");
+    lines.push("");
+    lines.push("| Hook | Description | Event |");
+    lines.push("|------|-------------|-------|");
+    for (const item of hooks) {
+      const name = getDisplayName(item.path, "hook");
+      const description =
+        item.frontmatter?.description || item.frontmatter?.name || name;
+      // Extract events from hooks.json rather than frontmatter
+      const hookFolderPath = path.join(ROOT_FOLDER, path.dirname(item.path));
+      const hookMeta = parseHookMetadata(hookFolderPath);
+      const event =
+        hookMeta?.hooks?.length > 0 ? hookMeta.hooks.join(", ") : "N/A";
+      lines.push(`| \`${name}\` | ${description} | ${event} |`);
+    }
+    lines.push("");
+  }
+
   // Skills
   const skills = items.filter((item) => item.kind === "skill");
   if (skills.length > 0) {

eng/constants.mjs

@@ -1,6 +1,5 @@
-import path from "path";
+import path, { dirname } from "path";
 import { fileURLToPath } from "url";
-import { dirname } from "path";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -100,6 +99,34 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
 - Browse the skills table below to find relevant capabilities
 - Copy the skill folder to your local skills directory
 - Reference skills in your prompts or let the agent discover them automatically`,
+
+  hooksSection: `## 🪝 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.`,
+
+  hooksUsage: `### How to Use Hooks
+
+**What's Included:**
+- Each hook is a folder containing a \`README.md\` file and a \`hooks.json\` configuration
+- Hooks may include helper scripts, utilities, or other bundled assets
+- Hooks follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
+
+**To Install:**
+- Copy the hook folder to your repository's \`.github/hooks/\` directory
+- Ensure any bundled scripts are executable (\`chmod +x script.sh\`)
+- Commit the hook to your repository's default branch
+
+**To Activate/Use:**
+- Hooks automatically execute during Copilot coding agent sessions
+- Configure hook events in the \`hooks.json\` file
+- Available events: \`sessionStart\`, \`sessionEnd\`, \`userPromptSubmitted\`, \`preToolUse\`, \`postToolUse\`, \`errorOccurred\`
+
+**When to Use:**
+- Automate session logging and audit trails
+- Auto-commit changes at session end
+- Track usage analytics
+- Integrate with external tools and services
+- Custom session workflows`,
 };
 
 const vscodeInstallImage =
@@ -115,13 +142,15 @@ const AKA_INSTALL_URLS = {
   instructions: "https://aka.ms/awesome-copilot/install/instructions",
   prompt: "https://aka.ms/awesome-copilot/install/prompt",
   agent: "https://aka.ms/awesome-copilot/install/agent",
+  hook: "https://aka.ms/awesome-copilot/install/hook",
 };
 
 const ROOT_FOLDER = path.join(__dirname, "..");
 const INSTRUCTIONS_DIR = path.join(ROOT_FOLDER, "instructions");
 const PROMPTS_DIR = path.join(ROOT_FOLDER, "prompts");
 const AGENTS_DIR = path.join(ROOT_FOLDER, "agents");
 const SKILLS_DIR = path.join(ROOT_FOLDER, "skills");
+const HOOKS_DIR = path.join(ROOT_FOLDER, "hooks");
 const COLLECTIONS_DIR = path.join(ROOT_FOLDER, "collections");
 const COOKBOOK_DIR = path.join(ROOT_FOLDER, "cookbook");
 const MAX_COLLECTION_ITEMS = 50;
@@ -135,23 +164,24 @@ const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
 const DOCS_DIR = path.join(ROOT_FOLDER, "docs");
 
 export {
-  TEMPLATES,
-  vscodeInstallImage,
-  vscodeInsidersInstallImage,
-  repoBaseUrl,
-  AKA_INSTALL_URLS,
-  ROOT_FOLDER,
-  INSTRUCTIONS_DIR,
-  PROMPTS_DIR,
   AGENTS_DIR,
-  SKILLS_DIR,
+  AKA_INSTALL_URLS,
   COLLECTIONS_DIR,
   COOKBOOK_DIR,
+  DOCS_DIR,
+  HOOKS_DIR,
+  INSTRUCTIONS_DIR,
   MAX_COLLECTION_ITEMS,
-  SKILL_NAME_MIN_LENGTH,
-  SKILL_NAME_MAX_LENGTH,
-  SKILL_DESCRIPTION_MIN_LENGTH,
+  PROMPTS_DIR,
+  repoBaseUrl,
+  ROOT_FOLDER,
   SKILL_DESCRIPTION_MAX_LENGTH,
-  DOCS_DIR,
+  SKILL_DESCRIPTION_MIN_LENGTH,
+  SKILL_NAME_MAX_LENGTH,
+  SKILL_NAME_MIN_LENGTH,
+  SKILLS_DIR,
+  TEMPLATES,
+  vscodeInsidersInstallImage,
+  vscodeInstallImage
 };