القائمة
Guidelines for creating high-quality Agent Skills for GitHub Copilot
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Refines and improves user prompts interactively before execution. Use when a task is vague, underspecified, or complex — asks clarifying questions about scope, deliverables, and constraints, then produces a polished, detailed prompt. Never writes code itself.
Performs thorough code reviews covering quality, security, performance, and best practices. Use when asked to review a pull request, audit code changes, check for security vulnerabilities, assess code quality, or provide feedback on a diff. Outputs structured feedback with severity levels and actionable suggestions.
Iterative implementation workflow for requirements. Use this skill when asked to implement a feature, user story, requirement, or change request. Guides through 5 phases: requirement review, implementation planning, sub-agent-driven implementation (code, tests, documentation), code review with rework loop, and final summary. Never commits code — the user always commits manually.
Refactors existing code to improve structure, readability, and maintainability without changing behavior. Use when asked to clean up code, reduce duplication, apply SOLID principles, or address code smells (long methods, tight coupling, poor naming). Always verifies existing tests pass before and after changes.
Applies Angular best practices for building the UI/presentation layer — components, templates, routing, forms, validation, HTTP consumption, interceptors, guards, and error handling. Use when creating components, configuring the router, building reactive or template-driven forms, wiring HttpClient and interceptors, adding route guards, handling client-side errors, or structuring an Angular app. For dependency injection, the provide/config pattern, and modern TypeScript idioms, use angular-fundamentals.
Use when asked to implement, extend, or change a feature, user story, requirement, or bug fix in an Angular / TypeScript project — any task that produces or modifies Angular production code, tests, or documentation. Use when an Angular change request arrives, before writing any code.
| description | Guidelines for creating high-quality Agent Skills for GitHub Copilot |
| applyTo | **/.github/skills/**/SKILL.md, **/.claude/skills/**/SKILL.md |
Instructions for creating effective and portable Agent Skills that enhance GitHub Copilot with specialized capabilities, workflows, and bundled resources.
Agent Skills are self-contained folders with instructions and bundled resources that teach AI agents specialized capabilities. Unlike custom instructions (which define coding standards), skills enable task-specific workflows that can include scripts, examples, templates, and reference data.
Key characteristics:
Skills are stored in specific locations:
| Location | Scope | Recommendation |
|---|---|---|
.github/skills/<skill-name>/ | Project/repository | Recommended for project skills |
.claude/skills/<skill-name>/ | Project/repository | Legacy, for backward compatibility |
~/.github/skills/<skill-name>/ | Personal (user-wide) | Recommended for personal skills |
~/.claude/skills/<skill-name>/ | Personal (user-wide) | Legacy, for backward compatibility |
Each skill must have its own subdirectory containing at minimum a SKILL.md file.
---
name: webapp-testing
description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.
license: Complete terms in LICENSE.txt
---
| Field | Required | Constraints |
|---|---|---|
name | Yes | Lowercase, hyphens for spaces, max 64 characters (e.g., webapp-testing) |
description | Yes | Clear description of capabilities AND use cases, max 1024 characters |
license | No | Reference to LICENSE.txt (e.g., Complete terms in LICENSE.txt) or SPDX identifier |
CRITICAL: The description field is the PRIMARY mechanism for automatic skill discovery. Copilot reads ONLY the name and description to decide whether to load a skill. If your description is vague, the skill will never be activated.
What to include in description:
Good description:
description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.
Poor description:
description: Web testing helpers
The poor description fails because:
The body contains detailed instructions that Copilot loads AFTER the skill is activated. Recommended sections:
| Section | Purpose |
|---|---|
# Title | Brief overview of what this skill enables |
## When to Use This Skill | List of scenarios (reinforces description triggers) |
## Prerequisites | Required tools, dependencies, environment setup |
## Step-by-Step Workflows | Numbered steps for common tasks |
## Troubleshooting | Common issues and solutions table |
## References | Links to bundled docs or external resources |
Skills can include additional files that Copilot accesses on-demand:
| Folder | Purpose | Loaded into Context? | Example Files |
|---|---|---|---|
scripts/ | Executable automation that performs specific operations | When executed | helper.py, validate.sh, build.ts |
references/ | Documentation the AI agent reads to inform decisions | Yes, when referenced | api_reference.md, schema.md, workflow_guide.md |
assets/ | Static files used AS-IS in output (not modified by the AI agent) | No | logo.png, brand-template.pptx, custom-font.ttf |
templates/ | Starter code/scaffolds that the AI agent MODIFIES and builds upon | Yes, when referenced | viewer.html (insert algorithm), hello-world/ (extend) |
.github/skills/my-skill/
├── SKILL.md # Required: Main instructions
├── LICENSE.txt # Recommended: License terms (Apache 2.0 typical)
├── scripts/ # Optional: Executable automation
│ ├── helper.py # Python script
│ └── helper.ps1 # PowerShell script
├── references/ # Optional: Documentation loaded into context
│ ├── api_reference.md
│ ├── workflow-setup.md # Detailed workflow (>5 steps)
│ └── workflow-deployment.md
├── assets/ # Optional: Static files used AS-IS in output
│ ├── baseline.png # Reference image for comparison
│ └── report-template.html
└── templates/ # Optional: Starter code the AI agent modifies
├── scaffold.py # Code scaffold the AI agent customizes
└── config.template # Config template the AI agent fills in
LICENSE.txt: When creating a skill, download the Apache 2.0 license text from https://www.apache.org/licenses/LICENSE-2.0.txt and save as
LICENSE.txt. Update the copyright year and owner in the appendix section.
Assets are static resources consumed unchanged in the output:
logo.png that gets embedded into a generated documentreport-template.html copied as output formatcustom-font.ttf applied to text renderingTemplates are starter code/scaffolds that the AI agent actively modifies:
scaffold.py where the AI agent inserts logicconfig.template where the AI agent fills in values based on user requirementshello-world/ project directory that the AI agent extends with new featuresRule of thumb: If the AI agent reads and builds upon the file content → templates/. If the file is used as-is in output → assets/.
Use relative paths to reference files within the skill directory:
## Available Scripts
Run the [helper script](./scripts/helper.py) to automate common tasks.
See [API reference](./references/api_reference.md) for detailed documentation.
Use the [scaffold](./templates/scaffold.py) as a starting point.
Skills use three-level loading for efficiency:
| Level | What Loads | When |
|---|---|---|
| 1. Discovery | name and description only | Always (lightweight metadata) |
| 2. Instructions | Full SKILL.md body | When request matches description |
| 3. Resources | Scripts, examples, docs | Only when Copilot references them |
This means:
When including scripts, prefer cross-platform languages:
| Language | Use Case |
|---|---|
| Python | Complex automation, data processing |
| pwsh | PowerShell Core scripting |
| Node.js | JavaScript-based tooling |
| Bash/Shell | Simple automation tasks |
Best practices:
--help flag)Include scripts in your skill when:
Scripts enable evolution: even simple operations benefit from being implemented as scripts when they may grow in complexity, need consistent behavior across invocations, or require future extensibility.
--force flags only for destructive operationsDocument parameters clearly:
| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `--input` | Yes | - | Input file or URL to process |
| `--action` | Yes | - | Action to perform |
| `--verbose` | No | `false` | Enable verbose output |
Before publishing a skill:
SKILL.md has valid frontmatter with name and descriptionname is lowercase with hyphens, ≤64 charactersdescription clearly states WHAT it does, WHEN to use it, and relevant KEYWORDSreferences/ folder)references/ folder with clear links from SKILL.mdWhen executing multi-step workflows, create a TODO list where each step references the relevant documentation:
## TODO
- [ ] Step 1: Configure environment - see [workflow-setup.md](./references/workflow-setup.md#environment)
- [ ] Step 2: Build project - see [workflow-setup.md](./references/workflow-setup.md#build)
- [ ] Step 3: Deploy to staging - see [workflow-deployment.md](./references/workflow-deployment.md#staging)
- [ ] Step 4: Run validation - see [workflow-deployment.md](./references/workflow-deployment.md#validation)
- [ ] Step 5: Deploy to production - see [workflow-deployment.md](./references/workflow-deployment.md#production)
This ensures traceability and allows resuming workflows if interrupted.