Skill-System

源码版本v2026.7.20

Verantwortung

Ein Skill ist eine stärkere Fähigkeitseinheit als ein Tool (tool): ein wiederverwendbarer, mit Frontmatter versehener Fluss (ähnlich der agentskills.io-Spezifikation), nach Domäne geordnet unter skills/<category>/. Im Gegensatz zu «statischen Funktionen» können Skills von der Lernschleife erzeugt, umgeschrieben und verfeinert werden; sie sind der Träger, der den Agenten «mit der Nutzung klüger» macht. Skills werden über skills_tool der Hauptschleife zum Aufruf freigegeben.

Designmotiv

Warum Skills nach category in Unterverzeichnisse legen statt flach? Die Zahl der Skills wächst mit der Nutzung (vom User hinzugefügte, aus dem Hub synchronisierte, von der Lernschleife generierte — alles unter ~/.hermes/skills/); flach wird die von skills_list zurückgegebene Liste schnell zum Rauschen. category erlaubt der ersten Stufe der Progressive Disclosure nur «hier ist eine Gruppe research-Skills» zu zeigen statt 50 einzelner Skill-Namen. Jede SKILL.md ist eine einzelne, selbstgenügsame Definitionsdatei (mit Frontmatter); zusammen mit den Subdateien unter skills/<category>/<skill>/references/ wird on-demand geladen, sodass die Token nicht auf einmal explodieren.

Bundle ist eine weitere Hüllschicht: mehrere Skills über einen einzigen Slash-Befehl laden, denn ein Szenario wie «Backend-Entwicklung» will gleichzeitig Code-Review, TDD und PR-Skills aktivieren — jedes einzeln per /skill zu laden, wäre zu zerstückelt.

Schlüsseldateien

• skills/-Verzeichnis — nach Domäne gruppiert (apple, computer-use, research, software-development, yuanbao…); jeder Skill sieht so aus:

skills/
├── my-skill/
│   ├── SKILL.md           # Hauptanweisung (erforderlich)
│   ├── references/        # Stütz-Dokumente
│   │   ├── api.md
│   │   └── examples.md
│   ├── templates/         # Ausgabe-Templates
│   └── assets/            # Anhänge (agentskills.io-Standard)
└── category/
    └── another-skill/
        └── SKILL.md

Oben in SKILL.md steht YAML-Frontmatter (name/description/version/platforms/prerequisites…), darunter der Anweisungstext. name ist auf 64 Zeichen, description auf 1024 begrenzt; diese beiden Felder sind die einzige Rückgabe der ersten Stufe von skills_list der Progressive Disclosure — Token sparen.

• skills_tool — gibt Skills als Werkzeug an die Hauptschleife frei. Registriert zwei Werkzeuge:

registry.register(
    name="skills_list",
    toolset="skills",
    schema=SKILLS_LIST_SCHEMA,
    handler=lambda args, **kw: skills_list(
        category=args.get("category"), task_id=kw.get("task_id")
    ),
    check_fn=check_skills_requirements,
    emoji="📚",
)

registry.register(
    name="skill_view",
    toolset="skills",
    schema=SKILL_VIEW_SCHEMA,
    handler=_skill_view_with_bump,
    check_fn=check_skills_requirements,
    emoji="📚",
)

skills_list liefert nur name + description + category (erste Stufe der Progressive Disclosure); skill_view lädt die vollständige SKILL.md (zweite Stufe); Stützdateien wie references/templates werden on-demand per skill_view(name, file_path="references/api.md") gezogen (dritte Stufe). _skill_view_with_bump ruft nach Erfolg bump_view / bump_use auf und aktualisiert den Nutzungszähler; darüber entscheidet der Stale-Timer des Curators, welche Skills niemand mehr nutzt und weggeräumt werden.

