Agent Skills Template

A private, copy-and-go template for authoring agent skills. Skills follow the open Agent Skills standard (SKILL.md + YAML frontmatter), so they work with opencode, Claude Code, Codex, GitHub Copilot CLI, Cursor, and 30+ other agents with no per-agent work. This repo ships the structure, CI, and conventions so a repo made from it is production-ready on the first push.

This is a template repo, not a toolchain: validation and distribution are handled by the ecosystem (see spec/ for the full rationale).

What's inside

AGENTS.md                      # skill authoring conventions (read by coding agents)
skills/                        # skills live here, one directory each
├── hello-world/               # example: minimal, markdown only
└── typescript-lib-scaffolder/ # example: complex, with scripts/references/assets
.github/workflows/
├── validate.yml               # skill-validator on push + PR
└── release.yml                # final validation gate on tag push

Starting a new skills repo

1. Create the repo from this template (GitHub: Use this template).
2. Adapt it to your own repo — see AGENTS.md "Starting a new repo from this template". In short: replace spec/intent.md and spec/plan.md with your repo's intent and plan, update this README, and adjust AGENTS.md to your conventions.
3. Delete the example skills you don't want, then add your own under skills/ (one directory per skill, named after the skill).
4. Open a PR — validate.yml runs skill-validator and blocks on errors.
5. Ship by tagging: git tag v1.0.0 && git push origin v1.0.0. release.yml re-validates as a final gate. No build step, no artifacts.

Authoring rules live in AGENTS.md — read it before writing a skill.

Installing skills (consumer side)

Opencode (and most agents) discover skills from filesystem folders — there is no install command. Either point an installer at this repo, or copy the folder yourself:

# Open installer (npx skills from skills.sh) — all skills or one skill
npx skills add <owner>/<repo>
npx skills add <owner>/<repo> --skill hello-world

# Manual — drop the folder into any opencode discovery directory
git clone https://github.com/<owner>/<repo>.git ~/.agents/skills

Opencode watches these locations (as of opencode 1.x):

scope	paths
project	.opencode/skills/, .claude/skills/, .agents/skills/
global	~/.config/opencode/skills/, ~/.claude/skills/, ~/.agents/skills/

Local validation

The same check CI runs, without GitHub:

go run github.com/agent-ecosystem/skill-validator/cmd/skill-validator@latest check skills/

Security

Skills can bundle executable scripts; always review the scripts/ directory of any skill you install, and keep allowed-tools minimal (omit shell/bash unless you've audited every script). See AGENTS.md for the policy this template enforces.

License

MIT