Skip to main content

Creating Agent Skills

This guide covers how to create and manage Agent Skills in the AI Primitives Hub.

What is an Agent Skill?​

Agent Skills are reusable capabilities that can be added to AI agents in GitHub Copilot. Unlike prompts or instructions that provide context, skills enable agents to perform specialized tasks by defining:

  • A name and description
  • Allowed tools the skill can use
  • Supporting scripts and reference materials

Skill Structure​

A skill is organized in a directory with the following structure:

my-skill/
├── SKILL.md              # Main skill definition (required)
├── scripts/              # Utility scripts
│   └── example.py        # Script files
├── references/           # Reference materials
│   └── api-docs.md       # Documentation files
├── assets/               # Static assets
│   └── data.json         # Data files
└── README.md             # Documentation

SKILL.md Format​

The SKILL.md file is the core of a skill, containing YAML frontmatter and markdown content:

---
name: my-skill
description: A skill that does something useful
metadata:
  license: MIT
  version: 1.0.0
  author: Your Name
allowed-tools:
  - run_in_terminal
  - read_file
  - grep_search
---

# My Skill

Description of what this skill does and when to use it.

## Usage

Instructions for using this skill...

## Examples

Example interactions demonstrating the skill...

Required Frontmatter Fields​

FieldTypeDescription
namestringUnique identifier for the skill
descriptionstringShort description of the skill's purpose

Optional Frontmatter Fields​

FieldTypeDescription
metadata.licensestringLicense identifier (e.g., MIT, Apache-2.0)
metadata.versionstringSkill version (semver)
metadata.authorstringAuthor name or contact
allowed-toolsstring[]List of tools the skill can use

Creating a Skill with Scaffolding​

The easiest way to create a new skill is using the scaffold command:

  1. Open Command Palette (Ctrl+Shift+P)
  2. Run "AI Primitives Hub: Scaffold Project"
  3. Select "Agent Skill"
  4. Choose target directory
  5. Enter skill name and details

This creates a complete skill structure with example files.

Installing Skills​

User Scope​

Skills installed at user scope are available in all workspaces:

# Location: ~/.copilot/skills/
cp -r my-skill ~/.copilot/skills/

Workspace Scope​

Skills installed at workspace scope are only available in that workspace:

# Location: .copilot/skills/ in your project
cp -r my-skill .copilot/skills/

Using AI Primitives Hub​

Skills can be included in bundles and installed via the AI Primitives Hub extension. Add a skill to your collection manifest:

id: my-collection
name: My Collection
items:
  - path: skills/my-skill/SKILL.md
    kind: skill
    name: My Skill
    description: A useful skill

Allowed Tools​

Skills can restrict which tools they use via the allowed-tools field. Common tools include:

ToolDescription
run_in_terminalExecute shell commands
read_fileRead file contents
grep_searchSearch for patterns
semantic_searchSemantic code search
list_dirList directory contents
create_fileCreate new files
replace_string_in_fileEdit existing files

Best Practices​

  1. Single Responsibility: Each skill should focus on one specific capability
  2. Clear Documentation: Provide examples and usage instructions in the markdown content
  3. Tool Minimization: Only request the tools your skill actually needs
  4. Reusable Scripts: Place utility scripts in the scripts/ directory
  5. Reference Materials: Include relevant documentation in references/

Versioning & Updates​

  • AI Primitives Hub calculates the displayed version for GitHub/local skills from a content hash. Any change to files inside the skill directory (SKILL.md, scripts/, references/, assets/, etc.) produces a new hash so the Marketplace shows Update after sync.
  • The optional metadata.version field in SKILL.md is still useful for humans but is not the signal that drives update detection.
  • When developing locally, simply edit your files and run Sync Source—the installed entry refreshes automatically because local installs are symlinked to the source folder.

Examples​

Code Review Skill​

---
name: code-review
description: Reviews code for quality, security, and best practices
allowed-tools:
  - read_file
  - grep_search
  - semantic_search
---

# Code Review Skill

This skill performs comprehensive code reviews...

Test Generator Skill​

---
name: test-generator
description: Generates unit tests for code
allowed-tools:
  - read_file
  - create_file
  - run_in_terminal
---

# Test Generator Skill

This skill creates unit tests based on existing code...

See Also​