gmickel/better-skill-builder
Overview
This skill teaches developers how to build clean, discoverable agent skills that work across Claude Code, Codex, Amp, and OpenCode. It documents a minimal project layout, file frontmatter patterns, and production-ready distribution and CLI patterns. The focus is on practical, repeatable patterns used in real projects like gno, sheets-cli, and raindrop.
How this skill works
The skill inspects and generates a compact skill description file with required frontmatter, recommended folder layout for references and scripts, and example scripts for CLI integration. It provides templates and checklists for triggers, quick reference commands, detailed docs, and distribution strategies so agents can detect activation phrases and surface usage. It also maps to official specification details for client integration.
When to use it
- You need a consistent skill file that agents can parse to discover capabilities and triggers
- You want to make CLI tools AI-native with clear trigger phrases and invocation patterns
- You are packaging skills for multiple agent platforms (Claude Code, Codex, Amp, OpenCode)
- You need production patterns for distribution, installation paths, and plugin structure
- You want examples and reference patterns from existing, proven projects
Best practices
- Keep the main skill description file short and focused; include trigger phrases up front
- Provide a Quick Reference section with one-line commands and common options
- Organize detailed docs under a references folder and keep executable helpers in a scripts folder
- Include installation and distribution notes for git, CLI, and plugin marketplaces
- Design triggers conservatively to avoid accidental activation and document safety/auth patterns
Example use cases
- Turn an existing CLI tool into an AI-discoverable skill with trigger phrases and examples
- Package a set of automation scripts with clear quick-reference commands for agents
- Create a multi-platform skill that works identically for Claude Code and OpenCode clients
- Publish a skill with plugin-style metadata for a marketplace or installer
- Add safety, auth, and scope sections so agents can surface appropriate usage constraints
FAQ
Include a short skill description file with frontmatter, a references folder for detailed docs, and a scripts folder for executable helpers.
How do agents know when to activate the skill?
Declare clear trigger phrases in the description frontmatter and list common invocation patterns in a When to Use or Quick Reference section.
