sanurb/build-skill
build-skill/SKILL.md
Creates new AI agent skills following the Agent Skills spec. Load FIRST before writing any SKILL.md. Provides required format, naming conventions, progressive disclosure patterns, and validation. Use when building, reviewing, or debugging skills.
development
Updated Apr 26, 2026
$ install --global
skillsauthnpx skillsauth add sanurb/skills build-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 26, 2026, 9:11 AM221.4s10 files scanned
SKILL.md
- name:
- build-skill
- description:
- Creates new AI agent skills following the Agent Skills spec. Load FIRST before writing any SKILL.md. Provides required format, naming conventions, progressive disclosure patterns, and validation. Use when building, reviewing, or debugging skills.
- allowed-tools:
- Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
Building Skills
Skills extend agent capabilities with specialized knowledge, workflows, and tools.
Quick Start
Minimal viable skill in 30 seconds:
mkdir my-skill && cat > my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does X when Y happens. Use for Z tasks.
---
# My Skill
Instructions go here.
EOF
Place in .agents/skills/ (project) or ~/.agents/skills/ (global).
Skill Type Decision Tree
What are you building?
├─ Instructions only → Simple skill (SKILL.md only)
│ Example: code-review guidelines, commit message format
│
├─ Domain knowledge → Reference-heavy skill (+ references/)
│ Example: API docs, database schemas, company policies
│
├─ Repeatable automation → Script-heavy skill (+ scripts/)
│ Example: PDF processing, data validation, file conversion
│
├─ Complex multi-step workflow → Multi-file skill (all directories)
│ Example: release process, deployment pipeline
│
└─ Large platform → Progressive skill
Example: AWS, GCP, Cloudflare (60+ products)
When to Create a Skill
Create a skill when:
- Same instructions repeated across conversations
- Project-specific conventions differ from generic best practices
- Domain knowledge model lacks (schemas, internal APIs, company policies)
- Workflow requires 3+ steps with specific order
- Code rewritten repeatedly for same task
- Team needs shared procedural knowledge
When NOT to Create a Skill
- Documentation already exists (create a reference instead)
- Pattern is trivial or self-explanatory
- It's a one-off task
| Scenario | Do Instead | |----------|------------| | Single-use instructions | AGENTS.md or inline in conversation | | Model already knows domain | Don't add redundant context | | < 3 steps, no reuse | Inline instructions | | Highly variable workflow | Higher-freedom guidelines | | Just want to store files | Use regular directories |
Reading Order
| Task | Files to Read | |------|---------------| | New skill from scratch | anatomy.md → frontmatter.md | | Optimize existing skill | progressive-disclosure.md | | Add scripts/resources | bundled-resources.md | | Find skill pattern | patterns.md | | Debug/fix skill | gotchas.md |
In This Reference
| File | Purpose | |------|---------| | anatomy.md | Skill directory structures | | frontmatter.md | YAML spec, naming, validation | | progressive-disclosure.md | Token-efficient design | | bundled-resources.md | scripts/, references/, assets/ | | patterns.md | Real-world skill patterns | | gotchas.md | Common mistakes + fixes |
Scripts
| Script | Purpose |
|--------|---------|
| scripts/init_skill.sh | Scaffold new skill |
| scripts/validate_skill.sh | Validate skill structure |
| scripts/package_skill.sh | Create distributable zip |
Pre-Flight Checklist
Before using a skill:
- [ ] SKILL.md starts with
---(line 1, no blank lines) - [ ]
name:field present, matches directory name - [ ]
description:includes what + when to use - [ ] Closing
---after frontmatter - [ ] SKILL.md under 200 lines (use references/ for more)
- [ ] All internal links resolve
Run: ./scripts/validate_skill.sh ./my-skill
Skill Locations
| Priority | Location |
|----------|----------|
| 1 | .opencode/skills/<name>/ (project) |
| 2 | ~/.config/opencode/skills/<name>/ (global) |
| 3 | .claude/skills/<name>/ (Claude-compat) |
Discovery walks up from CWD to git root. First-wins for duplicate names.
See Also
- Cloudflare Skill - Reference implementation
Related Skills
sanurb/setup-sanurb-skills
development
VerifiedTrustedCommunity
Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub, GitLab, fp, or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `fp-plan`, `fp-implement`, `fp-review`, `to-issues`, `to-prd`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out` — or if those skills appear to be missing context about the issue tracker, triage labels, or domain docs.
SKILL.mdUpdated Jun 4, 2026
sanurb/prototype
development
VerifiedTrustedCommunity
Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
SKILL.mdUpdated Jun 4, 2026
sanurb/herdr
tools
VerifiedTrustedCommunity
Control herdr (a terminal-native agent multiplexer) from inside it. Manage workspaces and tabs, split panes, spawn sibling agents, read pane output, and wait for state changes — all via CLI commands that talk to the running herdr instance over a local unix socket. Use when running inside herdr (HERDR_ENV=1). Do not use outside herdr.
SKILL.mdUpdated Jun 4, 2026
sanurb/handoff
documentation
VerifiedTrustedCommunity
Compact the current conversation into a handoff document for another agent to pick up.
SKILL.mdUpdated Jun 4, 2026