| name | add-project-skill |
| description | Create a new project-specific agent skill and install it in both .agents/skills/ (VS Code Copilot) and .claude/skills/ (Claude Code CLI), following the skills.sh dual-install pattern. Use when adding custom rules, domain knowledge, or reusable workflows for all agents in the project. Triggers: "create skill", "add skill", "new skill for all agents", "project-specific rules", "add agent rules". |
| argument-hint | Skill name and purpose, e.g. "api-conventions — rules for the Fastify API layer" |
Add Project Skill
Creates a project-specific SKILL.md installed to both agent runtimes in use:
| Path | Runtime |
|---|
.agents/skills/<name>/SKILL.md | VS Code Copilot |
.claude/skills/<name>/SKILL.md | Claude Code CLI |
This mirrors the skills.sh / npx skills dual-install pattern — the same skill file works across all agents with no extra configuration.
When to Use
- Capturing codebase conventions or domain knowledge as a reusable workflow
- Adding project-specific rules that every agent (VS Code + Claude) should follow
- Packaging a multi-step procedure (e.g. "how to add a new API route") as an on-demand skill
- After a long conversation reveals a repeatable pattern worth preserving
Procedure
1. Determine Skill Identity
Collect from the user or infer from context:
- Name — lowercase, hyphenated, 1–64 chars (e.g.
api-conventions, db-migrations, add-route)
- Purpose — one sentence: what task does it accomplish?
- Triggers — keywords a future agent would use to discover it (embed in
description)
2. Draft the SKILL.md
Use this template:
---
name: <skill-name>
description: '<What it does. When to use. Trigger keywords. Max 1024 chars.>'
argument-hint: '<Optional hint for /skill-name invocations>'
---
# <Skill Title>
## When to Use
- <trigger 1>
- <trigger 2>
## Procedure
1. <step>
2. <step>
## References
- [<title>](./<path>)
YAML frontmatter rules (silent failures if violated):
name must match the parent folder name exactly- Quote values that contain
: or #
- Use spaces, never tabs
- Keep
description keyword-rich — it is the sole discovery surface
3. Install to Both Platforms
Create the file in both locations with identical content:
.agents/skills/<name>/SKILL.md ← VS Code Copilot
.claude/skills/<name>/SKILL.md ← Claude Code CLI
Do not add local skills to skills-lock.json. That file tracks externally sourced skills
fetched from GitHub via npx skills. Local skills are managed directly.
4. Validate
5. Register in Copilot Instructions (optional but recommended)
If the skill is frequently used, add a row to the skills table in .github/copilot-instructions.md:
| `<name>` | <When to use — one line> |
This ensures VS Code Copilot loads the skill proactively without waiting for description-match discovery.
Example
Goal: Add a skill for Fastify API route conventions.
Skill name : api-conventions
Folder : .agents/skills/api-conventions/
.claude/skills/api-conventions/
Description: 'Fastify API conventions for the Stetsom backend. Use when writing
route handlers, validating schemas with Zod, or structuring Prisma queries.'
After creation, invoke it with:
/api-conventions add POST /products route
Notes on skills.sh / npx skills
npx skills downloads skills from GitHub into both .agents/skills/ and .claude/skills/ and writes a hash to skills-lock.json. This skill replicates that dual-install pattern for locally authored skills — no external source required.
