kjanat/build-skill
skills/build-skill/SKILL.md
Create effective skills for OpenCode agents. 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 18, 2026
$ install --global
skillsauthnpx skillsauth add kjanat/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 18, 2026, 7:22 AM19.0s12 files scanned
SKILL.md
- name:
- build-skill
- description:
- Create effective skills for OpenCode agents. Load FIRST before writing any SKILL.md. Provides required format, naming conventions, progressive disclosure patterns, and validation. Use when building, reviewing, or debugging skills.
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 .opencode/skills/ (project) or ~/.config/opencode/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
- 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
| 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 | | Review/validate skill | review-checklist.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 | | review-checklist.md | Post-creation review + dispatch |
Scripts
| Script | Purpose |
| --------------------------- | ------------------------ |
| scripts/init_skill.sh | Scaffold new skill |
| scripts/validate_skill.sh | Validate skill structure |
| scripts/package_skill.sh | Create distributable zip |
Post-Creation Review
After creating or significantly modifying a skill, dispatch a reviewer agent (oracle or code-reviewer) to cross-validate against the best practices checklist. See review-checklist.md for the full checklist and prompt template.
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
-
[ ] Validate the skill using skills-ref:
uvx 'git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref' \ validate <SKILL_DIR> # Validate a skill skills-ref validate path/to/skill # Read skill properties (outputs JSON) skills-ref read-properties path/to/skill # Generate <available_skills> XML for agent prompts skills-ref to-prompt path/to/skill-a path/to/skill-b
Skill Locations
| Priority | Location |
| -------- | ------------------------------------------------------------------------ |
| 1 | .opencode/skills/<name>/ (project) |
| 2 | ~/.config/opencode/skills/<name>/ (global) |
| 3 | .claude/skills/<name>/ (Claude-compat) |
| 4 | $(git rev-parse --show-toplevel)/skills (shared) |
Discovery walks up from CWD to git root. First-wins for duplicate names.
See Also
- Cloudflare Skill - Reference implementation
Related Skills
kjanat/statute-proxy
development
VerifiedTrustedCommunity
Use this skill whenever the user is designing, building, scaffolding, reviewing, or debugging Go-based reverse proxy or HTTP edge infrastructure, especially when they mention statute, config-as-code proxies, building an nginx replacement in Go, networking topology, TLS termination, load balancing, HTTP/2, HTTP/3, QUIC, ACME, upstream pools, middleware chains, or graceful shutdown. Trigger this skill even when the user does not explicitly name statute but is clearly working on a Go HTTP server, edge proxy, or networking infrastructure problem where the resulting artefact will be a compiled binary rather than a runtime-configured server. Also trigger when the user asks for explanations of networking protocols (HTTP/1.1, HTTP/2, HTTP/3, WebSockets, gRPC, TLS) in the context of building or operating a proxy, or when they ask about Go net/http pitfalls, transport tuning, or production-grade server defaults.
SKILL.mdUpdated May 8, 2026
kjanat/threlte
development
VerifiedTrustedCommunity
Routes Threlte questions to exact, commit-pinned docs paths and practical workflows. Use when helping with setup, debugging, or architecture across @threlte/core, @threlte/extras, @threlte/gltf, @threlte/rapier, @threlte/theatre, @threlte/xr, @threlte/flex, and @threlte/studio.
SKILL.mdUpdated Apr 18, 2026
kjanat/lightning
testing
VerifiedTrustedCommunity
Comprehensive lightning physics knowledge base derived from Rakov & Uman (2003) "Lightning: Physics and Effects". Covers discharge types, current parameters, leader/return-stroke physics, cloud electrification, protection, detection systems, atmospheric effects, and quantitative reference data. Use when answering questions about lightning physics, electromagnetic fields, thunderstorm electricity, lightning protection, or atmospheric electrical phenomena.
SKILL.mdUpdated Apr 18, 2026
kjanat/index-knowledge
development
VerifiedTrustedCommunity
Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
SKILL.mdUpdated Apr 18, 2026