Guide for creating effective skills that extend agent capabilities with specialized knowledge, workflows, or tool integrations. Use this skill when the user asks to: create a skill, make a skill, build a skill, set up a skill, initialize a skill, scaffold a skill, update or modify an existing skill, validate a skill, learn about skill structure, understand how skills work, or get guidance on skill design patterns.
This skill provides guidance for creating effective skills.
Skills are modular, self-contained packages that extend agent capabilities by providing specialized knowledge, workflows, and tools. 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 and domain expertise.
In deepagents CLI, skills are stored in ~/.deepagents/<agent>/skills/ where <agent> is your agent configuration name (default is agent). For example, with the default configuration, skills live at:
~/.deepagents/agent/skills/
├── skill-name-1/
│ └── SKILL.md
├── skill-name-2/
│ └── SKILL.md
└── ...
The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
Default assumption: The agent is already very capable. Only add context the agent doesn't already have.
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ └── description: (required)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (TypeScript/JavaScript/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
Skill creation involves these steps:
When creating a new skill from scratch, run the init_skill.ts script:
npx tsx scripts/init_skill.ts <skill-name> --path <output-directory>
For deepagents, use the agent's skills directory:
npx tsx scripts/init_skill.ts <skill-name> --path ~/.deepagents/agent/skills
Once development of the skill is complete, validate it:
npx tsx scripts/quick_validate.ts <path/to/skill-folder>
The validation script checks:
name and description