5 Best Practices for Building AI Agent Skills

The video “2026 Guide to AI Agents” outlines five best practices for developing reliable, secure, and effective AI agent skills, emphasizing that while simple in concept, they are easy to misimplement. Agent skills provide procedural knowledge to an AI agent, typically structured as a .skill.md Markdown file, which can also contain and execute code. The core challenge lies in entrusting a probabilistic model with fragile, multi-step tasks, especially when involving external code.

1. Write Skills That Trigger

The first critical step is ensuring an agent uses the skill. Due to context window limitations, agents only load a skill’s name (max 64 characters) and description (max 1024 characters) at startup. These must be sufficiently descriptive for the agent to know when to invoke the skill.

• Specificity is Key: Vague descriptions like “generates reports” are insufficient. A better example is “generates the monthly compliance report from internal data used when someone asks for the compliance report or the monthly filing.” This clearly states what the skill does and when it should be used.
• “Pushy” Descriptions: Models tend to under-trigger, sometimes skipping a relevant skill. It’s advisable to “oversell the description a touch rather than undersell it” to encourage proper activation.

2. Build from Real Expertise

Resist the temptation to have the LLM solely generate skills, as this often results in “very generic mush” that reiterates what the model already knows (e.g., “handle errors appropriately,” “validate inputs”). The true value of a skill comes from incorporating unique, specific domain expertise that the model cannot access on its own.

• Sources of Expertise:
  • Manual Task Walkthroughs: Perform the task yourself, documenting the exact steps and any corrections made along the way.
  • Existing Artifacts: Synthesize knowledge from runbooks, old reports, review comments, or PR feedback.
• Division of Labor: As Simon Willison states, “Keep the domain expertise and let the agent do the routine part.” You provide the unique knowledge, and the model handles the execution.
• “Gotchas” in the Skill Body: The most valuable content in a skill’s Markdown body (skill.md) is “gotchas”—environment-specific facts or exceptions that defy reasonable assumptions. Each time you manually correct the agent, that correction should be documented as a “gotcha” to prevent recurrence.
• Thoroughness: A good skill body is thorough, even if it initially leads to errors (e.g., a “math was wrong” compliance report). Catching such errors allows for refinement and improvement.

3. Spend Context Wisely

While thoroughness is important, context window management is crucial for cost and performance. The agent only loads the full skill body into its context after selecting the skill, and this context is shared with other information.

• Write Lean: Every line in the skill body competes for the model’s attention. The goal is to “write lean,” including only what the agent wouldn’t know from its pre-training data (e.g., it knows what a PDF is, so no need to explain).
• Token Limits: It is recommended to keep the main skill.md body under approximately 500 lines of text or 5,000 tokens.
• Progressive Disclosure with references: For larger skills, split content into a references sub-folder within the skill directory. The agent will only open files in this directory “when it actually needs them,” employing a pattern called progressive disclosure to manage context efficiently.

4. When Agents Shouldn’t Guess: Deterministic Scripts

AI agents improvise based on instructions, which is suitable for flexible steps but problematic for critical, fragile operations requiring exact precision. For such steps, deterministic logic is essential.

• Match Prescriptiveness to Fragility: For loose steps, provide instructions. For fragile steps, provide code.
• Utilize scripts Directory: A skill folder can contain a scripts directory. You can place executable scripts here (e.g., script_one.py). The skill body then simply instructs the agent to run this script.
• Benefits:
  • Token Saving: Scripts are not loaded into the agent’s context, saving tokens.
  • Reliability: Running pre-defined code is more reliable than relying on the model to regenerate logic from scratch every time.
• Explicit Intent: Be explicit whether the agent should “run this script” or “read this as reference.”
• Moving to Determinism: This approach shifts critical operations “away from probabilistic” guessing to deterministic execution. For parts that “have to be right,” remove the guessing entirely. For example, a math error in a compliance report was resolved by implementing a “deterministic math script” instead of having the model perform calculations probabilistically.

5. Can You Trust This Skill? Vet a Skill Before You Run It

The ability for skills to contain and execute code, accessing local file systems or API keys, is powerful but introduces significant security risks.

• Security Concerns: An audit of nearly 4,000 public skills found over 35% with security flaws, and 13% with critical issues like prompt injection or malware.
• Treat as a Dependency: Agent skills, especially those sourced externally, must be treated like any other third-party dependency in a project.
• Thorough Vetting: Before running a skill, “read what it does and check what it reaches out to.” The fact that agent skills is an open standard does not inherently guarantee the safety of a given skill.

These best practices aim to guide developers in building robust, predictable, and secure AI agent skills, moving beyond initial simple implementations to more professional and reliable agentic systems.

• Tags:
• AI Agents
• Prompt Engineering
• Prompt Injection
• Large Language Models
• Security
• LLMs
• Feature
• Context Management
• IBM
• Agent Skills
• Software Engineering Best Practices
• Deterministic Logic
• Code Execution