How to Create Good Agent Skills | Claude Code Guide

I explain how to create good agent skills for Claude, focusing on reusable, modular capabilities that extend Claude's functionality. It is ideal for developers building AI workflows who want to avoid common mistakes like overloading the context window or repeating prompts.

I share my exact framework for building skills that are concise, efficient, and practical. I also demonstrates how to use the official skill creator tool and best practices for skill design, testing, and distribution.

What's inside

• Why most developers create agent skills incorrectly
• Key principles for designing effective agent skills
• Using AI to generate and refine skills with the skill creator
• Creating a deployment skill example from package.json scripts
• Best practices for concise skill metadata and instructions
• Managing context window size and token costs
• Organizing skills with references and folder structure
• Distributing skills to teams or the community

Why most developers create agent skills incorrectly

Many developers misuse agent skills by overexplaining or including too much context that Claude already knows. This bloats the context window, making skills slow and expensive to run. I emphasize that skills should avoid repeating information the model already understands.

Instead, skills should focus on reusable tasks you find yourself repeating often, like adding a footer to emails or running deployment scripts. By modularizing these tasks into skills, you avoid redundant prompting and improve efficiency.

Key principles for designing effective agent skills

Skills are modular capabilities with a title, description, and instructions that Claude or any agent uses to decide if the skill fits the current conversation context. They should be concise and focused on repetitive tasks you want to automate.

I recommend keeping skill metadata short - using bullet points or one-liners - to minimize token consumption. Skills should not be used for one-off tasks or simple explanations; those are better handled by direct prompts.

Using AI to generate and refine skills with the skill creator

Rather than writing skills manually, I advise delegating skill creation to AI models like Claude or ChatGPT. I highlight the official skill creator tool from Anthropic, which can be installed via the skills CLI.

This tool guides you through creating skills interactively, asking relevant questions like how to bump versions during deployment. It produces skills that follow best practices and can be reused across projects.

Creating a deployment skill example from package.json scripts

I demonstrate creating a deployment skill that reads scripts from a package.json file. The skill asks what to deploy (API routes, preview, production, iOS app) and whether to bump the version.

This example shows how skills can automate repetitive developer tasks, such as running deployment commands or managing version increments, saving time and reducing errors.

Best practices for concise skill metadata and instructions

Good skills are concise, often around 50 tokens, and avoid large paragraphs or excessive explanations. I contrasts a minimal PDF text extraction skill with a verbose bad example that wastes tokens.

I stress that Claude is smart enough to understand code snippets and scripts without lengthy descriptions. Clear, direct instructions improve performance and reduce costs.

Managing context window size and token costs

Since the agent loads skill metadata, system prompts, conversation history, and the actual request into the context window, keeping skills lean is critical. Overloading the context window leads to slower responses and higher expenses.

I recommend testing skills with different Claude models (Haiku, Sonnet, and Opus) to ensure they provide enough guidance without overexplaining, especially for expensive models like Opus.

Organizing skills with references and folder structure

You can add a references folder inside your skill to provide additional context files. The agent loads these references depending on the task, allowing you to supply extra information without cluttering the main skill instructions.

Skills should be organized with a skill.md file containing the name and description. Including a README with usage tips, when to use the skill, and caveats is also recommended.

Distributing skills to teams or the community

If you want to share skills beyond your local machine, create a public repository with a marketplace.json file describing your skills. This allows others to install your skills via the skills CLI.

I show an example public repo with skills like an app icon generator. Anyone with access can install these skills easily, enabling collaboration and community sharing.

Resources

CourseReact Native course

Fundamentals through shipping: the concepts behind the prompts, with lifetime access.

Pro MembershipPro membership

Access private GitHub repos and production examples like the AI Tattoo app.