{"id":496910,"date":"2026-10-01T12:09:22","date_gmt":"2026-10-01T12:09:22","guid":{"rendered":"https:\/\/savepearlharbor.com\/?p=496910"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T21:00:00","slug":"","status":"publish","type":"post","link":"https:\/\/savepearlharbor.com\/?p=496910","title":{"rendered":"How to Create Agent Skills: Tools, Testing, and Installation"},"content":{"rendered":"
\n

Originally published on <\/strong>Mavka<\/strong><\/a>.<\/strong><\/p>\n

\"An<\/p>\n
An instructor writing formulas on a large chalkboard<\/figcaption><\/div>\n<\/figure>\n
\n

In short. Start with a task that keeps coming up and turn it into a Skill with superpowers:writing-skills. While creating it, test scenarios with and without the Skill, and validate the structure of SKILL.md. Then use the Skill on several real tasks. If it consistently helps, share it with your team through a Skills repository or a Plugin.<\/p>\n<\/blockquote>\n

Creating your first Agent Skill is easy. Make a folder, put a SKILL.md<\/code> file in it, and write a few instructions.<\/p>\n

The harder part is knowing whether that Skill actually works.<\/strong><\/p>\n

The agent has to find it among dozens of other instructions, invoke it for the right request, ignore similar but irrelevant requests, follow its instructions, and produce a better result than it would without the Skill.<\/p>\n

This guide covers tools for the full cycle: creation, improvement, validation, testing, installation, and maintenance.<\/p>\n

What a Skill is in practice<\/h3>\n

An Agent Skill is a folder containing instructions, reference material, and, if needed, executable scripts. Only one file is required: SKILL.md<\/code>.<\/p>\n

A minimal Skill looks like this:<\/p>\n

review-migration\/\u2514\u2500\u2500 SKILL.md<\/code>
<\/span><\/a><\/div><\/pre>\n
---name: review-migrationdescription: Reviews database migrations for compatibility and rollback risks. Use when a user creates or changes a database migration.---Review the migration:1. Check backward compatibility.2. Identify locks or long-running operations.3. Verify the rollback or roll-forward path.4. Report only risks introduced by this migration.<\/code>
<\/span><\/a><\/div><\/pre>\n
The open Agent Skills specification<\/a> requires the name<\/code> and description<\/code> fields. The description tells the agent when to read the full Skill for the task at hand.<\/p>\n
That matters because of how Skills are loaded:<\/p>\n
    \n
  1. \n
    The agent sees the metadata for all available Skills.<\/p>\n<\/li>\n
  2. \n
    The description helps it decide whether to read a particular Skill.<\/p>\n<\/li>\n
  3. \n
    Once the Skill is activated, it reads the full SKILL.md<\/code>.<\/p>\n<\/li>\n
  4. \n
    It opens additional references\/<\/code>, scripts\/<\/code>, and assets\/<\/code> only when needed.<\/p>\n<\/li>\n<\/ol>\n
    Anthropic calls this progressive disclosure<\/a>. It manages context: the agent doesn\u2019t need the full text of every Skill in every request. It reads instructions for the relevant task and opens longer reference material when it needs it.<\/p>\n
    Skill, AGENTS.md, or Plugin?<\/h3>\n
    Not every instruction should become a Skill.<\/p>\n
    \n
    \n\n\n\n\n\n\n\n\n
    \n
    Mechanism<\/p>\n<\/th>\n
    		\n
    When to use it<\/p>\n<\/th>\n<\/tr>\n
    \n
    AGENTS.md<\/p>\n<\/td>\n
    		\n
    Short, always-on context: project structure, working commands, non-obvious architecture decisions, and links to detailed rules<\/p>\n<\/td>\n<\/tr>\n
    \n
    Skill<\/p>\n<\/td>\n
    		\n
    A repeatable process or knowledge needed only for a particular type of task<\/p>\n<\/td>\n<\/tr>\n
    \n
    Plugin<\/p>\n<\/td>\n
    		\n
    A collection of Skills with agents, Hooks, MCP servers, configuration, or its own versioning lifecycle<\/p>\n<\/td>\n<\/tr>\n
    \n
    MCP server<\/p>\n<\/td>\n
    		\n
    Standardized access to an external system, data, or API<\/p>\n<\/td>\n<\/tr>\n
    \n
    Hook<\/p>\n<\/td>\n
    		\n
    A predefined action triggered by an event, such as running a formatter after an edit<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n
    Why Skills once started replacing MCP integrations, and what changed<\/strong><\/p>\n
    Large MCP integrations used to load descriptions for every tool into each request. A few servers could occupy a substantial share of the context window. That led people to replace narrow integrations with Skills containing CLI commands: the agent would read the instructions only when it needed them.<\/p>\n
    Modern tool search with deferred loading<\/a> has changed that trade-off. Descriptions of unused MCP tools no longer have to be included in the initial request: the agent can find the tool it needs and load its description on demand. That makes discovery more similar to Skills, though their roles remain different: a Skill provides a process and knowledge, while an MCP server performs an external action or returns data.<\/p>\n
    \n
    A good sign that you need a new Skill: you\u2019re pasting the same checklist into a chat or explaining the same process to a new session for the third time.<\/p>\n<\/blockquote>\n
    Tools for creating Skills<\/h3>\n
    1. The agent itself<\/h4>\n
    You don\u2019t need a separate generator. Anthropic\u2019s official authoring guide<\/a> recommends completing a real task from start to finish in a normal agent session, then asking the agent to extract the repeatable process into a Skill.<\/p>\n
    That\u2019s a better starting point than inventing a universal Skill from scratch. Real work quickly shows you:<\/p>\n