develop-agent-skills_skill

Overview

This skill guides creators through designing, building, and improving Agent Skills: compact, reusable packages that extend an AI agent with workflows, code, references, and assets. It focuses on minimizing context bloat, choosing appropriate degrees of freedom, and organizing files so the agent loads only what it needs. Use it to create new skills or audit and improve existing ones.

How this skill works

The guide inspects skill structure, metadata, and resource choices and prescribes a progressive-disclosure layout: minimal frontmatter, concise SKILL.md body, and optional bundled scripts/references/assets loaded only when needed. It walks through a stepwise creation process—understand usage examples, plan reusable contents, initialize scaffolding, validate structure, and iterate against best practices. It also recommends when to move content out of SKILL.md into reference files or scripts for token efficiency and determinism.

When to use it

• Creating a new Agent Skill from scratch
• Auditing an existing skill for context efficiency and correctness
• Designing what scripts, references, or assets to bundle
• Converting verbose documentation into concise SKILL.md + references
• Preparing a skill for reliable, repeatable execution

Best practices

• Keep SKILL.md concise; frontmatter must include clear name and description
• Prefer scripts for repeated deterministic code and assets for output files
• Use references/ for domain docs; link them from SKILL.md with clear relative links
• Apply progressive disclosure: metadata always loaded, body only when triggered, resources on demand
• When unsure, restrict degrees of freedom—start strict and relax later

Example use cases

• Create a pdf-editor skill with scripts/rotate_pdf.py and references for advanced features
• Audit a bigquery-skill and move large schemas to references/schema.md with a TOC
• Design a frontend-template skill that stores boilerplate in assets/ and minimal usage notes in SKILL.md
• Improve an image-editing skill by replacing verbose procedural text with compact triggers and targeted reference files
• Validate skill structure with skillutil and iterate based on agent feedback