helderberto/write-a-skill
skills/write-a-skill/SKILL.md
Create new agent skills with proper structure and progressive disclosure. Use when user wants to create, write, or build a new skill, or asks "make a skill for X".
$ install --global
skillsauthnpx skillsauth add helderberto/skills write-a-skillInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 30, 2026, 2:40 AM9.0s1 file scanned
SKILL.md
- name:
- write-a-skill
- description:
- Create new agent skills with proper structure and progressive disclosure. Use when user wants to create, write, or build a new skill, or asks "make a skill for X".
Write a Skill
Process
- Clarify scope -- ask the user (use AskUserQuestion when available; otherwise present as numbered options):
- "What type of skill?" — Options: "Pure instructions (no scripts)", "Instructions + helper scripts", "Wrapper around CLI tool"
- "Does it need pre-loaded context?" — Options: "Yes — auto-run commands on load (Recommended)", "No — gather context during workflow"
- Explore existing skills --
lsthe skills repo, read similar skills for conventions - Draft -- create
SKILL.md - Review with user -- confirm coverage, ask what's missing
Structure
skill-name/
├── SKILL.md # Required. All instructions live here.
└── scripts/ # Optional. Executable helpers only.
└── scan-secrets.sh
Keep everything in SKILL.md. Only use scripts/ for executable files (.sh, .py) that are called via Bash.
SKILL.md Template
---
name: skill-name
description: One sentence what it does. Use when [triggers]. Don't use when [anti-triggers].
---
# Skill Name
## Workflow
[numbered steps]
## Rules
[hard constraints]
## Error Handling
[if X -- do Y]
Frontmatter Fields
| Field | Required | Notes |
|---|---|---|
| name | yes | kebab-case, matches directory |
| description | yes | Agent's only signal for when to load this skill |
Description Rules
The description is the only thing the agent sees when choosing which skill to load.
- Max 1024 chars
- First sentence: what it does
- Second sentence:
Use when [triggers] - Third sentence (optional):
Don't use when [anti-triggers]
Good: Groups unstaged changes into atomic commits by concern. Use when user says "atomic commits" or wants to split changes before pushing.
Bad: Helps with commits.
Examples
Minimal skill -- pure instructions, fits in ~20 lines:
---
name: grill-me
description: Interview the user relentlessly about a plan. Use when user says "grill me".
---
[instructions...]
Pre-loaded context -- ! prefix auto-runs commands on load:
## Pre-loaded context
- Status: !`git status`
- Diff: !`git diff HEAD`
Avoids wasting a turn fetching context the agent always needs.
Rules
- No time-sensitive info (versions, dates) in skills
- Include error handling for foreseeable failure modes
- Test the skill by invoking it before shipping
Anti-patterns
- Description without triggers:
"Helps with testing."-- useless - Hardcoded versions or dates that go stale
- No error handling for skills that run Bash commands
Related Skills
helderberto/caveman
testing
VerifiedTrustedCommunity
Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
10SKILL.mdUpdated May 12, 2026
helderberto/handoff
documentation
VerifiedTrustedCommunity
Compact the current conversation into a handoff doc so a fresh agent can continue the work. Use when user asks to "handoff", "/handoff", "hand this off", or wants to end a session mid-task. Don't use for summarising completed work, writing PRDs/plans/ADRs, or committing changes.
8SKILL.mdUpdated May 20, 2026
helderberto/create-skill
development
VerifiedTrustedCommunity
Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill, or asks "make a skill for X".
8SKILL.mdUpdated May 20, 2026
helderberto/zoom-out
development
VerifiedTrustedCommunity
Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
8SKILL.mdUpdated May 12, 2026