# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-12 (Claude Opus 4.6)
# Nächste Prüfung: 2026-09-12
# Ressourcen: [skill_init.py, skills table]

ANTHROPIC / AGENTSKILLS.IO SKILL-STANDARDS
==========================================

Stand: 2026-03-12

Anthropic und agentskills.io definieren einen offenen Standard für
KI-Skills, der von Claude Code, Codex CLI, Cursor, ChatGPT und
weiteren Plattformen unterstützt wird. Dieser Standard erlaubt es,
Skills plattformübergreifend zu verteilen und zu installieren.

BACH unterstützt diesen Standard nativ und kann bestehende Skills
in das Anthropic-kompatible Format exportieren.


STANDARD-VERZEICHNISSTRUKTUR
-----------------------------
Ein Anthropic-kompatibler Skill ist ein Ordner mit folgender Struktur:

  my-skill/
  +-- SKILL.md              # Hauptdefinition (Pflicht)
  +-- scripts/              # Ausführbare Skripte (optional)
  |   +-- setup.sh
  |   +-- run.py
  +-- references/           # Referenz-Dokumentation (optional)
  |   +-- core-overview.md
  |   +-- features-api.md
  |   +-- best-practices-testing.md
  |   +-- advanced-caching.md
  +-- assets/               # Statische Dateien (optional)
      +-- logo.png
      +-- config-template.json


SKILL.MD -- YAML-FRONTMATTER
-----------------------------
Jede SKILL.md beginnt mit einem YAML-Frontmatter-Block:

  ---
  name: my-skill-name
  description: >
    Kurze Beschreibung der Fähigkeit, die dieser Skill bereitstellt.
    Maximal 1024 Zeichen.
  license: MIT
  compatibility:
    - claude-code
    - codex-cli
  metadata:
    author: lukisch
    version: 1.0.0
    tags: [automation, code-review]
  allowed-tools:
    - Bash
    - Read
    - Edit
  ---

Pflichtfelder:
  name            Max 64 Zeichen, kebab-case (a-z, 0-9, Bindestrich)
  description     Max 1024 Zeichen, Freitext

Optionale Felder:
  license         Lizenz-Bezeichner (MIT, Apache-2.0, etc.)
  compatibility   Liste kompatibler Plattformen
  metadata        Freies Key-Value für Autor, Version, Tags etc.
  allowed-tools   Whitelist der Tools, die der Skill nutzen darf

Nach dem Frontmatter folgt der eigentliche Skill-Body als Markdown.


PROGRESSIVE DISCLOSURE (3 STUFEN)
----------------------------------
Der Standard nutzt ein dreistufiges Ladeverfahren, um Token-Budgets
effizient zu nutzen:

  Stufe 1 -- Metadaten (~100 Tokens)
    Nur Frontmatter (name, description, metadata).
    Wird beim Browsen/Suchen geladen. Erlaubt dem LLM zu entscheiden,
    ob der Skill relevant ist, ohne den Body zu lesen.

  Stufe 2 -- SKILL.md Body (< 5000 Tokens)
    Der vollständige Instruktions-Text der SKILL.md.
    Wird geladen, wenn der Skill aktiviert/installiert wird.
    Enthält alle Regeln, Workflows und Anweisungen.

  Stufe 3 -- Bundled Resources (on demand)
    Dateien aus references/, scripts/ und assets/.
    Werden nur geladen, wenn der Skill sie explizit anfordert
    oder das LLM sie für die aktuelle Aufgabe benötigt.

Dieses Verfahren hält den initialen Token-Verbrauch niedrig und
skaliert erst bei Bedarf.


REFERENCE-FILES BENENNUNG
--------------------------
Dateien im references/-Ordner folgen einer Namenskonvention:

  core-*.md              Grundlegende Konzepte und Übersicht
  features-*.md          Feature-Dokumentation und API-Referenz
  best-practices-*.md    Empfohlene Vorgehensweisen
  advanced-*.md          Fortgeschrittene Themen und Optimierung

Beispiele:
  references/core-overview.md
  references/features-query-api.md
  references/best-practices-error-handling.md
  references/advanced-performance-tuning.md

Diese Konvention erlaubt es LLMs, gezielt nach der richtigen
Detailtiefe zu suchen.


BACH-UNTERSTÜTZUNG
--------------------
BACH kann Anthropic-kompatible Skills direkt scaffolden:

  bach skills create <name> --format anthropic

Dieser Befehl nutzt intern skill_init.py und erstellt:
- SKILL.md mit korrektem Frontmatter
- scripts/ Ordner (leer)
- references/ Ordner (leer)
- assets/ Ordner (leer)

Bestehende BACH-Skills können exportiert werden:

  bach skills export <name> --format anthropic

Der Export konvertiert den BACH-internen Header in
Anthropic-kompatibles Frontmatter und reorganisiert die Dateien.


VERGLEICH: BACH-INTERN VS ANTHROPIC-KOMPATIBEL
------------------------------------------------

  Aspekt              BACH-intern              Anthropic-Standard
  -----------------   ---------------------    ----------------------
  Hauptdatei          SKILL.md                 SKILL.md
  Header              YAML (erweitert)         YAML (Frontmatter)
  Name-Feld           name (frei)              name (kebab-case, 64Z)
  Typ-Feld            type (Pflicht)           -- (nicht vorhanden)
  Version             version (Pflicht)        metadata.version (opt.)
  Abhängigkeiten     dependencies (Pflicht)   -- (nicht formalisiert)
  Tools               Im Skill-Ordner          scripts/
  Doku                Im Skill-Ordner          references/
  Statische Dateien   data/ oder assets/       assets/
  Workflows           _workflows/ oder lokal   In SKILL.md Body
  DB-Sync             Ja (skills table)        Nein
  Export              bach skills export        Natives Format

BACH-interne Skills haben mehr Metadaten (type, dependencies,
trigger_phrases), die beim Export in metadata-Felder übertragen
werden. Anthropic-kompatible Skills sind schlanker, aber weniger
ausdrücklich.


SKILLS VS. AGENTS (ANTHROPIC)
------------------------------
Im Anthropic-Oekosystem sind Skills und Agents zwei separate Konzepte:

  Skill:  Offener Standard (agentskills.io), portierbar
          Definiert in: .claude/skills/<name>/SKILL.md
          Zweck: Instruktionen, Wissen, Workflows

  Agent:  Proprietaer (nur Claude Code / Agent SDK)
          Definiert in: .claude/agents/<name>.md
          Zweck: Isolierte Ausführung, eigenes Context Window

Agents werden NICHT im Skill-Ordner definiert. Sie können aber
zusammenarbeiten:

  - Skill kann Agent auslösen:  context: fork + agent: <name>
  - Agent kann Skills vorladen:  skills: [my-skill]

Für LobeHub/Marketplace ist nur der Skill-Export relevant (offen,
portierbar). Claude Code Agents sind optional und nicht portierbar.

Beim Export von BACH-Agenten:
  - Sub-Agent-Definitionen -> references/
  - Orchestrierungs-Code -> scripts/
  - Optional: .claude/agents/<name>.md für Claude Code Nutzer


SIEHE AUCH
----------
  bach help skills              BACH Skills System (Architektur v2.0)
  bach help skill_export        Export bestehender Skills
  bach help naming              Namenskonventionen
  bach wiki lobehub             LobeHub Marketplace
  docs/help/skills.txt          Detaillierte Skill-Dokumentation
  wiki/skills_board.txt         Skills Board GUI
