create-skill_skill

Overview

This skill guides you to design and build effective skills that extend an AI agent with domain knowledge, workflows, and tool integrations. It focuses on concise, progressive-disclosure design so skills remain lightweight, discoverable, and efficient. Follow these recommendations to create reusable scripts, references, and assets that produce reliable, repeatable behavior.

How this skill works

The skill inspects intended user workflows and maps them to three modular artifacts: compact metadata, a focused instruction file, and optional bundled resources (scripts, references, assets). It prescribes when to embed instructions directly and when to keep large or variant-specific content in references to save context. It also defines naming, placement, and freedom-level guidelines to match specificity to task fragility.

When to use it

• You want to create a new skill that automates a repeatable workflow or API integration.
• You need to update an existing skill to reduce context bloat or add scripts/references.
• You must convert frequently rewritten snippets into deterministic scripts.
• You are designing a skill that supports multiple variants, frameworks, or domains.
• You need a pattern for organizing large documentation without loading it by default.

Best practices

• Keep the in-context instruction short — include only what the agent absolutely needs.
• Use verb-first names (e.g., create-report, rotate-pdf) and prefer project-local placement by default.
• Apply progressive disclosure: metadata always in context, body loaded on trigger, resources loaded as needed.
• Choose freedom level based on fragility: high for heuristics, medium for configurable scripts, low for brittle sequences.
• Put large schemas or API specs in references and link them from the main instruction file.

Example use cases

• Create an edit-pdf skill with a reusable rotate script and a reference for OCR options.
• Build a query-bigquery skill that stores table schemas in references to avoid re-discovery.
• Package a deploy-app skill with an assets template for boilerplate and scripts for deterministic steps.
• Refactor an image-edit skill to move heavy examples into references and keep SKILL instructions minimal.
• Design a multi-framework cloud-deploy skill that loads provider-specific reference files only when chosen.