ASFS — Agent Skill Format Standard

Version: 1.0.0 Status: Published 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

---
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)

"""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:

# 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:

# 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)