Guide for creating new Skill for an AI Assistant/Agent. Use when creating new skills, updating existing skills, or contributing learnings back to the repository. Use when asked to "create a skill", "make a new skill", "scaffold a skill", or when building specialized AI capabilities with bundled resources. Generates SKILL.md files with proper frontmatter, directory structure, and optional scripts/references/assets folders.
A meta-skill for creating, refining, and maintaining other Agent Skills (SKILL.md files). Use this skill when you need to scaffold new skills, review existing ones, generate unified templates, or improve skill structure and effectiveness.
Skills are modular packages that extend agent capabilities with specialized knowledge and workflows. Think of them as "onboarding guides" for specific domains or tasks—they transform a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.
The context window is a public good. Skills share the context window with everything else the AI Assistant needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
Default assumption: AI Assistant is already very smart. Only add context the AI Assistant doesn't already have. Challenge each piece of information: "Does the AI Assistant really need this explanation?" and "Does this paragraph justify its token cost?"
Prefer concise examples over verbose explanations.
Match the level of specificity to the task's fragility and variability:
High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
Think of the AI Assistant as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required) # Frontmatter (name, description) + instructions
├── references/ # Documentation loaded into context as needed
└── assets/ # Files used in output (templates, etc.)
Every SKILL.md consists of:
name and description fields (required), plus optional fields like license, metadata, and compatibility. Only name and description are read by the AI Assistant to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used. The compatibility field is for noting environment requirements (target product, system packages, etc.) but most skills don't need it.references/)Documentation and reference material intended to be loaded as needed into context to inform the AI Assistant's process and thinking.
references/finance.md for financial schemas, references/mnda.md for company NDA template, references/policies.md for company policies, references/api_docs.md for API specificationsassets/)Files not intended to be loaded into context, but rather used within the output Claude produces.
assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate, assets/font.ttf for typographyA skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
Skills use a three-level loading system to manage context efficiently:
Keep SKILL.md lean (<5k words). Move detailed content to references/:
Skill creation involves these steps:
Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
To turn concrete examples into an effective skill, analyze each example by:
Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
assets/hello-world/ template containing the boilerplate HTML/React project files would be helpful to store in the skillExample: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:
references/schema.md file documenting the table schemas would be helpful to store in the skillTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ ├── description: (required)
│ │ └── compatibility: (optional, rarely needed)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
---