cyberuni Create Skill
When the user asks to create a new skill, follow this convention.
Skill placement
Pick the placement before scaffolding:
| Placement | Location | Notes |
|---|---|---|
| User | ~/.agents/skills/<name>/ |
Personal skills across all projects |
| Project private | .agents/skills/<name>/ |
Contributor tooling; add metadata: internal: true |
| Project public | skills/<name>/ |
Shipped with a package; users install via npx skills add |
Skill patterns
Capture the workflow shape separately from placement:
| Pattern | When to use it |
|---|---|
| Process | Ordered multi-step workflow with decision points |
| Tool-based | Consistent use of tools, systems, or connectors |
| Standard | Tone, format, structure, or quality enforcement |
Ask the user if the placement or pattern 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 placement (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/).
Skill design governance
Before writing content, load the skill-design governance:
npx cyber-skills@<version> governance show skill-design
Read stdout as the authoritative rules for principles, progressive disclosure, description structure, and when to extract deterministic logic to scripts or existing project CLIs.
Scripts and CLI output
If the skill includes a scripts/ directory or documents CLI commands agents run, also load agent-tool-output:
npx cyber-skills@<version> governance show agent-tool-output
Read stdout as the authoritative rules for stdout, JSON, non-interactive paths, and stderr.
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
descriptionfrontmatter 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.