| name | create-skill |
| description | Use this skill when the user asks to create a new agent skill — scaffold, audit, and link into detected agents. |
Create Skill
When the user asks to create a new skill, follow this convention.
Skill kinds
Pick the location from scope before scaffolding:
| Kind | Location | Notes |
|---|
| Global | ~/.agents/skills/<name>/ | Personal skills across all projects |
| Repo internal | .agents/skills/<name>/ | Contributor tooling; add metadata: internal: true |
| Repo public | skills/<name>/ | Shipped with a package; users install via npx skills add |
Ask the user if the kind is ambiguous.
Directory structure
Global skills live in ~/.agents/skills/<name>/ and are linked into each agent's skills directory:
~/.agents/skills/
<name>/
SKILL.md ← source of truth, edit this
~/.claude/skills/
<name> ← symlink → ~/.agents/skills/<name> (Claude Code)
# ...and equivalent paths for other detected agents
Steps
1. Create the skill
Determine the skill kind (above), then create the directory at the matching path.
Check whether npx skills is available:
npx skills --version 2>/dev/null
If available, use it to scaffold the skill:
npx skills init <name> --dir ~/.agents/skills
This creates ~/.agents/skills/<name>/SKILL.md with a starter template. Edit that file to fill in the real content.
If not available, create manually:
mkdir -p ~/.agents/skills/<name>
Then write ~/.agents/skills/<name>/SKILL.md using this template:
---
name: <name>
description: Use this skill when <trigger condition>. <One-line summary of what it does.>
---
# <Name>
## When to use
<Describe when this skill should be used.>
## Instructions
1. First step
2. Second step
2. Audit the skill
Run automated checks first:
npx cyber-skills@<version> audit validate --path ~/.agents/skills/<name>
Fix any CRITICAL findings before proceeding.
Then invoke the audit-skill agent skill for full review (Q6–Q12, E3–E8, P1–P3). Do not continue to step 3 if any CRITICAL findings remain.
3. Link to agents
If npx skills is available:
npx skills add ~/.agents/skills/<name>
This detects all installed agents and prompts the user to choose which ones to link. It handles the correct path for each agent (Claude Code, Cursor, Codex, OpenCode, etc.).
Known issue: npx skills has a bug where it may not create ~/.claude/skills/ if the directory doesn't exist yet. After linking, verify:
ls ~/.claude/skills/<name>
If missing, fall back to the manual step below.
If npx skills is not available, or the symlink is missing after the above:
ln -sf ~/.agents/skills/<name> ~/.claude/skills/<name>
Adjust the target path for other agents as needed (e.g., ~/.cursor/skills/, ~/.opencode/skills/).
What makes a good skill
- Decisions over documentation. Encode what to decide and how — don't repeat reference material the model already knows.
- Narrow and composable. One workflow per skill. Skills can be triggered by situation (user-facing) or called by other skills (sub-skills). Sub-skills have no situational trigger — their
description should say "Internal skill: called by X" to avoid accidental activation. Neither type should be loaded as ambient context.
- No baked-in opinions. Detect the user's setup (package manager, monorepo shape, tooling) at runtime rather than assuming a specific stack.
Scripts and CLI output
If the skill includes a scripts/ directory or documents CLI commands agents run, load the output discipline before authoring or reviewing executable tooling:
npx cyber-skills@<version> discipline show agent-tool-output
Read stdout as the authoritative rules. Prefer npx cyber-skills@<version> … CLI subcommands over new bundled scripts/.
Notes
~/.agents/skills/ is the source of truth — commit or back up this directory.- Agent skills directories (e.g.
~/.claude/skills/) only contain symlinks; never edit files there directly.
- The
description frontmatter field is what agents read to decide when to activate the skill — make it specific and include "Use this skill when" trigger language. For sub-skills, prefix with "Internal skill:" to prevent unintended activation.
