Creating Skills for AI Agents: Mechanics, Best Practices, and Turning Into a Plugin

The author, developer of the rpa-skills repository, details how to create skills for AI agents the right way. A skill is not a single markdown file but a folder with a mandatory SKILL.md file containing a YAML header (name, description) and an instruction body, along with optional directories references/, scripts/, assets/ and README.md. The principle of progressive disclosure loads only the skill description into the system; the body is pulled upon activation, so the body should be kept to 500 lines, with heavy content moved to references/. In the description field, it's important to clearly specify the purpose and trigger conditions, avoiding generic words like MUST to prevent the model from activating the skill haphazardly. The author emphasizes the difference between skills and rules: rules (with alwaysApply: true) are always active and suitable for code style or error handling, while skills are better for multi-step procedures (deployment, BDD, bug analysis). Skill descriptions and bodies should be written in English due to tokenization: Cyrillic takes on average twice as many tokens as Latin, saving context. Practices from Anthropic are provided: degrees of freedom (strict rails for critical tasks, open field for creative ones), deterministic operations should be moved to scripts, a mandatory section for common mistakes (Gotchas), names in gerund form (e.g., processing-pdfs), and avoid excessive variability—better to give one main solution and one fallback. For testing a skill, run a sub-agent with a clean context and check if the skill activates automatically, where it made errors, and whether the result matches expectations. At least three runs on different tasks and on different models, including small ones that follow instructions literally, are recommended. A skill for the marketplace is packaged as a plugin—a folder with a manifest plugin.json (for Claude Code in .claude-plugin/, for Codex in .codex-plugin/), specifying metadata, with the name matching the name from SKILL.md and version synced. The plugin can also include slash commands, sub-agents, hooks, and MCP servers.