Skip to main content

​
Standards of Agent Skills 📜

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. By following a standardized structure, skills become portable, self-documenting, and easy for agents to discover and execute. AIsa’s agent skills are built upon the open standards defined at agentskills.io, adapted for the AIsa ecosystem to ensure high reliability and seamless integration with our API proxy. Importantly, AIsa agent skills are designed for broad compatibility and can be seamlessly integrated with all major agent harnesses, including OpenClaw, Claude Code, and Hermes.

​
Core Concepts

​
1. Progressive Disclosure

To manage context efficiently, skills use a three-tier loading strategy:
  • Discovery: Agents only load the skill’s name and description initially to determine relevance.
  • Activation: When a task matches, the full SKILL.md instructions are read into context.
  • Execution: Detailed scripts, references, or assets are loaded only when specifically required by the agent.

​
2. Portability and Auditability

A skill is simply a folder containing a SKILL.md file. This makes them:
  • Self-documenting: Humans can read and audit the instructions as easily as agents.
  • Versionable: Skills can be managed in Git repositories, allowing for clear change tracking.
  • Extensible: They can range from simple text instructions to complex executable code.

​
Directory Structure

A standard AIsa skill follows this directory layout: 
skill-name/
├── SKILL.md          # Required: Metadata and instructions
├── scripts/          # Optional: Executable code (Python, Bash, etc.)
├── references/       # Optional: Technical documentation or reference guides
└── assets/           # Optional: Templates, images, or static data

​
The SKILL.md Specification

The SKILL.md file is the heart of every skill. It must contain YAML frontmatter followed by Markdown content.

​
Frontmatter Fields

  • name: A short, unique identifier (lowercase alphanumeric and hyphens).
  • description: A clear explanation of what the skill does and when the agent should use it. This is the primary signal for discovery.
  • metadata: (Optional) A map for additional properties like author, version, or platform-specific tags.
  • homepage: (Optional) A link to the skill’s home or repository.

​
Body Content

The Markdown body contains the actual instructions. For AIsa skills, we recommend including:
  • Step-by-step instructions: Clear, actionable steps for the agent.
  • Usage examples: Concrete cURL or Python snippets.
  • Edge cases: Guidance on how to handle common errors or limitations.

​
AIsa-Specific Standards

While AIsa skills adhere to the general specification, we apply additional standards to ensure they work perfectly with our platform:
StandardDescription
API Proxy AlignmentAll skills must use the AIsa API proxy (api.aisa.one) instead of direct upstream provider URLs.
AuthenticationSkills should rely on the AISA_API_KEY environment variable for authentication.
Bundled ClientsWe recommend providing a scripts/ directory with a standalone Python client for complex interactions.
Citation SupportFor search and research skills, instructions must emphasize providing inline citations for factual claims.

​
References

  1. What are skills? - Agent Skills
  2. Specification - Agent Skills
  3. AIsa Agent Skills Repository