[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6AD4J6YYX4Q2GWS9013ASGM":3,"skill-same:01M6AD4J6YYX4Q2GWS9013ASGM":60},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":31,"linkOnly":32,"markdownContent":33,"markdownBody":34,"frontMatter":35,"refName":36,"commitSha":37,"skillDirectory":38,"forksCount":39,"repositoryHtmlUrl":40,"repositoryHomepageUrl":41,"ownerHtmlUrl":42,"ownerBlogUrl":43,"ownerDescription":44,"updatedAt":45,"install":46,"resources":59},"01M6AD4J6YYX4Q2GWS9013ASGM","custom-agents",null,"Define and validate GitHub custom agent files, prompts, and examples.","github\u002Fgh-aw","github","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9919?v=4","01M6AC83DS133TPXFSP1DHNCC6","GitHub","01M6AD3VCZ4WKQSFSRTPN7N9DN",5636,"MIT","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcustom-agents\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,9,26,27,28,29,30],"custom agents","custom","validate","examples","prompts","files","define","2026-11-10 10:12:30",false,"---\nname: custom-agents\ndescription: Define and validate GitHub custom agent files, prompts, and examples.\n---\n\n\n# GitHub Custom Agent File Format\n\nUse this reference for the GitHub custom agent file format.\n\n## Overview\n\nGitHub Copilot reads custom agent instructions from Markdown files with YAML frontmatter. Use them to define specialized behavior, tool access, and workflows for your repository.\n\n## File Locations\n\nPlace custom agent files in these locations based on scope:\n\n### 1. Repository-wide Instructions\n- **File**: `.github\u002Fcopilot-instructions.md`\n- **Scope**: Applies to all code generation in the repository\n- **Use case**: General coding standards, security requirements, testing practices\n\n### 2. Path-specific Instructions\n- **Directory**: `.github\u002Finstructions\u002F`\n- **Pattern**: `*.instructions.md` (e.g., `frontend.instructions.md`, `backend.instructions.md`)\n- **Scope**: Can target specific directories or file patterns using `applyTo` in frontmatter\n- **Use case**: Framework-specific guidelines, component-specific rules\n\n### 3. Custom Agent Profiles\n- **Directory**: `.github\u002Fagents\u002F` or `.github\u002Fcopilot\u002Finstructions\u002F`\n- **Pattern**: `AGENTS.md`, `*.md` (e.g., `readme-creator.md`, `test-writer.md`)\n- **Scope**: Defines specialized agents with specific capabilities and instructions\n- **Use case**: Task-specific agents (documentation, testing, refactoring)\n\n### 4. agentic workflow integration\n- **Location**: Imported via `imports` field in workflow frontmatter\n- **Pattern**: Any markdown files under `.github\u002Fagents\u002F` directory\n- **Scope**: Custom agent for specific agentic workflow execution\n- **Use case**: Workflow-specific agent configuration\n- **Important**: Only one agent file is allowed per workflow\n\n## File Format\n\n### Basic Structure\n\n```markdown\n# YAML frontmatter (configuration)\nname: agent-name\ndescription: Brief description of agent's purpose\n\n# Markdown body (instructions)\n\nYour natural language instructions for the agent go here.\n```\n\n### Complete YAML Frontmatter Schema\n\n```yaml\n# Required fields\nname: agent-identifier              # Unique identifier for the agent\n\n# Optional descriptive fields\ndescription: >                      # Multi-line description of agent's purpose\n  Agent specializing in specific tasks\n\n# Optional instruction fields\nprompt: |                          # Freeform instructions (alternative to markdown body)\n  Your instructions here\n\n# Optional tool configuration\ntools:                             # List of allowed tools for this agent\n  - createFile\n  - editFiles\n  - codeSearch\n  - search\n\n# Optional path targeting (for .instructions.md files)\napplyTo:                          # Glob patterns for targeted files\u002Fdirectories\n  - \"src\u002Ffrontend\u002F**\"\n  - \"**\u002F*.tsx\"\n\n# Optional MCP server configuration (enterprise\u002Forg only)\nmcp-server:                       # External MCP server configuration\n  url: https:\u002F\u002Fmy-mcp-server.com\n  api-key: ${{ secrets.MCPSERVER_API_KEY }}\n\n# Optional settings\nsettings:                         # Custom runtime or connection settings\n  key: value\n```\n\n## Field Descriptions\n\n### Core Fields\n\n#### name (string, required for agent profiles)\n- Unique identifier for the custom agent\n- Used to reference the agent in workflows or assignments\n- Convention: lowercase with hyphens (e.g., `readme-creator`, `test-writer`)\n\n#### description (string, optional)\n- Human-friendly description of the agent's focus and behavior\n- Helps users understand what the agent specializes in\n- Can be multi-line using YAML's `>` or `|` syntax\n\n#### prompt (string, optional)\n- Alternative to using the markdown body for instructions\n- Contains freeform natural language instructions\n- Use YAML's `|` (literal) or `>` (folded) for multi-line content\n- If both `prompt` and markdown body exist, they are typically combined\n\n### Tool Configuration\n\n#### tools (array of strings, optional)\n- List of tools the agent is allowed to use\n- If omitted or set to `[\"*\"]`, agent has access to all available tools\n- Tool names are **case-insensitive**\n- Supports both GitHub's standard tool aliases and legacy naming conventions\n\n**GitHub Standard Tool Aliases:**\n\nGitHub Copilot defines a standardized set of tool aliases for custom agents:\n\n- **`read`** - Access and read contents of files or code\n- **`edit`** - Make changes in code files, apply edits or refactoring\n- **`search`** - Search codebase for keywords, references, or patterns\n- **`pr`** - Create, manage, or update pull requests\n- **`issue`** - Create, manage, or update issues\n\n**Legacy Tool Names:**\n\nFor backward compatibility, these legacy tool names are still supported:\n\n- `createFile` - Create new files (use `edit` instead)\n- `editFiles` - Modify existing files (use `edit` instead)\n- `deleteFiles` - Remove files (use `edit` instead)\n- `codeSearch` - Semantic code search (use `search` instead)\n- `runCommand` - Execute shell commands\n- `getFile` - Read file contents (use `read` instead)\n- `listFiles` - List directory contents (use `read` instead)\n\n**MCP Server Tool Prefixes:**\n\nWhen using Model Context Protocol (MCP) servers, you can specify tools with server prefixes:\n- Single tool: `my-mcp-server\u002Ftool-name`\n- All tools from a server: `my-mcp-server\u002F*`\n\n**Examples:**\n\n```yaml\n# Using standard tool aliases\ntools:\n  - read\n  - edit\n  - search\n\n# Enable all tools with wildcard\ntools: [\"*\"]\n\n# Using legacy names (still supported)\ntools:\n  - editFiles\n  - createFile\n  - search\n\n# Mixed standard and MCP server tools\ntools:\n  - read\n  - edit\n  - github-mcp\u002Fcreate_issue\n  - custom-mcp\u002F*\n\n# Empty list disables all tools\ntools: []\n```\n\n### Path Targeting\n\n#### applyTo (array of strings, optional)\n- Only used in `.instructions.md` files\n- Specifies glob patterns for files\u002Fdirectories these instructions apply to\n- Supports wildcards: `*` (any characters), `**` (any directories)\n- Multiple patterns can be specified\n\n**Example:**\n```yaml\napplyTo:\n  - \"src\u002Ffrontend\u002F**\u002F*.tsx\"\n  - \"src\u002Ffrontend\u002F**\u002F*.ts\"\n  - \"components\u002F**\"\n```\n\n### Enterprise Features\n\n#### mcp-server (object, optional)\n- Configuration for external MCP (Model Context Protocol) servers\n- Typically used in enterprise or organization settings\n- Allows integration with custom tools and services\n\n**Fields:**\n- `url` (string): MCP server endpoint\n- `api-key` (string): Authentication key (use GitHub secrets)\n\n**Example:**\n```yaml\nmcp-server:\n  url: https:\u002F\u002Finternal-tools.company.com\u002Fmcp\n  api-key: ${{ secrets.INTERNAL_MCP_KEY }}\n```\n\n#### settings (object, optional)\n- Custom runtime or connection settings\n- Key-value pairs for agent-specific configuration\n- Format and available keys depend on the agent implementation\n\n## Usage Patterns\n\n### Pattern 1: Repository-wide Standards\n\n**File:** `.github\u002Fcopilot-instructions.md`\n\n```markdown\ndescription: Repository-wide coding standards\n\n# Coding Standards\n\n## Style Guide\n- Use single quotes in JavaScript\u002FTypeScript\n- Follow ESLint configuration in `.eslintrc.json`\n- Maximum line length: 100 characters\n\n## Security\n- Always set `httpOnly` and `secure` flags for cookies\n- Validate all user input\n- Use parameterized queries for database access\n\n## Testing\n- All new code must include Jest tests\n- Aim for >80% code coverage\n- Test edge cases and error conditions\n```\n\n### Pattern 2: Path-specific Instructions\n\n**File:** `.github\u002Finstructions\u002Ffrontend.instructions.md`\n\n```markdown\ndescription: Frontend development guidelines\napplyTo:\n  - \"src\u002Ffrontend\u002F**\"\n  - \"components\u002F**\"\n\n# Frontend Development Guidelines\n\n## Component Structure\n- Use React functional components with hooks\n- Prefer composition over inheritance\n- Keep components small and focused (\u003C 150 lines)\n\n## Styling\n- Use CSS Modules for component styles\n- Follow BEM naming convention\n- Use Tailwind utility classes where appropriate\n\n## State Management\n- Use React Context for global state\n- Keep local state in components when possible\n- Use reducers for complex state logic\n```\n\n### Pattern 3: Custom Agent Profile\n\n**File:** `.github\u002Fagents\u002Freadme-creator.md`\n\n```markdown\nname: readme-creator\ndescription: Agent specializing in creating and improving README files\ntools:\n  - read\n  - edit\n  - search\n\n# README Creator Agent\n\nYou are a documentation specialist focused on creating clear, comprehensive README files.\n\n## Responsibilities\n- Create well-structured README.md files for projects\n- Include all standard sections: Overview, Installation, Usage, Contributing\n- Generate accurate code examples\n- Ensure documentation is up-to-date with codebase\n\n## Style Guidelines\n- Use clear, concise language\n- Include code examples with syntax highlighting\n- Add badges for build status, coverage, version\n- Organize with logical heading hierarchy\n- Include a table of contents for long READMEs\n\n## Quality Standards\n- Verify all code examples are accurate\n- Test installation instructions\n- Ensure links are valid and working\n- Check for proper Markdown formatting\n```\n\n### Pattern 4: Test Writer Agent\n\n**File:** `.github\u002Fagents\u002Ftest-writer.md`\n\n```markdown\nname: test-writer\ndescription: Specialized agent for writing comprehensive test suites\ntools:\n  - read\n  - edit\n  - search\n\n# Test Writer Agent\n\nYou specialize in creating comprehensive, well-structured test suites.\n\n## Testing Framework\n- Use Jest for JavaScript\u002FTypeScript\n- Follow AAA pattern: Arrange, Act, Assert\n- Use descriptive test names: \"should [expected behavior] when [condition]\"\n\n## Test Coverage\n- Write unit tests for all public functions\n- Create integration tests for API endpoints\n- Add edge case tests (null, undefined, empty, boundary values)\n- Test error conditions and exception handling\n\n## Test Organization\n- Group related tests with `describe` blocks\n- Use `beforeEach` and `afterEach` for setup\u002Fteardown\n- Keep tests independent and isolated\n- Mock external dependencies\n\n## Best Practices\n- One assertion per test when possible\n- Use test data builders for complex objects\n- Avoid test interdependence\n- Keep tests fast (\u003C 1 second each)\n```\n\n### Pattern 5: Agentic Workflow Integration\n\n**File:** `.github\u002Fworkflows\u002Fcode-review.md`\n\n```markdown\non:\n  pull_request:\n    types: [opened, synchronize]\npermissions:\n  contents: read\n  pull-requests: write\nengine:\n  id: copilot\n  custom-agent: .github\u002Fagents\u002Fcode-reviewer.md\n\n# Automated Code Review\n\nReview the pull request changes and provide constructive feedback.\n```\n\n**File:** `.github\u002Fagents\u002Fcode-reviewer.md`\n\n```markdown\nname: code-reviewer\ndescription: Agent specialized in performing code reviews\ntools:\n  - read\n  - search\n\n# Code Review Agent\n\nYou are an experienced code reviewer focused on code quality, security, and best practices.\n\n## Review Checklist\n- Code follows repository style guidelines\n- Proper error handling is implemented\n- Security best practices are followed\n- Tests are included for new functionality\n- Documentation is updated where needed\n- No unnecessary complexity\n\n## Feedback Style\n- Be constructive and specific\n- Explain the reasoning behind suggestions\n- Prioritize issues (critical, important, minor)\n- Acknowledge good patterns and improvements\n- Provide code examples for suggestions\n```\n\n## Integration with gh-aw\n\nThe gh-aw (GitHub Agentic Workflows) tool supports custom agent files through the `imports` field in workflow frontmatter. Any markdown files under the `.github\u002Fagents\u002F` directory are treated as custom agent files when imported.\n\n### Preferred way to install skills in workflows\n\nUse the `skills:` frontmatter field as the preferred way to install external skills for workflow runs. This installs skills during activation and persists them correctly between jobs. Use the top-level `plugins:` field the same way for agent plugins. Never add on-the-fly installation steps or ask the agent to install a skill or plugin from the prompt.\n\nUse `imports:` for workflow prompt\u002Fcontext files (including local custom agent files), not as the primary skill installation path.\n\n```markdown\non: pull_request\nengine:\n  id: copilot\nskills:\n  - mattpocock\u002Fskills\u002Ftdd@801dca688564c529fa84f247f64472520d9ebe28\nplugins:\n  - octo-org\u002Fagent-plugin@v1\nimports:\n  - .github\u002Fagents\u002Fcode-reviewer.md\n\n# Workflow prompt\n```\n\n### Configuration\n\n```markdown\non: issues\nengine:\n  id: copilot\nimports:\n  - .github\u002Fagents\u002Fmy-agent.md\n\n# My Workflow\n\nInstructions for the workflow...\n```\n\n### Supported Engines\n\nCustom agent files are supported by the following engines:\n\n1. **Copilot** - Uses `--agent \u003Cpath>` flag to load custom agent file\n2. **Claude** - Prepends agent file content to the workflow prompt\n3. **Codex** - Prepends agent file content to the workflow prompt\n\n### File Path Resolution\n\n- Agent files are imported via the `imports` field\n- Must be markdown files located under `.github\u002Fagents\u002F` directory\n- Only one agent file is allowed per workflow\n- File is validated during workflow compilation\n- Checkout step is automatically added if agent file is imported\n\n### Example Workflow with Custom Agent\n\n```markdown\non:\n  issues:\n    types: [opened]\npermissions:\n  contents: read\n  issues: write\nengine:\n  id: copilot\nimports:\n  - .github\u002Fagents\u002Fissue-triager.md\ntools:\n  github:\n    allowed:\n      - add_labels_to_issue\n      - create_issue_comment\n\n# Issue Triage Workflow\n\nAnalyze the issue and categorize it appropriately.\n```\n\n## Best Practices\n\n### 1. Keep Instructions Focused\n- Each agent should have a clear, specific purpose\n- Avoid mixing unrelated concerns in a single agent\n- Create multiple specialized agents rather than one general-purpose agent\n\n### 2. Be Explicit and Specific\n- Provide concrete examples of expected behavior\n- Define clear success criteria\n- Specify edge cases and error handling\n\n### 3. Use Appropriate Scoping\n- Repository-wide instructions for universal standards\n- Path-specific instructions for framework or directory-specific rules\n- Custom agents for task-specific workflows\n\n### 4. Test Agent Behavior\n- Verify agent follows instructions correctly\n- Test with various input scenarios\n- Iterate based on actual agent performance\n\n### 5. Maintain and Update\n- Keep instructions current with codebase changes\n- Review and refine based on agent performance\n- Remove outdated or conflicting instructions\n\n### 6. Security Considerations\n- Limit tool access to what's necessary\n- Be cautious with file deletion permissions\n- Use secrets for sensitive configuration\n- Review agent actions regularly\n\n## Common Patterns\n\n### Documentation Agent\n```yaml\nname: documentation-specialist\ndescription: Creates and maintains technical documentation\ntools: [read, edit, search]\n```\n\n### Refactoring Agent\n```yaml\nname: code-refactorer\ndescription: Improves code quality and structure\ntools: [read, edit, search]\n```\n\n### Security Auditor\n```yaml\nname: security-auditor\ndescription: Reviews code for security vulnerabilities\ntools: [read, search]\n```\n\n### Migration Assistant\n```yaml\nname: migration-helper\ndescription: Assists with framework or library migrations\ntools: [read, edit, search]\n```\n\n### Issue Management Agent\n```yaml\nname: issue-manager\ndescription: Manages GitHub issues and project tracking\ntools: [read, issue]\n```\n\n### Pull Request Assistant\n```yaml\nname: pr-assistant\ndescription: Assists with pull request creation and management\ntools: [read, edit, pr]\n```\n\n## Troubleshooting\n\n### Agent Not Following Instructions\n- Make instructions more explicit and specific\n- Provide concrete examples\n- Break down complex instructions into steps\n- Ensure instructions don't conflict\n\n### Tool Access Issues\n- Verify tools are listed in `tools` array\n- Check agent has necessary permissions\n- Ensure tools are available in the environment\n\n### Path Targeting Not Working\n- Verify glob patterns are correct\n- Check file paths match patterns\n- Ensure `applyTo` is only used in `.instructions.md` files\n\n### Custom Agent File Not Found\n- Verify agent file is imported in the `imports` field\n- Ensure file exists and is committed under `.github\u002Fagents\u002F` directory\n- Confirm agent file path is correct in imports list\n- Remember: only one agent file is allowed per workflow\n\n## References\n\n- [GitHub Copilot Agent Filess Configuration](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Freference\u002Fcopilot-custom-agents-configuration) - Official reference for custom agent configuration including tool aliases\n- [GitHub Copilot Custom Instructions Documentation](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fhow-tos\u002Fconfigure-custom-instructions\u002Fadd-repository-instructions)\n- [About Custom Agents](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fconcepts\u002Fagents\u002Fcoding-agent\u002Fabout-custom-agents)\n- [GitHub Blog: Custom Instructions Support](https:\u002F\u002Fgithub.blog\u002Fchangelog\u002F2025-07-23-github-copilot-coding-agent-now-supports-instructions-md-custom-instructions\u002F)\n- [GitHub Blog: AGENTS.md Support](https:\u002F\u002Fgithub.blog\u002Fchangelog\u002F2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions\u002F)\n\n## Examples in This Repository\n\nThe gh-aw repository uses custom agent files for performance engineering guides:\n\n- `.github\u002Fcopilot\u002Finstructions\u002Fci-performance.md` - CI\u002FCD optimization\n- `.github\u002Fcopilot\u002Finstructions\u002Fworkflow-performance.md` - Workflow efficiency\n- `.github\u002Fcopilot\u002Finstructions\u002Fbuild-performance.md` - Build optimization\n- `.github\u002Fcopilot\u002Finstructions\u002Fcli-performance.md` - CLI performance\n\nThese files provide specialized guidance for performance engineering tasks and demonstrate the custom agent file format in practice.\n","# GitHub Custom Agent File Format\n\nUse this reference for the GitHub custom agent file format.\n\n## Overview\n\nGitHub Copilot reads custom agent instructions from Markdown files with YAML frontmatter. Use them to define specialized behavior, tool access, and workflows for your repository.\n\n## File Locations\n\nPlace custom agent files in these locations based on scope:\n\n### 1. Repository-wide Instructions\n- **File**: `.github\u002Fcopilot-instructions.md`\n- **Scope**: Applies to all code generation in the repository\n- **Use case**: General coding standards, security requirements, testing practices\n\n### 2. Path-specific Instructions\n- **Directory**: `.github\u002Finstructions\u002F`\n- **Pattern**: `*.instructions.md` (e.g., `frontend.instructions.md`, `backend.instructions.md`)\n- **Scope**: Can target specific directories or file patterns using `applyTo` in frontmatter\n- **Use case**: Framework-specific guidelines, component-specific rules\n\n### 3. Custom Agent Profiles\n- **Directory**: `.github\u002Fagents\u002F` or `.github\u002Fcopilot\u002Finstructions\u002F`\n- **Pattern**: `AGENTS.md`, `*.md` (e.g., `readme-creator.md`, `test-writer.md`)\n- **Scope**: Defines specialized agents with specific capabilities and instructions\n- **Use case**: Task-specific agents (documentation, testing, refactoring)\n\n### 4. agentic workflow integration\n- **Location**: Imported via `imports` field in workflow frontmatter\n- **Pattern**: Any markdown files under `.github\u002Fagents\u002F` directory\n- **Scope**: Custom agent for specific agentic workflow execution\n- **Use case**: Workflow-specific agent configuration\n- **Important**: Only one agent file is allowed per workflow\n\n## File Format\n\n### Basic Structure\n\n```markdown\n# YAML frontmatter (configuration)\nname: agent-name\ndescription: Brief description of agent's purpose\n\n# Markdown body (instructions)\n\nYour natural language instructions for the agent go here.\n```\n\n### Complete YAML Frontmatter Schema\n\n```yaml\n# Required fields\nname: agent-identifier              # Unique identifier for the agent\n\n# Optional descriptive fields\ndescription: >                      # Multi-line description of agent's purpose\n  Agent specializing in specific tasks\n\n# Optional instruction fields\nprompt: |                          # Freeform instructions (alternative to markdown body)\n  Your instructions here\n\n# Optional tool configuration\ntools:                             # List of allowed tools for this agent\n  - createFile\n  - editFiles\n  - codeSearch\n  - search\n\n# Optional path targeting (for .instructions.md files)\napplyTo:                          # Glob patterns for targeted files\u002Fdirectories\n  - \"src\u002Ffrontend\u002F**\"\n  - \"**\u002F*.tsx\"\n\n# Optional MCP server configuration (enterprise\u002Forg only)\nmcp-server:                       # External MCP server configuration\n  url: https:\u002F\u002Fmy-mcp-server.com\n  api-key: ${{ secrets.MCPSERVER_API_KEY }}\n\n# Optional settings\nsettings:                         # Custom runtime or connection settings\n  key: value\n```\n\n## Field Descriptions\n\n### Core Fields\n\n#### name (string, required for agent profiles)\n- Unique identifier for the custom agent\n- Used to reference the agent in workflows or assignments\n- Convention: lowercase with hyphens (e.g., `readme-creator`, `test-writer`)\n\n#### description (string, optional)\n- Human-friendly description of the agent's focus and behavior\n- Helps users understand what the agent specializes in\n- Can be multi-line using YAML's `>` or `|` syntax\n\n#### prompt (string, optional)\n- Alternative to using the markdown body for instructions\n- Contains freeform natural language instructions\n- Use YAML's `|` (literal) or `>` (folded) for multi-line content\n- If both `prompt` and markdown body exist, they are typically combined\n\n### Tool Configuration\n\n#### tools (array of strings, optional)\n- List of tools the agent is allowed to use\n- If omitted or set to `[\"*\"]`, agent has access to all available tools\n- Tool names are **case-insensitive**\n- Supports both GitHub's standard tool aliases and legacy naming conventions\n\n**GitHub Standard Tool Aliases:**\n\nGitHub Copilot defines a standardized set of tool aliases for custom agents:\n\n- **`read`** - Access and read contents of files or code\n- **`edit`** - Make changes in code files, apply edits or refactoring\n- **`search`** - Search codebase for keywords, references, or patterns\n- **`pr`** - Create, manage, or update pull requests\n- **`issue`** - Create, manage, or update issues\n\n**Legacy Tool Names:**\n\nFor backward compatibility, these legacy tool names are still supported:\n\n- `createFile` - Create new files (use `edit` instead)\n- `editFiles` - Modify existing files (use `edit` instead)\n- `deleteFiles` - Remove files (use `edit` instead)\n- `codeSearch` - Semantic code search (use `search` instead)\n- `runCommand` - Execute shell commands\n- `getFile` - Read file contents (use `read` instead)\n- `listFiles` - List directory contents (use `read` instead)\n\n**MCP Server Tool Prefixes:**\n\nWhen using Model Context Protocol (MCP) servers, you can specify tools with server prefixes:\n- Single tool: `my-mcp-server\u002Ftool-name`\n- All tools from a server: `my-mcp-server\u002F*`\n\n**Examples:**\n\n```yaml\n# Using standard tool aliases\ntools:\n  - read\n  - edit\n  - search\n\n# Enable all tools with wildcard\ntools: [\"*\"]\n\n# Using legacy names (still supported)\ntools:\n  - editFiles\n  - createFile\n  - search\n\n# Mixed standard and MCP server tools\ntools:\n  - read\n  - edit\n  - github-mcp\u002Fcreate_issue\n  - custom-mcp\u002F*\n\n# Empty list disables all tools\ntools: []\n```\n\n### Path Targeting\n\n#### applyTo (array of strings, optional)\n- Only used in `.instructions.md` files\n- Specifies glob patterns for files\u002Fdirectories these instructions apply to\n- Supports wildcards: `*` (any characters), `**` (any directories)\n- Multiple patterns can be specified\n\n**Example:**\n```yaml\napplyTo:\n  - \"src\u002Ffrontend\u002F**\u002F*.tsx\"\n  - \"src\u002Ffrontend\u002F**\u002F*.ts\"\n  - \"components\u002F**\"\n```\n\n### Enterprise Features\n\n#### mcp-server (object, optional)\n- Configuration for external MCP (Model Context Protocol) servers\n- Typically used in enterprise or organization settings\n- Allows integration with custom tools and services\n\n**Fields:**\n- `url` (string): MCP server endpoint\n- `api-key` (string): Authentication key (use GitHub secrets)\n\n**Example:**\n```yaml\nmcp-server:\n  url: https:\u002F\u002Finternal-tools.company.com\u002Fmcp\n  api-key: ${{ secrets.INTERNAL_MCP_KEY }}\n```\n\n#### settings (object, optional)\n- Custom runtime or connection settings\n- Key-value pairs for agent-specific configuration\n- Format and available keys depend on the agent implementation\n\n## Usage Patterns\n\n### Pattern 1: Repository-wide Standards\n\n**File:** `.github\u002Fcopilot-instructions.md`\n\n```markdown\ndescription: Repository-wide coding standards\n\n# Coding Standards\n\n## Style Guide\n- Use single quotes in JavaScript\u002FTypeScript\n- Follow ESLint configuration in `.eslintrc.json`\n- Maximum line length: 100 characters\n\n## Security\n- Always set `httpOnly` and `secure` flags for cookies\n- Validate all user input\n- Use parameterized queries for database access\n\n## Testing\n- All new code must include Jest tests\n- Aim for >80% code coverage\n- Test edge cases and error conditions\n```\n\n### Pattern 2: Path-specific Instructions\n\n**File:** `.github\u002Finstructions\u002Ffrontend.instructions.md`\n\n```markdown\ndescription: Frontend development guidelines\napplyTo:\n  - \"src\u002Ffrontend\u002F**\"\n  - \"components\u002F**\"\n\n# Frontend Development Guidelines\n\n## Component Structure\n- Use React functional components with hooks\n- Prefer composition over inheritance\n- Keep components small and focused (\u003C 150 lines)\n\n## Styling\n- Use CSS Modules for component styles\n- Follow BEM naming convention\n- Use Tailwind utility classes where appropriate\n\n## State Management\n- Use React Context for global state\n- Keep local state in components when possible\n- Use reducers for complex state logic\n```\n\n### Pattern 3: Custom Agent Profile\n\n**File:** `.github\u002Fagents\u002Freadme-creator.md`\n\n```markdown\nname: readme-creator\ndescription: Agent specializing in creating and improving README files\ntools:\n  - read\n  - edit\n  - search\n\n# README Creator Agent\n\nYou are a documentation specialist focused on creating clear, comprehensive README files.\n\n## Responsibilities\n- Create well-structured README.md files for projects\n- Include all standard sections: Overview, Installation, Usage, Contributing\n- Generate accurate code examples\n- Ensure documentation is up-to-date with codebase\n\n## Style Guidelines\n- Use clear, concise language\n- Include code examples with syntax highlighting\n- Add badges for build status, coverage, version\n- Organize with logical heading hierarchy\n- Include a table of contents for long READMEs\n\n## Quality Standards\n- Verify all code examples are accurate\n- Test installation instructions\n- Ensure links are valid and working\n- Check for proper Markdown formatting\n```\n\n### Pattern 4: Test Writer Agent\n\n**File:** `.github\u002Fagents\u002Ftest-writer.md`\n\n```markdown\nname: test-writer\ndescription: Specialized agent for writing comprehensive test suites\ntools:\n  - read\n  - edit\n  - search\n\n# Test Writer Agent\n\nYou specialize in creating comprehensive, well-structured test suites.\n\n## Testing Framework\n- Use Jest for JavaScript\u002FTypeScript\n- Follow AAA pattern: Arrange, Act, Assert\n- Use descriptive test names: \"should [expected behavior] when [condition]\"\n\n## Test Coverage\n- Write unit tests for all public functions\n- Create integration tests for API endpoints\n- Add edge case tests (null, undefined, empty, boundary values)\n- Test error conditions and exception handling\n\n## Test Organization\n- Group related tests with `describe` blocks\n- Use `beforeEach` and `afterEach` for setup\u002Fteardown\n- Keep tests independent and isolated\n- Mock external dependencies\n\n## Best Practices\n- One assertion per test when possible\n- Use test data builders for complex objects\n- Avoid test interdependence\n- Keep tests fast (\u003C 1 second each)\n```\n\n### Pattern 5: Agentic Workflow Integration\n\n**File:** `.github\u002Fworkflows\u002Fcode-review.md`\n\n```markdown\non:\n  pull_request:\n    types: [opened, synchronize]\npermissions:\n  contents: read\n  pull-requests: write\nengine:\n  id: copilot\n  custom-agent: .github\u002Fagents\u002Fcode-reviewer.md\n\n# Automated Code Review\n\nReview the pull request changes and provide constructive feedback.\n```\n\n**File:** `.github\u002Fagents\u002Fcode-reviewer.md`\n\n```markdown\nname: code-reviewer\ndescription: Agent specialized in performing code reviews\ntools:\n  - read\n  - search\n\n# Code Review Agent\n\nYou are an experienced code reviewer focused on code quality, security, and best practices.\n\n## Review Checklist\n- Code follows repository style guidelines\n- Proper error handling is implemented\n- Security best practices are followed\n- Tests are included for new functionality\n- Documentation is updated where needed\n- No unnecessary complexity\n\n## Feedback Style\n- Be constructive and specific\n- Explain the reasoning behind suggestions\n- Prioritize issues (critical, important, minor)\n- Acknowledge good patterns and improvements\n- Provide code examples for suggestions\n```\n\n## Integration with gh-aw\n\nThe gh-aw (GitHub Agentic Workflows) tool supports custom agent files through the `imports` field in workflow frontmatter. Any markdown files under the `.github\u002Fagents\u002F` directory are treated as custom agent files when imported.\n\n### Preferred way to install skills in workflows\n\nUse the `skills:` frontmatter field as the preferred way to install external skills for workflow runs. This installs skills during activation and persists them correctly between jobs. Use the top-level `plugins:` field the same way for agent plugins. Never add on-the-fly installation steps or ask the agent to install a skill or plugin from the prompt.\n\nUse `imports:` for workflow prompt\u002Fcontext files (including local custom agent files), not as the primary skill installation path.\n\n```markdown\non: pull_request\nengine:\n  id: copilot\nskills:\n  - mattpocock\u002Fskills\u002Ftdd@801dca688564c529fa84f247f64472520d9ebe28\nplugins:\n  - octo-org\u002Fagent-plugin@v1\nimports:\n  - .github\u002Fagents\u002Fcode-reviewer.md\n\n# Workflow prompt\n```\n\n### Configuration\n\n```markdown\non: issues\nengine:\n  id: copilot\nimports:\n  - .github\u002Fagents\u002Fmy-agent.md\n\n# My Workflow\n\nInstructions for the workflow...\n```\n\n### Supported Engines\n\nCustom agent files are supported by the following engines:\n\n1. **Copilot** - Uses `--agent \u003Cpath>` flag to load custom agent file\n2. **Claude** - Prepends agent file content to the workflow prompt\n3. **Codex** - Prepends agent file content to the workflow prompt\n\n### File Path Resolution\n\n- Agent files are imported via the `imports` field\n- Must be markdown files located under `.github\u002Fagents\u002F` directory\n- Only one agent file is allowed per workflow\n- File is validated during workflow compilation\n- Checkout step is automatically added if agent file is imported\n\n### Example Workflow with Custom Agent\n\n```markdown\non:\n  issues:\n    types: [opened]\npermissions:\n  contents: read\n  issues: write\nengine:\n  id: copilot\nimports:\n  - .github\u002Fagents\u002Fissue-triager.md\ntools:\n  github:\n    allowed:\n      - add_labels_to_issue\n      - create_issue_comment\n\n# Issue Triage Workflow\n\nAnalyze the issue and categorize it appropriately.\n```\n\n## Best Practices\n\n### 1. Keep Instructions Focused\n- Each agent should have a clear, specific purpose\n- Avoid mixing unrelated concerns in a single agent\n- Create multiple specialized agents rather than one general-purpose agent\n\n### 2. Be Explicit and Specific\n- Provide concrete examples of expected behavior\n- Define clear success criteria\n- Specify edge cases and error handling\n\n### 3. Use Appropriate Scoping\n- Repository-wide instructions for universal standards\n- Path-specific instructions for framework or directory-specific rules\n- Custom agents for task-specific workflows\n\n### 4. Test Agent Behavior\n- Verify agent follows instructions correctly\n- Test with various input scenarios\n- Iterate based on actual agent performance\n\n### 5. Maintain and Update\n- Keep instructions current with codebase changes\n- Review and refine based on agent performance\n- Remove outdated or conflicting instructions\n\n### 6. Security Considerations\n- Limit tool access to what's necessary\n- Be cautious with file deletion permissions\n- Use secrets for sensitive configuration\n- Review agent actions regularly\n\n## Common Patterns\n\n### Documentation Agent\n```yaml\nname: documentation-specialist\ndescription: Creates and maintains technical documentation\ntools: [read, edit, search]\n```\n\n### Refactoring Agent\n```yaml\nname: code-refactorer\ndescription: Improves code quality and structure\ntools: [read, edit, search]\n```\n\n### Security Auditor\n```yaml\nname: security-auditor\ndescription: Reviews code for security vulnerabilities\ntools: [read, search]\n```\n\n### Migration Assistant\n```yaml\nname: migration-helper\ndescription: Assists with framework or library migrations\ntools: [read, edit, search]\n```\n\n### Issue Management Agent\n```yaml\nname: issue-manager\ndescription: Manages GitHub issues and project tracking\ntools: [read, issue]\n```\n\n### Pull Request Assistant\n```yaml\nname: pr-assistant\ndescription: Assists with pull request creation and management\ntools: [read, edit, pr]\n```\n\n## Troubleshooting\n\n### Agent Not Following Instructions\n- Make instructions more explicit and specific\n- Provide concrete examples\n- Break down complex instructions into steps\n- Ensure instructions don't conflict\n\n### Tool Access Issues\n- Verify tools are listed in `tools` array\n- Check agent has necessary permissions\n- Ensure tools are available in the environment\n\n### Path Targeting Not Working\n- Verify glob patterns are correct\n- Check file paths match patterns\n- Ensure `applyTo` is only used in `.instructions.md` files\n\n### Custom Agent File Not Found\n- Verify agent file is imported in the `imports` field\n- Ensure file exists and is committed under `.github\u002Fagents\u002F` directory\n- Confirm agent file path is correct in imports list\n- Remember: only one agent file is allowed per workflow\n\n## References\n\n- [GitHub Copilot Agent Filess Configuration](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Freference\u002Fcopilot-custom-agents-configuration) - Official reference for custom agent configuration including tool aliases\n- [GitHub Copilot Custom Instructions Documentation](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fhow-tos\u002Fconfigure-custom-instructions\u002Fadd-repository-instructions)\n- [About Custom Agents](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fconcepts\u002Fagents\u002Fcoding-agent\u002Fabout-custom-agents)\n- [GitHub Blog: Custom Instructions Support](https:\u002F\u002Fgithub.blog\u002Fchangelog\u002F2025-07-23-github-copilot-coding-agent-now-supports-instructions-md-custom-instructions\u002F)\n- [GitHub Blog: AGENTS.md Support](https:\u002F\u002Fgithub.blog\u002Fchangelog\u002F2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions\u002F)\n\n## Examples in This Repository\n\nThe gh-aw repository uses custom agent files for performance engineering guides:\n\n- `.github\u002Fcopilot\u002Finstructions\u002Fci-performance.md` - CI\u002FCD optimization\n- `.github\u002Fcopilot\u002Finstructions\u002Fworkflow-performance.md` - Workflow efficiency\n- `.github\u002Fcopilot\u002Finstructions\u002Fbuild-performance.md` - Build optimization\n- `.github\u002Fcopilot\u002Finstructions\u002Fcli-performance.md` - CLI performance\n\nThese files provide specialized guidance for performance engineering tasks and demonstrate the custom agent file format in practice.\n",{"name":5,"description":7},"main","8541229759617347888641eba917d3b0ad66a984",".github\u002Fskills\u002Fcustom-agents",626,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw","https:\u002F\u002Fgh.io\u002Fgh-aw","https:\u002F\u002Fgithub.com\u002Fgithub","https:\u002F\u002Fgithub.com\u002Fabout","How people build software.","2026-11-15 06:45:15",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":58},[48,51,54],{"tool":49,"command":50},"npx","npx skills add github\u002Fgh-aw --skill custom-agents",{"tool":52,"command":53},"bunx","bunx skills add github\u002Fgh-aw --skill custom-agents",{"tool":55,"command":56},"pnpm","pnpm dlx skills add github\u002Fgh-aw --skill custom-agents","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcustom-agents\u002FSKILL.md",true,[],[61,86,104,129,155,173],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":71,"publishedAt":31},"01M6ADC942STTXHFV410J4DH0X","GitHub Agentic Workflows","GitHub Agentic Workflows (`gh-aw`) is a GitHub CLI extension for writing Agentic Workflows in markdown and compiling them to GitHub Actions.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002FSKILL.md",[67,70],{"categoryNo":68,"categoryName":69,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[9,72,73,74,75,76,77,78,79,80,81,82,83,84,85],"agentic","agentic workflows","github agentic workflows","workflows","github cli","gh","extension","for","compiling","cli","writing","actions","github actions","markdown",{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":31},"01M6ADC6ZXSA46N9XD6VNAP1MS","windows-compatibility","Cross-platform path handling and command patterns","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fwindows-compatibility\u002FSKILL.md",[],[93,94,95,96,97,98,99,100,101,102,103],"windows","windows compatibility","compatibility","bugs","path","high","platform","cross-platform","patterns","command","git",{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":31},"01M6ADC44957SVQF96R5YY247P","versioning-policy","Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fversioning-policy\u002FSKILL.md",[],[111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,79,127,81,128],"policy","versioning policy","versioning","incident","gate","implementation","version","Rules","workspace","pr","ci","npm","semver","release","squad","resolution","incidents","sdk",{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":139,"publishedAt":31},"01M6ADC1PHMEAEVR87F8PDR89X","tiered-memory","Three-tier agent memory model (hot\u002Fcold\u002Fwiki) for context reduction per spawn","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftiered-memory\u002FSKILL.md",[135,138],{"categoryNo":136,"categoryName":137,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[140,141,142,143,79,144,145,146,147,148,149,150,151,152,153,154],"tiered memory","memory","memory-management","model","cold","proposal","runtime","three","spawn","management","context","wiki","agent memory","performance","design",{"skillNo":156,"name":157,"nameZh":6,"description":158,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":159,"categories":160,"keywords":164,"publishedAt":31},"01M6ADBZTDGFM0E25EWRQEMYEH","test-discipline","Update tests when changing APIs — no exceptions","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftest-discipline\u002FSKILL.md",[161],{"categoryNo":162,"categoryName":163,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",[165,166,167,168,169,98,170,114,171,172],"test discipline","discipline","test","sync","when","tests","quality","update",{"skillNo":174,"name":125,"nameZh":6,"description":175,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":176,"categories":177,"keywords":178,"publishedAt":31},"01M6ADBX5MJP4Z7CG4XTV8ZVT8","Squad's command catalog and interactive menu. Invoke via \u002Fsquad (slash command) or natural language (\"squad commands\", \"what can squad do\", \"show me squad options\"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fsquad\u002FSKILL.md",[],[125,179,180,181,182,183,184,185,186,187,188,189,190,102,143,191,192,193,194,195,196,197,81],"show","interactive menu","invoke","coordinator","as","commands","upgrade","options","me","natural language","do","install","team","show me","plugins","issues","state","squad commands","sessions"]