Write AI Agent Skills and Plugins That Load and Trigger Correctly

## Read the Official Docs and Adapt a Reference Skill Before writing anything, read the current official documentation for the plugin and skill system you are targeting: the plugin format, the skill format, and the published authoring best practices. Vendor documentation changes faster than any third-party write-up, so treat it as the source of truth and treat community guides as commentary on top of it. Then pick a reference skill at the complexity level you need and adapt it rather than designing a structure from scratch: - Basic: minimal frontmatter and a short block of guidance, nothing else. - Intermediate: a language package, a references directory, and language-specific documents. - Advanced: scripts, workflow files, templates, extraction helpers, and multiple entry points. Reading two or three production plugins from other teams is usually faster than inventing a layout. If the environment provides a documentation-aware helper agent for plugin and skill questions, route those questions there instead of answering from memory. ## Keep One Metadata Source Even When Several Runtimes Load the Plugin When more than one agent runtime can load your plugin, choose a single metadata format as canonical and do not add per-runtime sidecar copies. Duplicated metadata drifts, and the drift is discovered by users rather than by CI. In practice: - Keep the marketplace manifest and the per-plugin manifest in their one canonical location. - Do not create parallel runtime-specific manifest directories or plugin-metadata directories for a second runtime. - Keep every component at the plugin root using the default paths both runtimes already understand: the skills directory, the hooks file, the MCP configuration file, and the app configuration file. - If a plugin needs MCP configuration, put it in the dedicated MCP configuration file at the plugin root instead of embedding an object inside the plugin manifest. Run the loadability check for each supported runtime before submitting. When one runtime fails, fix the canonical source so the other runtime can load it through compatibility — never by adding a second copy of the same metadata. ## Put Component Folders at the Plugin Root, Not in the Metadata Folder A plugin directory holds a plugin-metadata directory containing only the plugin manifest (name, version, description, author), plus optional directories for slash commands, autonomous agents, skills, and event hooks, plus a README that documents the plugin. Each skill lives in its own directory under the skills directory, with an entry-point document carrying the frontmatter, and optional subdirectories for references, workflows, and scripts. The rule that trips people up most: component directories — skills, commands, agents, and hooks — must sit at the plugin root, not inside the plugin-metadata directory. Only the plugin manifest belongs there. Loaders and reviewers both depend on this, and a misplaced component directory usually presents as a plugin that silently exposes nothing. ## Pick a Clear Kebab-Case Name and Fill In the Frontmatter The frontmatter on a skill entry point needs, at minimum, a name and a description. An optional allowed-tools list restricts the skill to the tools it genuinely needs, which is worth setting whenever the skill is narrow. - The name is kebab-case and stays within the length limit, commonly 64 characters. - The description is written in third person and states both what the skill does and when to use it. - Prefer the gerund form for names — a verb-first name like "analyzing-contracts" or "processing-pdfs" reads better than a noun-agent name like "contract-analyzer" or "pdf-processor". - Avoid vague names such as helper, utils, tools, or misc, which match everything and mean nothing. - Avoid reserved words, including vendor and product names, which the runtime may treat specially. ## Say in the Description What the Skill Does and When to Use It Your skill competes with a hundred others for attention, and the description is often the only text the agent reads when deciding whether to load it. A vague description means the skill sits unused, or worse, fires in the wrong situation. - Third-person voice: "Analyzes X", not "I help with X". - Include the triggering situation, not just the subject: "Use when auditing smart contracts" carries far more routing signal than "Smart contract tool". - Be specific about the capability: "Detects reentrancy vulnerabilities" beats "Helps with security". Write the description as if it were the routing rule it actually is, and re-read it asking whether a competing skill would win the same request. ## Avoid Hardcoded Paths and Declare Script Dependencies Inside the Script Never hardcode absolute paths. Use the base-directory variable the runtime provides, and use forward slashes even on Windows, so the same skill works on every machine. When a skill ships scripts that have dependencies: 1. Declare the dependencies inline in the script header using the standard inline-metadata block for that language, including the minimum language version. This lets the runner resolve everything without a separate install step. 2. Invoke the script through a runner that honors that inline metadata, so dependency resolution is automatic rather than a documented prerequisite. 3. Keep a project file in the scripts directory for development tooling such as linters and formatters. 4. Document system-level dependencies that the language package manager cannot install — PDF and OCR tooling, for example — in the workflow files, with platform-specific install commands. ## Keep Hooks That Run Before Every Command Fast Hooks that run before every command sit on the hot path, so their cost is paid on every single invocation. Performance is a correctness concern here, not a nicety. - Prefer a shell plus a lightweight JSON filter over a full interpreter. Interpreter and parser startup adds latency that users feel on every command. - Fast-fail early: exit successfully and immediately for commands that clearly do not match, so the overwhelming majority of invocations are effectively free. - Favor regular expressions over full syntax-tree parsing. Accept rare false positives when the performance gain is significant and the agent can simply rephrase the command. - Anticipate the false-positive shapes: diagnostic commands that merely locate an interpreter, search commands that mention its name as a search term, and filenames containing that name must not trigger interception. - Document these tradeoffs in the change description so reviewers can see the choices were deliberate rather than sloppy. ## Teach When and Why to Look Things Up Instead of Pasting Whole Specs A skill should supply guidance the model does not already have. Pasting an entire specification into a skill burns context and adds nothing the model could not look up. - Do not paste whole specifications or API references. Teach when and how to look things up instead. - Explain why, not only what: include trade-offs, decision criteria, and the judgment calls a newcomer would get wrong. - Document anti-patterns together with the reason they are wrong, rather than a bare list of prohibitions. A good example of the pattern: a skill for a complex binary debug format does not embed the format specification. It teaches which inspection tools to reach for, how to query them, and which tool is appropriate for which question. ## Set Strictness by Task Risk and Say When Not to Use the Skill How rigid a skill should be depends on how fragile the task is. - Strict for fragile tasks: security audits, cryptographic implementations, and compliance checks need rigid, enforced, step-by-step procedures. - Flexible for variable tasks: code exploration, documentation, and refactoring should offer options and leave room for judgment. Every skill entry point must carry two sections. A "When to Use" section listing the specific scenarios where the skill applies, and a "When NOT to Use" section naming the cases where a different approach is better. The negative section is the one people skip, and it is the one that stops the skill from firing in the wrong place. Audit and security skills need a third section, "Rationalizations to Reject", listing the common shortcuts and excuses that lead to missed findings — because under time pressure those rationalizations are exactly what surfaces. ## Keep the Main File Short and Link Details Only One Level Deep Keep the skill entry point under roughly 500 lines and split the remainder into a references directory and a workflows directory. Put the quick start first and the details behind links, so a reader who needs only the common path never loads the rest. Keep links one level deep: the entry point links to files, and those files do not chain onward to further files. Directory depth itself is fine — a references directory with topic subfolders is perfectly reasonable. The problem is chained indirection, not nested folders. A typical shape is a Quick Start section holding the core instructions, an Advanced Usage section pointing at one reference document for detailed patterns, and an API reference section pointing at another for complete method documentation. ## Pass the Automated and Reviewer Checks and Bump the Version Before Review Separate what automation validates from what a human reviewer must judge, and clear both before opening a review. Automated checks: valid frontmatter with a name and description; a kebab-case name within the length limit; every referenced file actually exists; no hardcoded home-directory paths; the loadability check passes for each supported runtime. Reviewer checks: the description triggers correctly and is written in third person; both the "When to Use" and "When NOT to Use" sections are present; examples are concrete, showing input and resulting output; the document explains why and not only what. Documentation: the plugin has a README; it is added to the root README table; it is registered in the repository-level marketplace manifest rather than the plugin's own metadata directory; and an ownership entry names the maintainers in the code-owners file. Version updates for an existing plugin: increment the version in both the plugin manifest and the repository-level marketplace entry, and keep the two numbers identical. Many clients pull an update only when the version number increases, so a missed bump means nobody receives the fix.