agentdev-skill-authoring

Provides quality criteria and review protocols for authoring OpenCode SKILL.md files.

Updated Mar 7, 2026
One-click install
npx skills add https://github.com/yogata/agent-dev-flow --skill agentdev-skill-authoring-yogata
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agentdev-skill-authoring
Source: https://github.com/yogata/agent-dev-flow/tree/main/src/opencode/skills/agentdev-skill-authoring
Command: npx skills add https://github.com/yogata/agent-dev-flow --skill agentdev-skill-authoring-yogata

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing high-quality SKILL.md files for OpenCode agents requires consistent structure, precise trigger descriptions, token budget discipline, and progressive disclosure, which is hard to maintain without explicit standards and review checklists. ## Core Features & Use Cases - Design Principles: Enforces conciseness, token budgets (under 5,000 tokens), line-count governance (500-line extraction threshold), naming conventions, and third-person descriptions with mandatory USE FOR / DO NOT USE FOR triggers. - Quality Evaluation & Review Protocols: Applies five evaluation axes (clarity, completeness, trigger accuracy, scope, anti-pattern detection) and four check protocols covering frontmatter, budget, structure, and advisory checks. - Placement & Workflow Guidance: Provides a placement decision flow (Skill vs Script vs Template vs Design/Decision/Guide) and an iterative development workflow with anti-pattern catalogs. - Use Case: When creating a new OpenCode skill or improving an existing one, use this Skill to classify complexity (simple/moderate/detailed), structure references/ for progressive disclosure, and validate the result against the review protocol before publishing. ## Quick Start Review my SKILL.md file against the skill authoring quality criteria and fix any violations of the frontmatter, trigger, and structure rules.

Frequently Asked Questions about agentdev-skill-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a good SKILL.md description for OpenCode?▼

Write the description in third person and include mandatory USE FOR and DO NOT USE FOR triggers listing concrete application and exclusion scenarios. Keep 3 to 7 triggers, and limit frontmatter to only the name and description fields.

What is the recommended structure for an OpenCode skill?▼

Classify complexity first: simple skills stay under 200 lines in SKILL.md alone, moderate skills add 1-2 reference files, and detailed skills use a references directory. Keep reference depth to one level and add a table of contents to reference files over 100 lines.

When should I split SKILL.md content into references files?▼

Extraction becomes mandatory when SKILL.md exceeds 500 lines, and should be considered above 400 lines. Move detailed procedures, decision tables, and examples into references while keeping SKILL.md as an overview and navigation entry point.

Why does my OpenCode skill name fail to resolve?▼

A common cause is wrapping the frontmatter name value in backticks, which makes the YAML parser treat the backticks as part of the name. Write name as a plain YAML scalar matching the directory name, reserving backticks for Markdown body mentions.

What are the limitations of this skill authoring guidance?▼

It covers only Skill quality criteria and does not define command definitions or the command-skill boundary, which lives in the artifact-contracts design document. It also excludes general coding tasks and simple documentation fixes from its scope.