# ASFS — Agent Skill Format Standard

**Version:** 1.0.0-draft
**Status:** Specification
**Layer:** Cross-layer (L3 Discovery + L5 Coordination)
**License:** CC BY 4.0

## 1. Purpose

Define a universal, cross-platform format for AI agent skills. Current ecosystems (Hermes, Claude Code, Codex, OpenClaw, CrewAI) each have proprietary skill formats. ASFS is an interchange standard — write once, run anywhere.

An ASFS skill is a self-contained unit of agent knowledge: what it does, when to use it, how to execute it, and what pitfalls to avoid.

## 2. Design Principles

- **Human-writable + agent-readable** — Markdown with YAML frontmatter. No JSON schema required to author.
- **Zero dependencies** — A skill is a single `.md` file. No package manager, no build step.
- **Self-documenting** — The skill describes itself. An agent reading it knows when and how to use it.
- **Cross-platform** — Same file works on Hermes, Claude Code, Codex, OpenClaw without conversion.
- **Versioned** — Semantic versioning. Agents check compatibility before loading.

## 3. Schema

```yaml
---
name: my-skill                    # lowercase, hyphens, max 64 chars
version: 1.0.0                    # semver
description: One-line summary     # max 120 chars
tags: [python, debugging, cli]    # discoverability
triggers:                         # when an agent should load this
  - "debug python"
  - "traceback"
  - "pdb"
os: [linux, macos, windows]       # platform compatibility
deps: []                          # external commands needed (optional)
---

# Skill Title (matches name in human-readable form)

## When to Use

Clear trigger conditions. An agent should know exactly when to load this.

## Steps

1. Numbered, actionable steps
2. Each step has a clear command or action
3. Verification: how to confirm the step worked

## Pitfalls

- Common mistakes and how to avoid them
- Platform-specific gotchas

## Verification

How an agent confirms the skill was applied correctly.
```

## 4. ASFS ↔ Hermes Converter

Hermes skills are a superset of ASFS. The converter strips Hermes-specific frontmatter and preserves the core format.

### Python converter (stdlib only)

```python
"""ASFS ↔ Hermes skill converter. No dependencies."""
import re, yaml  # yaml is optional — falls back to regex

def hermes_to_asfs(skill_md: str) -> str:
    """Convert a Hermes SKILL.md to ASFS format."""
    # Strip Hermes-specific frontmatter fields
    lines = skill_md.split("\n")
    output = []
    in_fm, fm_done = False, False
    skip_keys = {"hermes", "metadata", "related_skills", "category", 
                 "prerequisites", "author"}
    
    for line in lines:
        if line.strip() == "---" and not fm_done:
            in_fm, fm_done = True, True
            output.append(line)
            continue
        if in_fm and line.strip() == "---":
            in_fm = False
            output.append(line)
            continue
        if in_fm:
            key = line.split(":")[0].strip() if ":" in line else ""
            if key in skip_keys:
                continue
        output.append(line)
    
    return "\n".join(output)

# Usage:
# with open("~/.hermes/skills/my-skill/SKILL.md") as f:
#     asfs = hermes_to_asfs(f.read())
# with open("my-skill.asfs.md", "w") as f:
#     f.write(asfs)
```

## 5. Agent Adoption Instructions

### For any AI agent reading this:
```bash
# Download a skill in ASFS format
curl https://workswithagents.dev/v1/skills/my-skill > my-skill.asfs.md

# Validate
python3 -c "
import frontmatter  # pip install python-frontmatter (optional)
with open('my-skill.asfs.md') as f:
    fm = frontmatter.load(f)
    assert fm.get('name'), 'Missing name field'
    assert fm.get('version'), 'Missing version field'
"
```

### Skill discovery:
```bash
# List all ASFS skills available
curl https://workswithagents.dev/v1/skills

# Search by tag
curl https://workswithagents.dev/v1/skills?tag=python
```

## 6. Relationship to OSI Model

- **L3 (Discovery):** ASFS skills are discoverable via the Knowledge Platform API
- **L5 (Coordination):** Agents share skills through the Coordination Protocol
- **Cross-layer:** Skills are the atomic unit of agent knowledge — they flow through all layers

## 7. Status & Roadmap

- [x] Spec published (1.0.0-draft)
- [x] Hermes→ASFS converter
- [ ] ASFS validator
- [ ] ASFS registry (Knowledge Platform integration)
- [ ] Claude Code → ASFS converter
- [ ] Codex → ASFS converter
- [ ] Formal RFC submission (IETF-style)