Promotion

Keep stack packs as learn content by default. Promote a pack into a live agent skill only when repeated use proves that automatic routing and focused instructions will improve real work.

Promotion Criteria

Do not create .agents/skills/<stack>/SKILL.md until all criteria pass:

Criterion	Required evidence
Repeated use	Pack guided at least three real app or prototype tasks
Stable source map	`docs-index.md` has official docs, samples, versions, and raw recovery paths
Command proof	Required local gates in `commands.md` and `quality-gates.md` are verified
Pitfall coverage	Known recurring traps are recorded with detection and fixes
Agent value	Agents using the pack avoid mistakes they made without it
Eval seed	Two or three realistic prompts exist for regression testing
Safety review	No unreviewed scripts, hidden instructions, or broad tool grants are bundled

Skill Shape

If promotion is justified, keep SKILL.md short and point to the learn pack for details.

---
name: [stack-slug]
description: Use this when building, reviewing, testing, packaging, or releasing apps with [stack]. Loads the Research Lab stack capability pack, verifies docs and commands, applies quality gates, and prevents unsafe release claims.
---

# [Stack] Capability Pack

Read `learn/stacks/[stack-slug]/README.md` first.

Follow these in order:

1. Check `docs-index.md` for official sources and freshness.
2. Use `decision-guide.md` before recommending the stack.
3. Use `commands.md` and `quality-gates.md` before claiming done.
4. Apply `pitfalls.md` and `agent-guardrails.md` during implementation and review.
5. Stop before package, signing, release, install, or store work unless the user approves missing gates.

Frontmatter Rules

Field	Rule
`name`	Lowercase letters, numbers, and hyphens; match the skill directory
`description`	Include what the skill does and when to use it
`license`	Optional, only when distributing outside the repo
`compatibility`	Optional, use only for real environment requirements
`metadata`	Optional string-to-string map
`allowed-tools`	Avoid by default; never pre-approve shell for unreviewed scripts

Preview And Validation

Before installing or sharing a promoted skill:

gh skill preview OWNER/REPOSITORY SKILL
gh skill publish --dry-run

For OpenCode in this workspace, a project-local skill can live at:

.agents/skills/<stack>/SKILL.md

OpenCode also discovers compatible skill roots under .opencode/skills/, .claude/skills/, .agents/skills/, and matching global folders.

Distribution Choice

Shape	Use when
Learn pack only	The stack is still being researched or used occasionally
Repo-local skill	The stack is important to one repo or app family
User-global skill	The user repeatedly builds this stack across repos
Plugin or capability bundle	Multiple skills, hooks, MCP servers, custom agents, or LSP settings ship together