• skill_manager_tool — Skill-Verwaltung (auflisten/ansehen/aktivieren)
• skills_hub — Synchronisation mit der Skill-Hub (agentskills.io-kompatibel)
• skills_sync — lokaler/Remote-Skill-Abgleich
• skill_bundles — Skill-Bündelung, Injektion in den Prompt (prompt). Ein Bundle ist eine kleine Datei unter ~/.hermes/skill-bundles/*.yaml:

name: backend-dev
description: Backend feature work — code review, testing, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Optional extra guidance to inject above the skill bodies.

/<bundle-name> ruft build_bundle_invocation_message auf und fügt die SKILL.md aller Mitglieds-Skills zu einer einzigen User-Nachricht zusammen. Haben Bundle und Skill denselben Namen, gewinnt das Bundle — wer explizit denselben Namen vergibt, will den zufällig gleichnamigen Skill überdecken. Fehlende Mitglieds-Skills werfen keinen Fehler, sondern werden mit einem Hinfeld versehen, welche übersprungen wurden.

• skill_preprocessing — Vorverarbeitung von Skill-Inhalten. Ersetzt Template-Variablen ${HERMES_SKILL_DIR} / ${HERMES_SESSION_ID} und führt Inline-Shell-Snippets wie !date +%Y-%m-%d`` aus. Schlägt ein Inline-Shell fehl, wird statt einer Exception der Marker [inline-shell error: ...] zurückgegeben — ein kaputtes Snippet reißt nicht die ganze Skill-Nachricht mit.
• Skill-Knoten und Kanten:125-193 — build_skill_nodes / build_edges, organisiert Skills als Lern-Graph

Datenfluss

1. Beim Start scannt skill_preprocessing (agent/skill_preprocessing.py) das Verzeichnis skills/<category>/ und liest Frontmatter.
2. skill_bundles (agent/skill_bundles.py) bündelt relevante Skills und injiziert sie über build_turn_context:268 in den aktuellen Prompt.
3. Der Provider (provider) entscheidet, einen Skill aufzurufen → tool_call skills → tools/skills_tool.py lädt und führt den Skill-Fluss aus.
4. Das Ausführungsergebnis wird in die Hauptschleife zurückgefüllt.
5. Die Lernschleife betrachtet den Turn (turn) im Hintergrund und kann:
   • neue Skills erzeugen (learning_mutations)
   • den neuen Skill im Lern-Graph agent/learning_graph.py:125 registrieren
   • über tools/skills_sync.py mit dem Skill-Hub synchronisieren

Grenzen und Fehler

• Pfad-Traversal: Der Skill-Name wird an ~/.hermes/skills/ angehängt, um die Datei zu finden; _skill_lookup_path_error weist ..-Segmente, absolute Pfade und Windows-Laufwerksbuchstaben zurück. Sonst könnte name="../outside" Dateien außerhalb des Skill-Verzeichnisses lesen.
• Prompt-Injection: SKILL.md-Inhalte mit Mustern wie «ignore previous instructions», «system prompt:», «]]>» werden über _INJECTION_PATTERNS markiert. Drittanbieter-Skills (aus dem Hub synchronisiert) sind nicht vertrauenswürdig; beim Laden in die Hauptschleife wird sanitisiert.
• Bundle fehlt ein Mitglied: build_bundle_invocation_message notiert fehlende oder deaktivierte Mitglieds-Skills nur in einer missing- bzw. disabled-Liste und bricht nicht ab — ein Bundle lädt nachsichtig; ein paar fehlende Mitglieder beeinträchtigen den Rest nicht.
• Cache veraltet: Der Scan von skills/ kostet O(#dirs) stat; die Signatur enthält Verzeichnis-mtime, disabled-Set und Plattform. Aber eine direkte Änderung an einer SKILL.md bumpert nur ihre eigene mtime, die Verzeichnis-Signatur merkt das nicht — deshalb gibt es als Auffang zusätzlich einen TTL von 30 Sekunden.

Zusammenfassung

Skill = evolvierbarer höherer Fluss, beschrieben durch Frontmatter, definiert als Datei, umgeschrieben durch die Lernschleife. Verhältnis zu Tools: Tools sind die Atome innerhalb eines Skill-Flusses, Skills sind das Wissen «wie man Tools kombiniert, um eine Klasse von Aufgaben zu erledigen». Zum Evolutionsmechanismus der Skills siehe Lernschleife.