// How to create, name, and structure agent skills for the repository.
| name | skill-creator |
| description | How to create, name, and structure agent skills for the repository. |
Skills are domain-specific instruction files that teach AI agents how to perform specialized tasks in the codebase. This skill documents how to create new skills correctly.
.agents/skills/<skill-name>/SKILL.md
Each skill is a single Markdown file in its own directory. The directory name is the skill identifier.
| Rule | Example |
|---|---|
| 2-4 words, descriptive | code-style, skill-creator |
| Verb prefix for action skills | write-e2e-test, prepare-pull-request |
Every SKILL.md has YAML frontmatter and compact Markdown content:
---
name: my-skill-name
description: One-sentence description of what this skill covers. Additionally, another one-sentence description when to use it ("Use when..." format).
---
# Skill Title
## Overview
Brief explanation of the domain (2-3 sentences max).
## Prerequisites
List tools/setup required. Cross-platform instructions (macOS + Windows).
## Workflow / Usage
The core content — how to do the thing.
## Related Skills
- [other-skill](../other-skill/SKILL.md) — short why
When requirements evolve, extend existing AGENTS/skills first:
AGENTS.mdSkills must work on macOS, Linux and Windows. Concrete rules:
| Avoid | Use Instead |
|---|---|
Bash scripts (.sh) | Node.js scripts (.mjs) |
sed, awk, grep in scripts | Node.js fs, readline, regex |
curl in automation scripts | fetch() (Node.js 22+) |
/usr/local/bin paths | Tool-specific commands via PATH |
Unix-specific env ($HOME) | process.env.HOME or os.homedir() |
Shell examples in SKILL.md may use bash syntax for readability (curl, pipes) since they're human-facing. Automation scripts must be .mjs files.
Every skill that requires external tools must document setup instructions. Use the project's established toolchain:
| Tool | Setup | Used For |
|---|---|---|
| Node.js | v22 LTS (see project-setup) | Frontend, scripts, tooling |
| Docker / OrbStack | Desktop install | Local services |
| MCP servers | JSON config in .vscode/mcp.json | Notion, Playwright, etc. |
When a skill references a tool not in this table, add a Prerequisites section explaining how to install and configure it.
If a skill uses an MCP server (e.g., Notion, Playwright), document the config:
{
"server-name": {
"type": "http",
"url": "https://mcp.example.com/mcp"
}
}
And describe authentication/setup steps.
If a skill involves sensitive operations (e.g., handling secrets, deploying to production), include a "Safety / workflow rules" section with guidelines to minimize risks.
If a skill requires tools, packages or MCP servers from external providers, ask the user for permission to continue, as they may be security risks. For example, if a skill requires installing a new npm package, or a cli tool, or connecting to a new MCP server, ask the user for explicit permission before proceeding! To make it easier for the user, please also provide a brief explanation of why the tool is needed and what it will be used for, so they can make an informed decision. Include who's the author of the tool, and if it's widely used and trusted in the industry. Check the tool's documentation and source code (if open source) to verify its security and privacy practices. Research who's the owner/maintainer, if it's actively maintained and under which license it's available.
Security is important, and we want to avoid introducing tools that require elevated permissions or have security implications without explicit approval. If and only IF the user gave you the permission, then proceed installing and describing external tools. If the user denies permission, do not proceed with the installation or connection, and suggest alternative approaches if possible.
After creating SKILL.md, ensure it is discoverable in the workspace skill inventory and has precise frontmatter (name, description) so agents can select it correctly.
Before committing a new skill:
name in frontmatter