Merge pull request #496 from github/digitarald/exotic-raven

New awesome agent primitive

Author: digitarald

.github/copilot-instructions.md

@@ -39,3 +39,19 @@ The following instructions are only to be applied when performing a code review.
 - [ ] The file name is lower case, with words separated by hyphens.
 - [ ] Encourage the use of `tools`, but it's not required.
 - [ ] Strongly encourage the use of `model` to specify the model that the chat mode is optimised for.
+
+## Agent Skills guide
+
+**Only apply to folders in the `skills/` directory**
+
+- [ ] The skill folder contains a `SKILL.md` file.
+- [ ] The SKILL.md has markdown front matter.
+- [ ] The SKILL.md has a `name` field.
+- [ ] The `name` field value is lowercase with words separated by hyphens.
+- [ ] The `name` field matches the folder name.
+- [ ] The SKILL.md has a `description` field.
+- [ ] The `description` field is not empty, at least 10 characters, and maximum 1024 characters.
+- [ ] The `description` field value is wrapped in single quotes.
+- [ ] The folder name is lower case, with words separated by hyphens.
+- [ ] Any bundled assets (scripts, templates, data files) are referenced in the SKILL.md instructions.
+- [ ] Bundled assets are reasonably sized (under 5MB per file).

.schemas/collection.schema.json

@@ -50,13 +50,13 @@
           "path": {
             "type": "string",
             "description": "Relative path from repository root to the item file",
-            "pattern": "^(prompts|instructions|agents)/[^/]+\\.(prompt|instructions|agent)\\.md$",
+            "pattern": "^(?:skills/[^/]+/SKILL\\.md|(prompts|instructions|agents)/[^/]+\\.(prompt|instructions|agent)\\.md)$",
             "minLength": 1
           },
           "kind": {
             "type": "string",
             "description": "Type of the item",
-            "enum": ["prompt", "instruction", "agent"]
+            "enum": ["prompt", "instruction", "agent", "skill"]
           },
           "usage": {
             "type": "string",

.vscode/tasks.json

@@ -41,9 +41,33 @@
         "${input:tags}"
       ],
       "problemMatcher": [],
-      "group": "build",
+      "group": "none",
       "detail": "Creates a new collection manifest template.",
       "dependsOn": "npm install"
+    },
+    {
+      "label": "create-skill",
+      "type": "shell",
+      "command": "npm run skill:create",
+      "args": [
+        "--name",
+        "${input:skillName}",
+        "--description",
+        "${input:skillDescription}"
+      ],
+      "problemMatcher": [],
+      "group": "none",
+      "detail": "Creates a new skill template.",
+      "dependsOn": "npm install"
+    },
+    {
+      "label": "validate-skills",
+      "type": "shell",
+      "command": "npm run skill:validate",
+      "problemMatcher": [],
+      "group": "build",
+      "detail": "Validates all skill manifest files.",
+      "dependsOn": "npm install"
     }
   ],
   "inputs": [
@@ -58,6 +82,18 @@
       "description": "Comma separated list of tags",
       "default": "tag1,tag2",
       "type": "promptString"
+    },
+    {
+      "id": "skillName",
+      "description": "Skill name (PascalCase)",
+      "default": "MySkill",
+      "type": "promptString"
+    },
+    {
+      "id": "skillDescription",
+      "description": "Brief description of the skill",
+      "default": "A brief description of my skill.",
+      "type": "promptString"
     }
   ]
 }

AGENTS.md

@@ -7,6 +7,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom
 - **Agents** - Specialized GitHub Copilot agents that integrate with MCP servers
 - **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
 - **Collections** - Curated collections organized around specific themes and workflows
 
 ## Repository Structure
@@ -16,6 +17,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom
 ├── agents/           # Custom GitHub Copilot agent definitions (.agent.md files)
 ├── 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)
 ├── collections/      # Curated collections of resources (.md files)
 ├── docs/             # Documentation for different resource types
 ├── eng/              # Build and automation scripts
@@ -36,13 +38,19 @@ npm run collection:validate
 
 # Create a new collection
 npm run collection:create -- --id <collection-id> --tags <tags>
