AgentForceTest/AGENT_SKILLS_GUIDE.md

# VS Code Agent Skills: Complete Guide

## Summary

Agent Skills are reusable folders containing instructions, scripts, and resources that GitHub Copilot can automatically load when relevant to perform specialized tasks. They form an open standard working across multiple AI agents including GitHub Copilot in VS Code, CLI, and coding agent.

---

## Key Points

### 1. **What Are Agent Skills?**

- Folders of instructions, scripts, and resources that Copilot loads on-demand
- Open standard (agentskills.io) enabling portability across different AI tools
- Automatically activated based on your prompt—no manual selection needed

### 2. **Key Benefits**

- **Specialize Copilot**: Tailor capabilities for domain-specific tasks
- **Reduce repetition**: Create once, use automatically across all conversations
- **Compose capabilities**: Combine multiple skills to build complex workflows
- **Efficient loading**: Progressive disclosure—only relevant content loads into context

### 3. **Agent Skills vs Custom Instructions**

| Aspect          | Agent Skills                                        | Custom Instructions                    |
| --------------- | --------------------------------------------------- | -------------------------------------- |
| **Purpose**     | Teach specialized capabilities and workflows        | Define coding standards and guidelines |
| **Portability** | Works across VS Code, Copilot CLI, and coding agent | VS Code and GitHub.com only            |
| **Content**     | Instructions, scripts, examples, and resources      | Instructions only                      |
| **Scope**       | Task-specific, loaded on-demand                     | Always applied (or via glob patterns)  |
| **Standard**    | Open standard (agentskills.io)                      | VS Code-specific                       |

### 4. **When to Use Agent Skills**

- Create reusable capabilities across different AI tools
- Include scripts, examples, or resources alongside instructions
- Share capabilities with the wider AI community
- Define specialized workflows (testing, debugging, deployment)

### 5. **Skill Storage Locations**

- **Project skills**: `.github/skills/` (recommended) or `.claude/skills/` (legacy)
- **Personal skills**: `~/.copilot/skills/` (recommended) or `~/.claude/skills/` (legacy)

---

## Creating a Skill: Step-by-Step

### Directory Structure

```
.github/skills/
└── your-skill-name/
    ├── SKILL.md              (required)
    ├── script-template.js    (optional)
    ├── examples/             (optional)
    └── other-resources/      (optional)
```

### SKILL.md File Format

**Header (YAML Frontmatter - Required):**

```yaml
---
name: skill-name # Lowercase with hyphens (max 64 chars)
description: Brief description... # What and when to use (max 1024 chars)
---
```

**Body (Content):**

- Clear, specific instructions
- What the skill accomplishes
- When to use it
- Step-by-step procedures
- Examples of input and output
- References to included resources using relative paths: `[reference](./filename)`

### Example Structure

A testing skill might include:

- `SKILL.md` - Testing instructions
- `test-template.js` - Template test file
- `examples/` - Example test scenarios

---

## How Copilot Uses Skills: Three-Level Loading System

### Level 1: Skill Discovery

- Copilot reads `name` and `description` from YAML frontmatter
- Lightweight metadata determines skill relevance
- No context overhead

### Level 2: Instructions Loading

- When request matches skill description
- Full `SKILL.md` body loads into context
- Detailed instructions become available

### Level 3: Resource Access

- Copilot accesses scripts, examples, documentation as needed
- Resources don't load until referenced
- Keeps context efficient

**Result**: Install many skills with minimal context consumption—only what's needed loads.

---

## Using Shared Skills

### Finding Shared Skills

- Browse [github/awesome-copilot](https://github.com/github/awesome-copilot) repository
- Check [anthropics/skills](https://github.com/anthropics/skills) for reference skills

### Implementation Steps

1. Browse available skills in repository
2. Copy skill directory to your `.github/skills/` folder
3. Review and customize `SKILL.md` for your needs
4. Optionally modify or add resources

### Security Considerations

- Always review shared skills before using
- Ensure compliance with your standards
- VS Code terminal tool provides controls for script execution
- Configure auto-approve options with allow-lists

---

## Portability Across AI Agents

Agent Skills work with:

- **GitHub Copilot in VS Code**: Available in chat and agent mode
- **GitHub Copilot CLI**: Accessible in terminal
- **GitHub Copilot Coding Agent**: Used during automated coding tasks

Open standard enables skills to work across multiple AI ecosystems.

---

## Current Status & Enablement

- **Status**: Currently in preview
- **Enablement**: Set `chat.useAgentSkills` setting to use Agent Skills

---

## Related Resources

- [Customize AI responses overview](https://code.visualstudio.com/docs/copilot/customization/overview)
- [Create custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
- [Create reusable prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
- [Create custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
- [Agent Skills specification](https://agentskills.io/)
- [Reference skills repository](https://github.com/anthropics/skills)

---

## Quick Reference Checklist

When creating a skill, ensure you have:

- [ ] Unique, lowercase skill name with hyphens (max 64 chars)
- [ ] Clear description of capabilities and use cases (max 1024 chars)
- [ ] Comprehensive `SKILL.md` with header and body
- [ ] Step-by-step procedures and examples
- [ ] Optional: supporting scripts, templates, examples
- [ ] Optional: resource documentation with relative paths
- [ ] Placed in `.github/skills/` or `~/.copilot/skills/`
- [ ] Tested with `chat.useAgentSkills` enabled