.yawn Skills

.yawn Skills Documentation

Complete reference for the .yawn agentic skill system. Extends the Agent Skills standard with holonic composition, trust scoring, and autonomous lifecycle management.

Getting Started

A .yawn skill is a directory containing at minimum a SKILL.yawn or SKILL.md file that describes a capability an AI agent can invoke.

# Install a skill from the yawn shop

yawn install entity-extract

# Create a new skill

yawn skill create my-skill --category=perception

# Score a skill's trust level

yawn score my-skill

Each skill lives in a directory under .yawn/skills/<category>/<skill-name>/. The directory name IS the skill ID. The path IS the holarchy position.

SKILL.yawn Format

The SKILL.yawn format extends the standard SKILL.md with structured YAML frontmatter and .yawn-specific sections.

---
name: entity-extract
description: Extract named entities from natural language.
version: 1.0.0
category: perception
status: active
priority: high
holarchy-path: yawn/skills/perception/entity-extract
handler: lib/skills/handlers/entity-extract.ts
required-skills: [llm-invoke]
evidence-kind: skill_entity_extract
autonomy-level: 3
trust-score: null  # Computed by the scorer

# .yawn extensions (not in standard SKILL.md)
lifecycle:
  spawn-condition: "When text input contains > 3 potential entities"
  retire-condition: "Superseded by domain-specific extractor"
  parent: perception
  children: []
holarchy:
  inherits-from: perception
  overridable: true
  scope: subtree
---

# Entity Extract

Extracts named entities (people, organizations, dates, locations,
amounts) from natural language text.

## When to Use
- Processing user input that references real-world entities
- Building knowledge graphs from unstructured text
- Populating entity databases from notes or triggers

## Instructions
1. Accept raw text input
2. Run NER via LLM with structured output schema
3. Return typed entity array with confidence scores

## Evidence
Every invocation logs a `skill_entity_extract` event with:
- Input length, entity count, confidence distribution
- Used for trust score computation and gradient analysis

Standard fields (SKILL.md compatible)

name, description, version
category, status, priority
# Instructions, ## When to Use

.yawn extensions

holarchy-path, handler, evidence-kind
autonomy-level, trust-score
lifecycle (spawn/retire/parent/children)
holarchy (inherits-from, scope, overridable)

The Holarchy Model

In the .yawn system, skills nest inside skills. Each skill is both a whole (it can execute independently) and a part (it belongs to a category or parent skill). This is the holarchy.

Skill Holarchy (URL = Holarchy = Permission Tree)

yawn.ai/skills - root manifest

├── core/ - fundamental capabilities

├── llm-invoke/ [L4]

├── json-parse/ [L4]

└── rate-limit/ [L3]

├── perception/ - input understanding

├── entity-extract/ [L3]

└── intent-classify/ [L4]

├── safety/ - guardrails

├── risk-assess/ [L2]

└── kernel-pdp/ [L1]

└── action/ - world changes

├── db-mutate/ [L3]

└── yawn-create/ [L3]

[L1]=human-required [L2]=human-oversight [L3]=auto+audit [L4]=fully-autonomous

The holarchy encodes three things simultaneously:

Composition - which skills are needed to compose a capability
Navigation - the URL path maps directly to the tree position
Permission - depth determines autonomy requirements

Skill Lifecycle

planned

stub

partial

active

blocked

retired

Skills progress through these stages. The loop status is derived from the lifecycle stage and handler availability:

Loop Closed

Status is 'active', handler exists, evidence is being captured. The skill works end-to-end.

Partial

Skill exists but is incomplete. May be missing a handler, evidence capture, or error handling.

Missing / Gap

The skill is a stub, planned, or blocked. It is a lacuna that needs to be filled.

Trust Scoring

Every skill is scored across four dimensions with 35+ automated checks.

Functional30%

Does the skill have a handler, inputs/outputs, and evidence capture?

Quality25%

Error handling, schema validation, documentation completeness.

Safety30%

Scope boundaries, escalation paths, rate limiting. Safety floor: if < 50%, overall grade capped at D.

Maintenance15%

Update frequency, dependency health, deprecation markers.

Try it live: yawn.ai/agentic-skills-testing

Cross-Platform Usage

Every SKILL.yawn generates a standard SKILL.md that works everywhere.

Cursor

.cursor/skills/

Native support

Claude Code

.claude/skills/

Native support

Codex

.codex/skills/

Via SKILL.md

Manus

.manus/skills/

Via SKILL.md

Windsurf

.windsurf/skills/

Via SKILL.md

Any MCP

Custom

Via yawn.ai API

Desired Outcome Matching

The core primitive: describe what you want, get the skill tree needed to achieve it.

POST /api/skills/match

{
  "outcome": "Extract entities from user notes and store them",
  "context": {
    "autonomyLevel": 3,
    "platform": "cursor"
  }
}

Response

{
  "outcome": "Extract entities from user notes...",
  "skillTree": {
    "root": "entity-extract",
    "skills": [...],
    "edges": [...],
    "gaps": [...],
    "executionOrder": ["llm-invoke", "entity-extract", "db-mutate"]
  },
  "summary": {
    "total": 3,
    "closed": 2,
    "partial": 1,
    "missing": 0,
    "healthScore": 83
  }
}

Try the live matcher: yawn.ai/skills

API Reference

GET/api/skills/statusGet all skills with status, grouped by category

POST/api/skills/matchMatch a desired outcome to a skill tree

POST/api/skills/[skillId]/executeExecute a specific skill with input

GET/api/yawn-shop/listList available skills on the Yawn Shop

--- name: entity-extract description: Extract named entities from natural language. version: 1.0.0 category: perception status: active priority: high holarchy-path: yawn/skills/perception/entity-extract handler: lib/skills/handlers/entity-extract.ts required-skills: [llm-invoke] evidence-kind: skill_entity_extract autonomy-level: 3 trust-score: null # Computed by the scorer # .yawn extensions (not in standard SKILL.md) lifecycle: spawn-condition: "When text input contains > 3 potential entities" retire-condition: "Superseded by domain-specific extractor" parent: perception children: [] holarchy: inherits-from: perception overridable: true scope: subtree --- # Entity Extract Extracts named entities (people, organizations, dates, locations, amounts) from natural language text. ## When to Use - Processing user input that references real-world entities - Building knowledge graphs from unstructured text - Populating entity databases from notes or triggers ## Instructions 1. Accept raw text input 2. Run NER via LLM with structured output schema 3. Return typed entity array with confidence scores ## Evidence Every invocation logs a `skill_entity_extract` event with: - Input length, entity count, confidence distribution - Used for trust score computation and gradient analysis

{ "outcome": "Extract entities from user notes...", "skillTree": { "root": "entity-extract", "skills": [...], "edges": [...], "gaps": [...], "executionOrder": ["llm-invoke", "entity-extract", "db-mutate"] }, "summary": { "total": 3, "closed": 2, "partial": 1, "missing": 0, "healthScore": 83 } }