# 5 Best Practices for Building AI Agent Skills

## Executive summary

This guide outlines five best practices for building reliable, secure, and effective AI agent skills. Skills are defined as procedural knowledge packaged in a `skill.md` file that teaches an AI agent specific job functions. Best practices emphasize improving skill triggering via detailed descriptions, grounding content in real domain expertise, managing context window size by using progressive disclosure, enforcing deterministic logic through scripts for critical steps, and rigorously vetting all skills for security vulnerabilities.

## Key takeaways

- Best Practice 1: Optimize the Skill Description (Triggering): The agent uses the skill's name and description to decide if it should run. The description must be highly informative, stating what the skill does and when it should be used. It is recommended to 'oversell' the description slightly rather than underselling it, as models tend to under-trigger.
- Best Practice 2: Build from Real Expertise: Skills must contain domain expertise that the model cannot generate on its own. This content should be synthesized from existing artifacts (e.g., old reports, run books, PR feedback). The highest value section in the skill body is often 'gotchas'—environment-specific facts or corrections made during manual execution.
- Best Practice 3: Spend Context Wisely: The goal is to keep the skill body lean. Since the entire skill body contributes to the context window, only include information the agent wouldn't know otherwise. For large bodies of text, use a dedicated `references` sub-folder and implement 'progressive disclosure,' allowing the agent to open files only when needed.
- Best Practice 4: Use Deterministic Scripts for Fragile Steps: For steps that must be exactly correct (fragile steps), do not rely on the model's probabilistic improvisation. Instead, write deterministic code and place it in a dedicated `scripts` directory within the skills folder. This ensures consistent, reliable execution.
- Best Practice 5: Vet Skills Before Running Them: Treat agent skills like any external dependency package. Because skills can run code and access local file systems or APIs, they must be audited for security flaws (e.g., prompt injection or malware) before deployment.

## Technical details

- AI Agent Skills Structure: A skill is procedural knowledge packaged in a `skill.md` file, containing YAML definitions for name (max 64 characters) and description (max 1024 characters). The standard is defined at agentskills.io.
- Context Management: The skill body should ideally be kept under approximately 5,000 tokens (or ~500 lines of text). Exceeding this limit requires splitting content into a `references` sub-folder to maintain context efficiency.
- Code Execution: Deterministic scripts should be placed in a dedicated `scripts` directory. The skill body must explicitly instruct the agent whether to 'run this script' or 'read this as reference,' preventing ambiguity.

## Practical implications

- When building skills, prioritize domain knowledge and hard-won operational fixes ('gotchas') over general LLM output.
- For mission-critical or mathematically sensitive steps, always replace probabilistic model calls with deterministic code scripts to guarantee consistency across runs.
- Implement a security vetting process for all third-party skills, treating them as high-risk dependencies.

## Topics

AI Agents, Skill Engineering, Context Window Management, Deterministic Logic, Prompt Injection, Build Standards, agentskills.io, IBM Technology Newsletter

Source: https://www.youtube.com/watch?v=qYNs80FKIVc