# agentskills | Agent Skills | Knowledge Base | Instagit Specification and documentation for Agent Skills GitHub Stars: 22k Repository: https://github.com/agentskills/agentskills --- ## Articles ### [Testing and Evaluating AI Agent Skill Effectiveness Before Distribution: A Complete CI/CD Guide](/agentskills/agentskills/testing-and-evaluating-ai-agent-skill-effectiveness-before-distribution) Learn to test and evaluate AI agent skill effectiveness before distribution. Our guide uses a zero-dependency validation pipeline to ensure structural correctness, safety, and integrity. - Tags: how-to-guide - Published: 2026-07-06 ### [How to Add AI Agent Skill Support to an Existing Client](/agentskills/agentskills/how-to-add-ai-agent-skill-support-to-an-existing-client) Learn how to add AI agent skill support to your existing client. Implement a three stage progressive disclosure flow with the skills-ref library to integrate LLM system prompts. - Tags: how-to-guide - Published: 2026-07-06 ### [Implementing AI Agent Skill Autocomplete for User-Explicit Activation](/agentskills/agentskills/implementing-ai-agent-skill-autocomplete-for-user-explicit-activation) Learn how to implement AI agent skill autocomplete by scanning files, parsing front-matter, and exposing skill names for model context and user widgets. - Tags: how-to-guide - Published: 2026-07-06 ### [How to Implement Trust Checks for Loading Project-Level AI Agent Skills from Untrusted Repositories](/agentskills/agentskills/implementing-trust-checks-for-loading-project-level-ai-agent-skills-from-untrusted-repos) Securely load AI agent skills from untrusted repositories with a five-layer validation pipeline in agentskills. Protect your project from malicious code before execution. - Tags: security - Published: 2026-07-06 ### [Managing AI Agent Skill Context Deduplication to Avoid Duplicate Injections](/agentskills/agentskills/managing-ai-agent-skill-context-deduplication-to-avoid-duplicate-injections) Learn how to avoid AI agent skill context deduplication and prevent duplicate injections. The Agent Skills library efficiently manages metadata for consistent performance. - Tags: best-practices - Published: 2026-07-06 ### [Writing Effective AI Agent Skill Descriptions for Model Identification](/agentskills/agentskills/writing-effective-ai-agent-skill-descriptions-for-model-identification) Learn to write effective AI agent skill descriptions for accurate model identification. Craft concise, imperative phrases that AI models use to choose the right skill. - Tags: best-practices - Published: 2026-07-06 ### [How to Filter and Exclude AI Agent Skills from Catalog Based on User Permissions](/agentskills/agentskills/filtering-and-excluding-ai-agent-skills-from-catalog-based-on-user-permissions) Learn how to filter and exclude AI agent skills from your catalog based on user permissions. Securely manage access by validating tool permissions and metadata for a tailored experience. - Tags: how-to-guide - Published: 2026-07-06 ### [Implementing Subagent Delegation for Complex AI Agent Skill Workflows](/agentskills/agentskills/implementing-subagent-delegation-for-complex-ai-agent-skill-workflows) Master subagent delegation for complex AI agent workflows with Agent Skills. Learn to extend metadata for hierarchical AI and streamline skill execution. Get started today! - Tags: how-to-guide - Published: 2026-07-06 ### [Handling Malformed YAML in AI Agent Skill Frontmatter with Fallback Parsing](/agentskills/agentskills/handling-malformed-yaml-in-ai-agent-skill-frontmatter-with-fallback-parsing) Learn to handle malformed YAML in AI agent skill frontmatter using strict validation and a fallback parser. Prevent build failures and ensure data integrity. - Tags: how-to-guide - Published: 2026-07-06 ### [Creating Cross-Client Compatible AI Agent Skills Using the `.agents/skills/` Convention](/agentskills/agentskills/creating-cross-client-compatible-ai-agent-skills-using-agents-skills-convention) Learn to create cross-client compatible AI agent skills using the .agents/skills/ convention. Build portable, domain-specific extensions that work with any compliant client. - Tags: how-to-guide - Published: 2026-07-06 ### [Implementing AI Agent Skill Activation: Tools vs. File-Read Approaches](/agentskills/agentskills/implementing-ai-agent-skill-activation-via-tool-vs-file-read) Choose AI agent skill activation: explore tool-based vs file-read methods. Learn how allowed tools and YAML frontmatter enable efficient skill management. - Tags: deep-dive - Published: 2026-07-06 ### [Protecting AI Agent Skill Content from Context Truncation: A Complete Guide](/agentskills/agentskills/protecting-ai-agent-skill-content-from-context-truncation) Prevent AI agent skill context truncation. Learn how Agent Skills library enforces size limits and uses compact XML summaries to keep full documentation out of LLM prompts. - Tags: how-to-guide - Published: 2026-07-06 ### [Validating AI Agent Skill Names Against Specification Rules: A Complete Guide](/agentskills/agentskills/validating-ai-agent-skill-names-against-specification-rules) Learn to validate AI agent skill names with the skills-ref library. Enforce strict rules like character limits and directory matching using the powerful validate() function. Optimize your agent development today. - Tags: how-to-guide - Published: 2026-07-06 ### [Implementing Skill Discovery Across Project and User-Level Directories for AI Agents](/agentskills/agentskills/implementing-skill-discovery-across-project-and-user-level-directories-for-ai-agents) Implement skill discovery for AI agents with Agentskills. Scan directories for SKILL.md, validate metadata, and generate XML for LLMs. Enhance your AI capabilities seamlessly. - Tags: architecture - Published: 2026-07-06 ### [Best Practices for Structuring AI Agent Skill Directories: A Complete Guide](/agentskills/agentskills/best-practices-for-structuring-ai-agent-skill-directories) Master AI agent skill directory best practices. Learn essential structure, required SKILL.md, naming conventions, and ideal subdirectory organization for efficient development. - Tags: best-practices - Published: 2026-07-06 ### [Handling Name Collisions Between AI Agent Skills from Different Scopes](/agentskills/agentskills/handling-name-collisions-between-ai-agent-skills-from-different-scopes) Learn how Agent-Skills handles name collisions between AI agent skills by namespace-qualifying them with their originating scope. Discover how to manage duplicate skill names effectively. - Tags: how-to-guide - Published: 2026-07-06 ### [How to Parse YAML Frontmatter from SKILL.md Files in AgentSkills](/agentskills/agentskills/how-to-parse-yaml-frontmatter-from-skill-md-files) Learn how to parse YAML frontmatter from SKILL.md files in AgentSkills. Discover the `parse_frontmatter()` function for efficient data extraction and validation. - Tags: how-to-guide - Published: 2026-07-06 ### [How to Implement Progressive Disclosure for Loading AI Agent Skills](/agentskills/agentskills/how-to-implement-progressive-disclosure-for-loading-ai-agent-skills) Master progressive disclosure for AI agent skills. Load skills efficiently by deferring full instructions and files until selection. Enhance performance and reduce prompt complexity. - Tags: how-to-guide - Published: 2026-07-06 ### [How the Agent Skills Open Specification Handles Ecosystem Contributions](/agentskills/agentskills/how-does-the-open-specification-handle-contributions) Learn how the Agent Skills open specification manages ecosystem contributions via a SKILL.md schema, a validator CLI, and a structured pull request workflow. Contribute to the Agent Skills ecosystem. - Tags: how-to-guide - Published: 2026-07-05 ### [Open-Source Tools for Creating and Managing Agent Skills: The Complete Developer Toolkit](/agentskills/agentskills/what-open-source-tools-exist-for-creating-and-managing-skills) Discover open-source tools for creating and managing agent skills. Explore the agentskills Python package for authoring, validating, and publishing skills with a Markdown specification. - Tags: getting-started - Published: 2026-07-05 ### [How Scripts and References Work in Agent Skills Skill Packages](/agentskills/agentskills/how-do-scripts-and-references-work-within-a-skill-package) Understand how scripts and references function in Agent Skills packages. Learn to organize code and documentation for efficient agent tool execution and context injection. - Tags: documentation - Published: 2026-07-05 ### [NFKC Normalization Applied to Skill Names in Agent Skills](/agentskills/agentskills/what-is-the-nfkc-normalization-applied-to-skill-names) Learn how Agent Skills uses NFKC normalization to standardize skill names, ensuring compatibility and accurate matching of visually similar characters. - Tags: deep-dive - Published: 2026-07-05 ### [How Skills Are Discovered and Activated at Runtime by Agents Using Agent Skills](/agentskills/agentskills/how-are-skills-discovered-and-activated-at-runtime-by-agents) Learn how Agent Skills empowers agents to discover and activate runtime capabilities using a simple file-system contract. Separate metadata from Python implementation seamlessly. - Tags: how-to-guide - Published: 2026-07-05 ### [How the Compatibility Field Affects Skill Loading in Agent Skills](/agentskills/agentskills/how-does-the-compatibility-field-affect-skill-loading) Understand how the compatibility field in Agent Skills determines runtime environment readiness. Learn about its role in skill loading without impacting core validation. - Tags: deep-dive - Published: 2026-07-05 ### [Description Field Validation in Agent Skills: Rules and Implementation](/agentskills/agentskills/what-validation-rules-apply-to-the-description-field) Learn description field validation rules in Agent Skills. Discover length limits and implementation details for the _validate_description function. Ensure data integrity now. - Tags: deep-dive - Published: 2026-07-05 ### [How Metadata Key-Value Pairs Are Processed in Agent Skills Skill Frontmatter](/agentskills/agentskills/how-are-metadata-key-value-pairs-processed-in-skill-frontmatter) Learn how Agent Skills processes metadata key-value pairs in SKILL.md frontmatter, converting all entries to strings stored as a dict str str within SkillProperties. - Tags: how-to-guide - Published: 2026-07-05 ### [Which Client Implementations Support the Agent Skills Format?](/agentskills/agentskills/what-client-implementations-support-the-agent-skills-format) Discover which client implementations support the Agent Skills format. Explore the canonical list of 38+ integrations including Claude Code, GitHub Copilot, and Cursor. - Tags: getting-started - Published: 2026-07-05 ### [How the Agent Skills Reference Library Integrates with strictyaml for YAML Parsing](/agentskills/agentskills/how-does-the-reference-library-integrate-with-strictyaml) Learn how the Agent Skills reference library integrates with strictyaml for robust YAML parsing. Enforce strict YAML 1.2 compliance and standardize error handling for your skills. - Tags: how-to-guide - Published: 2026-07-05 ### [Understanding the `` XML Output Format in Agent Skills](/agentskills/agentskills/what-is-the-structure-of-the-available_skills-xml-output-format) Examine the XML output format used in Agent Skills. Learn its structure, including root elements, skill entries, and safely parsed child elements like name, description, and location. - Tags: api-reference - Published: 2026-07-05 ### [How the AgentSkills Parser Handles Both SKILL.md and skill.md File Variants](/agentskills/agentskills/how-does-the-parser-handle-both-skill-md-and-skill.md-file-variants) Learn how the AgentSkills parser reliably handles both SKILL.md and skill.md file variants using a case-insensitive search order for cross-platform compatibility. - Tags: internals - Published: 2026-07-05 ### [Character Length Limits Enforced by the Agent Skills Validator](/agentskills/agentskills/what-are-the-character-length-limits-enforced-by-the-validator) Discover character length limits for Agent Skills validator. Learn the 64-character limit for skill names, 1024 for descriptions, and 500 for compatibility strings in SKILL.md. - Tags: api-reference - Published: 2026-07-05 ### [SkillProperties Data Model in Agentskills: Structure and Dictionary Conversion](/agentskills/agentskills/how-is-the-skillproperties-data-model-structured-and-converted-to-dict) Explore the SkillProperties data model structure in agentskills. Learn how it converts to a dictionary excluding None and empty values for compact JSON payloads. - Tags: deep-dive - Published: 2026-07-05 ### [How `allowed_tools` Works in the Agent Skills Metadata Schema](/agentskills/agentskills/how-do-allowed_tools-work-in-the-skill-metadata-schema) Learn how the allowed_tools field in the Agent Skills metadata schema lets you whitelist tool patterns for your skills. Understand its runtime enforcement by downstream agents. - Tags: documentation - Published: 2026-07-05 ### [skills_ref Error Types: ParseError, ValidationError, and When They Are Raised](/agentskills/agentskills/what-error-types-does-the-skills_ref-library-define) Understand skills_ref Error Types: ParseError and ValidationError. Learn when to expect these errors during SKILL.md parsing for missing files, malformed frontmatter, or invalid metadata. - Tags: api-reference - Published: 2026-07-05 ### [How the AgentSkills Validator Checks Directory Name and Skill Name Consistency](/agentskills/agentskills/how-does-the-validator-check-directory-name-and-skill-name-consistency) Discover how the agentskills validator ensures directory name and skill name consistency by normalizing and comparing both values. - Tags: how-to-guide - Published: 2026-07-05 ### [File Path Resolution Mechanisms in the Agent Skills Parser](/agentskills/agentskills/what-are-the-file-path-resolution-mechanisms-in-the-parser) Discover how the Agent Skills parser uses Python's pathlib to find SKILL.md files via directory discovery and normalized CLI arguments. Learn about file path resolution mechanisms for efficient skill management. - Tags: deep-dive - Published: 2026-07-05 ### [How the Reference Library Handles Internationalization (i18n) in Skill Names](/agentskills/agentskills/how-does-the-reference-library-handle-i18n-in-skill-names) Learn how the agentskills reference library handles internationalization i18n in skill names by supporting Unicode letters and international characters while enforcing standards for clear and consistent skill identification. - Tags: internals - Published: 2026-07-05 ### [How Skill Properties Are Serialized to XML Prompts for Agent Consumption](/agentskills/agentskills/how-are-skill-properties-serialized-to-xml-prompts-for-agent-consumption) Learn how AgentSkills serializes skill properties to XML prompts. Discover the process of reading YAML, validating metadata, escaping characters, and creating the system prompt block. - Tags: how-to-guide - Published: 2026-07-05 ### [Difference Between parse_frontmatter and validate in Agent Skills: Parsing vs Validation Explained](/agentskills/agentskills/what-is-the-difference-between-parse-frontmatter-and-validate-functions) Understand the difference between parse_frontmatter and validate in Agent Skills. Learn how parse_frontmatter converts YAML front-matter to a Python dictionary and validate checks metadata for adherence to specifications. - Tags: deep-dive - Published: 2026-07-05 ### [How AgentSkills Enforces Skill Name Constraints in the Validation Logic](/agentskills/agentskills/how-does-the-validation-logic-enforce-skill-name-constraints) Discover how the agentskills repository strictly enforces skill name constraints using its private _validate_name helper ensuring every skill meets presence formatting and directory alignment rules. - Tags: deep-dive - Published: 2026-07-05 ### [YAML Frontmatter Schema for SKILL.md Files: Exact Specification](/agentskills/agentskills/what-is-the-exact-yaml-frontmatter-schema-for-skill-md-files) Discover the exact YAML frontmatter schema for SKILL.md files. Learn the precise structure required for your skill definitions and ensure compliance with the agentskills repository standards. - Tags: api-reference - Published: 2026-07-05 ### [How Agent Skills Implements Progressive Disclosure for Skill Loading: A 3-Tier Strategy](/agentskills/agentskills/how-does-agent-skills-implement-progressive-disclosure-for-skill-loading) Agent Skills optimizes skill loading with progressive disclosure. Discover how its 3-tier strategy minimizes token costs by incrementally loading skill definitions for efficient model interaction. - Tags: deep-dive - Published: 2026-07-05 ### [Python Packages Used in the Agent Skills Reference Library: Complete Dependency Guide](/agentskills/agentskills/python-packages-agent-skills-reference-library) Explore the Python packages powering the Agent Skills reference library. Discover core dependencies like Click, Pydantic, and Rich, plus development tools. Get the full dependency guide. - Tags: api-reference - Published: 2026-07-03 ### [How Agent Skills Ensures Consistent and Auditable Procedures for AI Agents](/agentskills/agentskills/agent-skills-consistent-auditable-procedures) Agent Skills ensures consistent and auditable AI agent procedures with declarative SKILL.md descriptors and a validated library enforcing specifications for reproducible and traceable skills. - Tags: how-to-guide - Published: 2026-07-03 ### [Skill Bundle Structure in Agent Skills: The Complete Guide](/agentskills/agentskills/structure-of-skill-bundle) Discover the structure of a skill bundle in Agent Skills. Learn how to create a self-contained folder with SKILL.md and auxiliary resources. - Tags: deep-dive - Published: 2026-07-03 ### [How to Create a New Agent Skill in the agentskills Framework](/agentskills/agentskills/how-to-create-new-agent-skill) Learn how to create a new Agent Skill in agentskills. Add a kebab-case folder under .agents/skills/ and a SKILL.md file with essential YAML front-matter and instructions. - Tags: how-to-guide - Published: 2026-07-03 ### [Benefits of Using Agent Skills for Packaging Procedural Knowledge](/agentskills/agentskills/benefits-of-agent-skills-for-procedural-knowledge) Discover how Agent Skills package procedural knowledge with version control for AI agents. Enhance reusability and portability of step-by-step instructions and scripts. - Tags: getting-started - Published: 2026-07-03 ### [What is NFKC Unicode Normalization in Agent Skills: A Complete Guide](/agentskills/agentskills/nfkc-unicode-normalization-agent-skills) Learn how Agent Skills uses NFKC Unicode normalization to ensure skill and directory names match consistently by standardizing character sequences for accurate comparisons. - Tags: deep-dive - Published: 2026-07-03 ### [How Agent Skills Handles Unicode Characters in Skill Names](/agentskills/agentskills/unicode-handling-skill-names-agent-skills) Agent Skills validates skill names using Unicode characters from diverse scripts like Chinese, Cyrillic, and Arabic via NFKC normalization and str.isalnum. Learn how. - Tags: how-to-guide - Published: 2026-07-03 ### [How to Generate XML Prompts for Agent Integration Using the Agent Skills CLI](/agentskills/agentskills/generate-xml-prompts-cli-agent-skills) Easily generate XML prompts for agent integration with the Agent Skills CLI. Learn how the to-prompt subcommand converts skill directories for Anthropic Claude and compatible agents. - Tags: how-to-guide - Published: 2026-07-03 ### [How to Validate a Skill Directory Using the Agent Skills CLI](/agentskills/agentskills/validate-skill-directory-cli) Validate skill directories with the Agent Skills CLI. Learn how to check front-matter, naming, and length constraints for successful skill integration. Quick and easy validation. - Tags: how-to-guide - Published: 2026-07-03 ### [Primary CLI Commands for Agent Skills: validate, read-properties, and to-prompt](/agentskills/agentskills/primary-cli-commands-agent-skills) Master Agent Skills CLI commands validate read-properties and to-prompt to verify skill integrity extract metadata and generate XML prompts directly from your terminal. - Tags: how-to-guide - Published: 2026-07-03 ### [What YAML Parsing Library Does Agent Skills Use and Why?](/agentskills/agentskills/yaml-parsing-library-agent-skills) Agent Skills uses strictyaml for YAML parsing due to its strict schema validation, prevention of arbitrary code execution, and strongly typed Python dictionaries. Learn why. - Tags: internals - Published: 2026-07-03 ### [How the Agent Skills Parser Handles File Discovery and Frontmatter Extraction](/agentskills/agentskills/agent-skills-parser-file-discovery-extraction) Explore how the Agent Skills parser discovers SKILL.md files and extracts YAML frontmatter for strict validation into SkillProperties. Learn about efficient skill descriptor management. - Tags: how-to-guide - Published: 2026-07-03 ### [What Is the Role of the Parsing and Validation System in Agent Skills?](/agentskills/agentskills/role-of-parsing-validation-system-agent-skills) Discover the crucial role of the parsing and validation system in Agent Skills. Ensure your SKILL.md files are converted to typed SkillProperties objects, meeting strict specification compliance. - Tags: deep-dive - Published: 2026-07-03 ### [How the Progressive Disclosure Model Powers Agent Skills: A Three-Stage Architecture](/agentskills/agentskills/how-progressive-disclosure-model-works) Discover how the progressive disclosure model in Agent Skills works. Learn about its three-stage architecture for efficient AI agent context management. - Tags: architecture - Published: 2026-07-03 ### [Description Field Validation Rules in SKILL.md: The 3 Constraints You Must Follow](/agentskills/agentskills/description-field-validation-skillmd) Learn the 3 essential validation rules for the description field in SKILL.md: required, non-empty, and max 1024 characters. Ensure your skill files are valid. - Tags: how-to-guide - Published: 2026-07-03 ### [How the Name Field Is Validated in SKILL.md: 7 Rules Explained](/agentskills/agentskills/name-field-validation-skillmd) Understand SKILL.md name validation. Learn the 7 rules, including lowercase letters, hyphens, and character limits, enforced by the _validate_name function. - Tags: how-to-guide - Published: 2026-07-03 ### [What Are the Optional Fields in SKILL.md Frontmatter?](/agentskills/agentskills/optional-fields-skillmd-frontmatter) Discover the optional fields in SKILL.md frontmatter beyond name and description. Learn about license, compatibility, allowed-tools, and metadata. - Tags: api-reference - Published: 2026-07-03 ### [Required Fields in SKILL.md Frontmatter: A Complete Guide for Agent Skills](/agentskills/agentskills/required-fields-skillmd-frontmatter) Learn the required fields for SKILL.md frontmatter. Master the name and description fields for agent skills to ensure successful parsing and integration. - Tags: how-to-guide - Published: 2026-07-03 ### [What Is the SKILL.md File in Agent Skills? A Complete Guide](/agentskills/agentskills/purpose-of-skillmd-file) Discover the SKILL.md file, the central descriptor and activation trigger for Agent Skills. Learn how this single source of truth guides agents on skill purpose, invocation, and execution. - Tags: how-to-guide - Published: 2026-07-03 ### [Agent Skills Reference Library Structure: A Complete Guide to the skills-ref Package](/agentskills/agentskills/agent-skills-reference-library-structure) Understand the Agent Skills reference library structure. This guide explains how the skills-ref Python package parses YAML, validates metadata, and generates XML prompt blocks for LLM integration. - Tags: api-reference - Published: 2026-07-03 ### [Main Components of the Agent Skills Repository: A Complete Technical Guide](/agentskills/agentskills/agent-skills-repository-components) Explore the main components of the Agent Skills repository. Learn how the skills_ref Python library with its seven modules validates, parses, and renders skill definitions for LLM prompts. - Tags: deep-dive - Published: 2026-07-03 ### [How Agent Skills Extend AI Agent Capabilities: A Modular Architecture Guide](/agentskills/agentskills/how-agent-skills-extend-ai-agent-capabilities) Explore how Agent Skills extend AI agent capabilities. This modular architecture guide shows how agents gain new knowledge and expertise without inflating context windows. - Tags: architecture - Published: 2026-07-03 ### [What Is the Agent Skills Format? A Lightweight Spec for AI Agent Expertise](/agentskills/agentskills/what-is-agent-skills-format) Discover the Agent Skills format, a lightweight spec for AI agent expertise. Learn how it packages reusable knowledge and workflows using structured directories and SKILL.md files. - Tags: getting-started - Published: 2026-07-03