> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Standards of Agent Skills

> Learn the AIsa Agent Skills structure, SKILL.md specification, and standards for portable, auditable skills across supported AI agents.

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](https://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:

```text theme={null}
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. |

## References

1. [What are skills? - Agent Skills](https://agentskills.io/what-are-skills)
2. [Specification - Agent Skills](https://agentskills.io/specification)
3. [AIsa Agent Skills Repository](https://github.com/AIsa-team/agent-skills)