| name | new-skill |
| description | Creates a new agent skill in the SKILL.md format (open standard — Claude Code, Codex, Antigravity, agents.md), in the project or in the dotfiles global collection |
| argument-hint | ["skill-name"] |
| allowed-tools | Read, Write, Bash, Glob |
| user-invocable | true |
| disable-model-invocation | true |
Create New Skill
A skill is a folder with a SKILL.md (+ optional assets), in the open
format supported by Claude Code, Codex, Antigravity and the agents.md
standard.
Where to create it
| Scope | Location |
|---|
| Project | .agents/skills/<name>/SKILL.md (with .claude/skills symlink → ../.agents/skills) |
| Personal template | ~/Projects/dotfiles/agents/skills/project/templates/<name>/SKILL.template.md — inert until /project-new///project-update copy it into a project as SKILL.md |
| Global (personal) | ~/Projects/dotfiles/agents/skills/<name>/, then ./dotfiles apply:agents |
Global is only for meta-skills that operate on projects (project,
project-new, project-update, project-doctor, new-skill). Code/stack
conventions become a template; domain rules become a project skill.
Precedence: a project skill wins over a global one of the same name.
Template
---
name: kebab-case-name
description: What it does and WHEN to use it ("Use when...") — this is how the model decides to activate it
allowed-tools: Read, Grep # only the tools the skill needs
---
# Title
Direct instructions, in the imperative, with paste-ready examples.
Optional frontmatter:
argument-hint: [arg] — argument hint for manual invocation.user-invocable: true — becomes a /name command.disable-model-invocation: true — only the user invokes it (for action
skills: commit, scaffold, deploy…).
Best practices
- The description decides everything: say what it does and when to
use it; if it over-activates, add "Do not use for…".
- Short and dense: the whole SKILL.md enters the context — 50–350
lines. Long material goes to
references/*.md (linked, loaded on
demand) and scripts to scripts/.
- Real examples: code that compiles/runs, extracted from real use,
not pseudocode.
- One responsibility per skill; a family of skills > an encyclopedia
skill.
- Language: personal collection skills (dotfiles) in English; project
skills follow the project's language.
- Third-party vendored skill: keep the
LICENSE.* and an UPSTREAM.md
with the source repo/commit and how to update.
Final checklist