+
+# Validate agent skills
+npm run skill:validate
+
+# Create a new skill
+npm run skill:create -- --name <skill-name>
 ```
 
 ## Development Workflow
 
-### Working with Agents, Prompts, and Instructions
+### Working with Agents, Prompts, Instructions, and Skills
 
-All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction files (`*.instructions.md`) must include proper markdown front matter:
+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:
 
 #### Agent Files (*.agent.md)
 - Must have `description` field (wrapped in single quotes)
@@ -62,20 +70,40 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi
 - Must have `applyTo` field specifying file patterns (e.g., `'**.js, **.ts'`)
 - File names should be lower case with words separated by hyphens
 
+#### Agent Skills (skills/*/SKILL.md)
+- Each skill is a folder containing a `SKILL.md` file
+- SKILL.md must have `name` field (lowercase with hyphens, matching folder name, max 64 characters)
+- SKILL.md must have `description` field (wrapped in single quotes, 10-1024 characters)
+- Folder names should be lower case with words separated by hyphens
+- Skills can include bundled assets (scripts, templates, data files)
+- Bundled assets should be referenced in the SKILL.md instructions
+- Asset files should be reasonably sized (under 5MB per file)
+- Skills follow the [Agent Skills specification](https://agentskills.io/specification)
+
 ### Adding New Resources
 
-When adding a new agent, prompt, or instruction file:
+When adding a new agent, prompt, instruction, or skill:
 
+**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 Skills:**
+1. Run `npm run skill:create` to scaffold a new skill folder
+2. Edit the generated SKILL.md file with your instructions
+3. Add any bundled assets (scripts, templates, data) to the skill folder
+4. Run `npm run skill:validate` to validate the skill structure
+5. Update the README.md by running: `npm run build`
+6. Verify the skill appears in the generated README
+
 ### Testing Instructions
 
 ```bash
 # Run all validation checks
 npm run collection:validate
+npm run skill:validate
 
 # Build and verify README generation
 npm run build
@@ -148,6 +176,15 @@ For agent files (*.agent.md):
 - [ ] Includes `model` field (strongly recommended)
 - [ ] Considers using `tools` field
 
+For skills (skills/*/):
+- [ ] Folder contains a SKILL.md file
+- [ ] SKILL.md has markdown front matter
+- [ ] Has `name` field matching folder name (lowercase with hyphens, max 64 characters)
+- [ ] Has non-empty `description` field wrapped in single quotes (10-1024 characters)
+- [ ] Folder name is lower case with hyphens
+- [ ] Any bundled assets are referenced in SKILL.md
+- [ ] Bundled assets are under 5MB per file
+
 ## Contributing
 
 This is a community-driven project. Contributions are welcome! Please see:

README.md

@@ -14,6 +14,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 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, and chat modes organized around specific themes and workflows
 
 ## 🌟 Featured Collections

docs/README.skills.md

@@ -0,0 +1,25 @@
+# 🎯 Agent Skills
+
+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 Use Agent Skills
+
+**What's Included:**
+- Each skill is a folder containing a `SKILL.md` instruction file
+- Skills may include helper scripts, code templates, or reference data
+- Skills follow the Agent Skills specification for maximum compatibility
+
+**When to Use:**
+- Skills are ideal for complex, repeatable workflows that benefit from bundled resources
+- Use skills when you need code templates, helper utilities, or reference data alongside instructions
+- Skills provide progressive disclosure - loaded only when needed for specific tasks
+
+**Usage:**
+- 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
+
+| Name | Description | Bundled Assets |
+| ---- | ----------- | -------------- |
+| [webapp-testing](../skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `test-helper.js` |

eng/constants.mjs

@@ -77,6 +77,29 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
 - Access installed agents through the VS Code Chat interface, assign them in CCA, or through Copilot CLI (coming soon)
 - Agents will have access to tools from configured MCP servers
 - Follow agent-specific instructions for optimal usage`,
+
+  skillsSection: `## 🎯 Agent Skills
+
+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.`,
+
+  skillsUsage: `### How to Use Agent Skills
+
+**What's Included:**
+- Each skill is a folder containing a \`SKILL.md\` instruction file
+- Skills may include helper scripts, code templates, or reference data
+- Skills follow the Agent Skills specification for maximum compatibility
+
+**When to Use:**
+- Skills are ideal for complex, repeatable workflows that benefit from bundled resources
+- Use skills when you need code templates, helper utilities, or reference data alongside instructions
+- Skills provide progressive disclosure - loaded only when needed for specific tasks
+
+**Usage:**
+- 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`,
 };
 
 const vscodeInstallImage =
@@ -98,9 +121,16 @@ 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 COLLECTIONS_DIR = path.join(ROOT_FOLDER, "collections");
 const MAX_COLLECTION_ITEMS = 50;
 
+// Agent Skills validation constants
+const SKILL_NAME_MIN_LENGTH = 1;
+const SKILL_NAME_MAX_LENGTH = 64;
+const SKILL_DESCRIPTION_MIN_LENGTH = 10;
+const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+
 const DOCS_DIR = path.join(ROOT_FOLDER, "docs");
 
 export {
@@ -113,8 +143,13 @@ export {
   INSTRUCTIONS_DIR,
   PROMPTS_DIR,
   AGENTS_DIR,
+  SKILLS_DIR,
   COLLECTIONS_DIR,
   MAX_COLLECTION_ITEMS,
+  SKILL_NAME_MIN_LENGTH,
+  SKILL_NAME_MAX_LENGTH,
+  SKILL_DESCRIPTION_MIN_LENGTH,
+  SKILL_DESCRIPTION_MAX_LENGTH,
   DOCS_DIR,
 };