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:

Standard	Description
API Proxy Alignment	All skills must use the AIsa API proxy (`api.aisa.one`) instead of direct upstream provider URLs.
Authentication	Skills should rely on the `AISA_API_KEY` environment variable for authentication.
Bundled Clients	We recommend providing a `scripts/` directory with a standalone Python client for complex interactions.
Citation Support	For search and research skills, instructions must emphasize providing inline citations for factual claims.

Getting Started

Marketing

AI Model Gateway

Creative AI

Data & Finance

Search & Research

Social Media

Standards of Agent Skills

Core Concepts

1. Progressive Disclosure

2. Portability and Auditability

Directory Structure

The SKILL.md Specification

Frontmatter Fields

Body Content

AIsa-Specific Standards

References

​Core Concepts

​1. Progressive Disclosure

​2. Portability and Auditability

​Directory Structure

​The SKILL.md Specification

​Frontmatter Fields

​Body Content

​AIsa-Specific Standards

​References

Core Concepts

1. Progressive Disclosure

2. Portability and Auditability

Directory Structure

The SKILL.md Specification

Frontmatter Fields

Body Content

AIsa-Specific Standards

References