create-skill

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.