Agent-almanac create-skill

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/de/skills/create-skill" ~/.claude/skills/pjt222-agent-almanac-create-skill-f3ea2a && rm -rf "$T"

manifest: i18n/de/skills/create-skill/SKILL.md

source content

Neuen Skill erstellen

Eine SKILL.md-Datei verfassen, die Agentensysteme verwenden koennen, um ein bestimmtes Verfahren auszufuehren.

Wann verwenden

Kodifizierung eines wiederholbaren Verfahrens, dem Agenten folgen sollen
Hinzufuegen einer neuen Faehigkeit zur Skills-Bibliothek
Konvertierung eines Leitfadens, Runbooks oder einer Checkliste in agentenlesbares Format
Standardisierung eines Workflows ueber Projekte oder Teams hinweg

Eingaben

Erforderlich: Aufgabe, die der Skill erledigen soll

Erforderlich: Domain-Klassifizierung — eine der 48 Domains in

skills/_registry.yml

r-packages

jigsawr

containerization

reporting

compliance

mcp-integration

web-dev

git

general

citations

data-serialization

review

bushcraft

esoteric

design

defensive

project-management

devops

observability

mlops

workflow-visualization

swarm

morphic

alchemy

tcg

intellectual-property

gardening

shiny

animal-training

mycology

prospecting

crafting

library-science

travel

relocation

a2a-protocol

geometry

number-theory

stochastic-processes

theoretical-science

diffusion

hildegard

maintenance

blender

visualization

3d-printing

lapidary

versioning

Erforderlich: Komplexitaetsstufe (basic, intermediate, advanced)
Optional: Quellmaterial (bestehender Leitfaden, Runbook oder funktionierendes Beispiel)
Optional: Verwandte Skills als Querverweise

Vorgehensweise

Schritt 1: Verzeichnis erstellen

Jeder Skill lebt in seinem eigenen Verzeichnis:

mkdir -p skills/<skill-name>/

Benennungskonventionen:

Kleinbuchstaben-Kebab-Case verwenden:
```
submit-to-cran
```
, nicht
```
SubmitToCRAN
```
Mit einem Verb beginnen:
```
create-
```
,
```
setup-
```
,
```
write-
```
,
```
deploy-
```
,
```
configure-
```
Spezifisch sein:
```
create-r-dockerfile
```
, nicht
```
create-dockerfile
```

Erwartet: Verzeichnis

skills/<skill-name>/

existiert und der Name folgt Kleinbuchstaben-Kebab-Case beginnend mit einem Verb.

Bei Fehler: Falls der Name nicht mit einem Verb beginnt, das Verzeichnis umbenennen. Auf Namenskonflikte pruefen:

ls skills/ | grep <keyword>

, um sicherzustellen, dass kein bestehender Skill einen ueberlappenden Namen hat.

Schritt 2: YAML-Frontmatter schreiben

---
name: skill-name-here
description: >
  Ein bis drei Saetze plus wichtige Aktivierungsausloser. Muss klar genug
  sein, damit ein Agent allein anhand der Beschreibung entscheiden kann,
  ob er diesen Skill aktivieren soll. Max. 1024 Zeichen. Mit einem Verb beginnen.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob  # optional, experimentell
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: general
  complexity: intermediate
  language: R | TypeScript | Python | Docker | Rust | multi
  tags: komma, getrennt, kleinbuchstaben, tags
---

Pflichtfelder:

name

description

Optionale Felder:

license

allowed-tools

(experimentell),

metadata

compatibility

Metadatenkonventionen:

```
complexity
```
: basic (< 5 Schritte, keine Randfaelle), intermediate (5-10 Schritte, etwas Urteilsvermoegen), advanced (10+ Schritte, erhebliches Domainwissen)
```
language
```
: Hauptsprache;
```
multi
```
fuer sprachenuebergreifende Skills verwenden
```
tags
```
: 3-6 Tags zur Auffindbarkeit; Domain-Name einbeziehen

Erwartet: YAML-Frontmatter wird fehlerfrei geparst,

name

stimmt mit dem Verzeichnisnamen ueberein und

description

ist unter 1024 Zeichen mit klaren Aktivierungsausloesern.

Bei Fehler: YAML durch Pruefen auf passende

---

-Begrenzer, korrektes Anzeigen von Versionsstrings (z.B.

"1.0"

nicht

1.0

) und korrekte

-Mehrzeilenfaltsyntax fuer das Beschreibungsfeld validieren.

Schritt 3: Titel und Einfuehrung schreiben

# Skill-Titel (Imperativ-Form)

Ein Absatz: was dieser Skill erreicht und den Mehrwert den er bietet.

Der Titel sollte dem

name

entsprechen, aber in menschenlesbarer Form. "Submit to CRAN" nicht "submit-to-cran".

Erwartet: Eine

-Ueberschrift auf oberster Ebene in Imperativform, gefolgt von einem praegnanten Absatz ueber das Ziel des Skills.

Bei Fehler: Falls der Titel als Substantivphrase statt als Verbphrase klingt, umschreiben. "Package Submission" wird zu "Submit to CRAN."

Schritt 4: "Wann verwenden" schreiben

3-5 Ausloesebedingungen auflisten — konkrete Szenarien, in denen ein Agent diesen Skill aktivieren sollte:

## When to Use

- Neues R-Paket von Grund auf starten
- Lose R-Skripte in ein Paket konvertieren
- Paketskelett fuer kollaborative Entwicklung einrichten

Aus der Perspektive des Agenten schreiben. Dies sind die Bedingungen, die der Agent prueft, um die Aktivierung zu entscheiden.

Hinweis: Die wichtigsten Ausloesebedingungen sollten auch im Frontmatter-Feld
description
erscheinen, da dieses waehrend der Entdeckungsphase gelesen wird, bevor der vollstaendige Hauptteil geladen wird. Der Abschnitt
## When to Use
bietet zusaetzliche Details und Kontext.

Erwartet: 3-5 Stichpunkte, die konkrete, beobachtbare Bedingungen beschreiben, unter denen ein Agent diesen Skill aktivieren sollte.

Bei Fehler: Falls Ausloser vage wirken ("wenn etwas getan werden muss"), aus der Agentenperspektive neu schreiben: Welcher beobachtbare Zustand oder welche Benutzeranfrage wuerde die Aktivierung ausloesen?

Schritt 5: "Inputs" schreiben

Erforderliche von optionalen trennen. Typen und Standards genau angeben:

## Inputs

- **Required**: Paketname (Kleinbuchstaben, keine Sonderzeichen ausser `.`)
- **Required**: Einzeilige Beschreibung des Paketzwecks
- **Optional**: Lizenztyp (Standard: MIT)
- **Optional**: Ob renv initialisiert werden soll (Standard: ja)

Erwartet: Der Inputs-Abschnitt trennt klar Erforderliche von optionalen Parametern, jeweils mit einem Typhinweis und Standardwert, wo zutreffend.

Bei Fehler: Falls der Typ eines Parameters mehrdeutig ist, ein konkretes Beispiel in Klammern hinzufuegen: "Paketname (Kleinbuchstaben, keine Sonderzeichen ausser

)".

Schritt 6: "Procedure" schreiben

Dies ist das Herzstuck des Skills. Jeder Schritt folgt diesem Muster:

### Step N: Aktionstitel

Kontextsatz, der erklaert, was dieser Schritt erreicht.

\```language
konkreter_code("den der Agent ausfuehren kann")
\```

**Expected:** Wie Erfolg aussieht. Spezifisch sein — Datei erstellt, Ausgabe stimmt mit Muster ueberein, Befehl beendet sich mit 0.

**On failure:** Wiederherstellungsschritte. Nicht nur "beheben" sagen — die haeufigste Fehlerursache und deren Loesung angeben.

Effektive Schritte schreiben:

Jeder Schritt sollte unabhaengig verifizierbar sein
Tatsaechlichen Code einbeziehen, keine Pseudocodes
Den haeufigsten Pfad zuerst, Randfaelle in "On failure"
5-10 Schritte sind der optimale Bereich. Unter 5 koennten zu vage sein; ueber 12 sollte in mehrere Skills aufgeteilt werden.
Auf echte Werkzeuge und echte Befehle verweisen, keine abstrakten Beschreibungen

Erwartet: Der Procedure-Abschnitt enthaelt 5-12 nummerierte Schritte, jeweils mit konkretem Code, einem

**Expected:**

-Ergebnis und einer

**On failure:**

-Wiederherstellungsmassnahme.

Bei Fehler: Falls einem Schritt Code fehlt, den tatsaechlichen Befehl oder die Konfiguration hinzufuegen. Falls Expected/On failure fehlt, jetzt schreiben — jeder fehlschlagbare Schritt braucht beides.

Schritt 7: "Validation" schreiben

Eine Checkliste, die der Agent nach Abschluss der Vorgehensweise durchfuehrt:

## Validation

- [ ] Kriterium 1 (pruefbar, binaer bestanden/nicht bestanden)
- [ ] Kriterium 2
- [ ] Keine Fehler oder Warnungen in der Ausgabe

Jedes Element muss objektiv pruefbar sein. "Code ist sauber" ist schlecht. "

devtools::check()

gibt 0 Fehler zurueck" ist gut.

Erwartet: Eine Markdown-Checkliste (

- [ ]

) mit 3-8 binaeren Bestanden/Nicht-bestanden-Kriterien, die ein Agent programmatisch oder durch Inspektion pruefen kann.

Bei Fehler: Subjektive Kriterien durch messbare ersetzen. "Gut dokumentiert" wird zu "Alle exportierten Funktionen haben

@param

@return

- und

@examples

-roxygen-Tags."

Schritt 8: "Common Pitfalls" schreiben

3-6 Fallstricke mit Ursache und Vermeidung:

## Common Pitfalls

- **Fallstrickname**: Was schieflaeuft und wie es vermieden wird. Spezifisch ueber Symptom und Loesung sein.

Aus echter Erfahrung schoepfen. Die besten Fallstricke sind solche, die erhebliche Zeit vergeuden und nicht offensichtlich sind.

Erwartet: 3-6 Fallstricke, jeweils mit einem fettgedruckten Namen, einer Beschreibung was schieflaeuft und wie es vermieden wird.

Bei Fehler: Falls Fallstricke generisch wirken ("sei vorsichtig mit X"), sie spezifischer machen: Symptom, Ursache und Loesung benennen. Aus tatsaechlichen Fehlerszenarien waehrend der Entwicklung oder Tests schoepfen.

Schritt 9: "Related Skills" schreiben

2-5 Skills als Querverweise angeben, die haeufig davor, danach oder zusammen mit diesem verwendet werden:

## Related Skills

- `prerequisite-skill` - muss vor diesem Skill durchgefuehrt werden
- `follow-up-skill` - wird haeufig nach diesem Skill durchgefuehrt
- `alternative-skill` - alternativer Ansatz zum gleichen Ziel

Das Feld

name

des Skills verwenden (Kebab-Case), nicht den Titel.

Erwartet: 2-5 verwandte Skills aufgelistet mit Kebab-Case-IDs und kurzen Beschreibungen der Beziehung (Voraussetzung, Nachfolger, Alternative).

Bei Fehler: Pruefen ob jeder referenzierte Skill existiert:

ls skills/<skill-name>/SKILL.md

. Alle Verweise auf Skills entfernen, die umbenannt oder entfernt wurden.

Schritt 10: Zur Registry hinzufuegen

skills/_registry.yml

bearbeiten und den neuen Skill unter der entsprechenden Domain hinzufuegen:

- id: skill-name-here
  path: skill-name-here/SKILL.md
  complexity: intermediate
  language: multi
  description: Einzeilige Beschreibung, die dem Frontmatter entspricht

Den

total_skills

-Zaehler am Anfang der Registry aktualisieren.

Erwartet: Neuer Eintrag erscheint in

skills/_registry.yml

unter der korrekten Domain, und

total_skills

-Zaehler stimmt mit der tatsaechlichen Anzahl der Skill-Verzeichnisse auf der Festplatte ueberein.

Bei Fehler: Skills auf der Festplatte zaehlen mit

find skills -name SKILL.md | wc -l

und gegen

total_skills

in der Registry pruefen. Sicherstellen, dass das Feld

id

genau mit dem Verzeichnisnamen uebereinstimmt.

Schritt 11: Zitate hinzufuegen (Optional)

Falls der Skill auf etablierten Methoden, Forschungsarbeiten, Softwarepaketen oder Standards basiert, Zitations-Unterdateien im

references/

-Verzeichnis hinzufuegen:

mkdir -p skills/<skill-name>/references/

Zwei Dateien erstellen:

references/CITATIONS.bib
— Maschinenlesbares BibTeX (Wahrheitsquelle)
references/CITATIONS.md
— Menschenlesbare gerenderte Referenzen fuer GitHub-Browsing

% references/CITATIONS.bib
@article{author2024title,
  author  = {Author, First and Other, Second},
  title   = {Paper Title},
  journal = {Journal Name},
  year    = {2024},
  doi     = {10.xxxx/xxxxx}
}

Zitate sind optional — hinzufuegen wenn die Herkunftsverfolgung wichtig ist (akademische Methoden, veroffentlichte Standards, Regulierungsrahmen).

Erwartet: Beide Dateien existieren und

.bib

wird als gueltiges BibTeX geparst.

Bei Fehler: BibTeX-Syntax mit

bibtool -d references/CITATIONS.bib

oder einem Online-Validator pruefen.

Schritt 12: Skill validieren

Lokale Validierungspruefungen vor dem Committen durchfuehren:

# Zeilenanzahl pruefen (muss <=500 sein)
lines=$(wc -l < skills/<skill-name>/SKILL.md)
[ "$lines" -le 500 ] && echo "OK ($lines lines)" || echo "FAIL: $lines lines > 500"

# Erforderliche Frontmatter-Felder pruefen
head -20 skills/<skill-name>/SKILL.md | grep -q '^name:' && echo "name: OK"
head -20 skills/<skill-name>/SKILL.md | grep -q '^description:' && echo "description: OK"

Erwartet: Zeilenanzahl <=500, alle Pflichtfelder vorhanden.

Bei Fehler: Falls ueber 500 Zeilen, progressive Disclosure anwenden — grosse Code-Bloecke (>15 Zeilen) in

references/EXAMPLES.md

extrahieren:

mkdir -p skills/<skill-name>/references/

Erweiterte Code-Beispiele, vollstaendige Konfigurationsdateien und Mehrfachvarianten-Beispiele nach

references/EXAMPLES.md

verschieben. Querverweis in SKILL.md hinzufuegen:

See [EXAMPLES.md](references/EXAMPLES.md) for complete configuration examples.

Kurze Inline-Ausschnitte (3-10 Zeilen) im Haupt-SKILL.md behalten.

Schritt 13: Slash-Command-Symlinks erstellen

Symlinks erstellen, damit Claude Code den Skill als

/slash-command

entdeckt:

# Projektebene (in diesem Projekt verfuegbar)
ln -s ../../skills/<skill-name> .claude/skills/<skill-name>

# Global (in allen Projekten verfuegbar)
ln -s /mnt/d/dev/p/agent-almanac/skills/<skill-name> ~/.claude/skills/<skill-name>

Erwartet:

ls -la .claude/skills/<skill-name>/SKILL.md

loest sich zur Skill-Datei auf.

Bei Fehler: Pruefen ob der relative Pfad korrekt ist. Von

.claude/skills/

aus sollte der Pfad

../../skills/<skill-name>

das Skill-Verzeichnis erreichen.

readlink -f

verwenden, um Symlink-Auflosung zu debuggen.

Schritt 14: Uebersetzungen anlegen

Erforderlich fuer alle Skills. Dieser Schritt gilt sowohl fuer menschliche Autoren als auch fuer KI-Agenten, die dieser Vorgehensweise folgen. Nicht ueberspringen — fehlende Uebersetzungen sammeln sich zu einem veralteten Backlog an.

Unmittelbar nach dem Committen des neuen Skills Uebersetzungsdateien fuer alle 4 unterstuetzten Locales anlegen:

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- skills <skill-name> "$locale"
done

Anschliessend die angelegte Prosa in jeder Datei uebersetzen (Code-Bloecke und IDs bleiben auf Englisch). Abschliessend die Statusdateien neu generieren:

npm run translation:status

Erwartet: 4 Dateien unter

i18n/{de,zh-CN,ja,es}/skills/<skill-name>/SKILL.md

erstellt, alle mit

source_commit

, der dem aktuellen HEAD entspricht.

npm run validate:translations

zeigt 0 Stale-Warnungen fuer den neuen Skill.

Bei Fehler: Falls das Scaffolding fehlschlaegt, vor dem Anlegen pruefen ob der Skill in

skills/_registry.yml

existiert — das Skript liest die Registry. Falls

translation:status

die neuen Dateien als veraltet anzeigt, pruefen ob

source_commit

mit dem Commit-Hash uebereinstimmt, an dem die englische Quelle zuletzt geaendert wurde.

Validierung

SKILL.md existiert unter
```
skills/<skill-name>/SKILL.md
```
YAML-Frontmatter wird fehlerfrei geparst
Feld
```
name
```
stimmt mit dem Verzeichnisnamen ueberein
```
description
```
ist unter 1024 Zeichen
Alle Pflichtabschnitte vorhanden: When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills
Jeder Vorgehensweise-Schritt hat konkreten Code und Expected/On-failure-Paare
Related Skills verweisen auf gueltige Skill-Namen
Skill ist in
```
_registry.yml
```
mit korrektem Pfad aufgefuehrt
```
total_skills
```
-Zaehler in der Registry ist aktualisiert
SKILL.md ist <=500 Zeilen (bei Ueberschreitung nach
```
references/EXAMPLES.md
```
extrahieren)
Zitate zu
```
references/CITATIONS.bib
```
+
```
CITATIONS.md
```
hinzugefuegt, falls Skill auf veroffentlichten Methoden basiert
Symlink existiert unter
```
.claude/skills/<skill-name>
```
, der auf das Skill-Verzeichnis zeigt
Globaler Symlink existiert unter
```
~/.claude/skills/<skill-name>
```
(falls global verfuegbar)

Haeufige Stolperfallen

Vage Vorgehensweisen: "System entsprechend konfigurieren" ist fuer einen Agenten nutzlos. Genaue Befehle, Dateipfade und Konfigurationswerte angeben.
Fehlendes On failure: Jeder fehlschlagbare Schritt braucht Wiederherstellungsanleitung. Agenten koennen nicht improvisieren — das Fallback muss ausgeschrieben sein.
Zu breiter Umfang: Ein Skill, der "gesamte Entwicklungsumgebung einrichten" abdecken will, sollte 3-5 fokussierte Skills sein. Ein Skill = eine Vorgehensweise.
Nicht pruefbare Validierung: "Codequalitaet ist gut" kann nicht verifiziert werden. "Linter besteht mit 0 Warnungen" kann es.
Veraltete Querverweise: Beim Umbenennen oder Entfernen von Skills nach dem alten Namen in allen Related-Skills-Abschnitten suchen.
Beschreibung zu lang: Das Beschreibungsfeld ist das, was Agenten lesen, um die Aktivierung zu entscheiden. Unter 1024 Zeichen halten und Schluesselinformationen voranzustellen.
git mv
auf NTFS-gemounteten Pfaden vermeiden (WSL): Auf
```
/mnt/
```
-Pfaden kann
```
git mv
```
fuer Verzeichnisse fehlerhafte Berechtigungen erstellen. Stattdessen
```
mkdir -p
```
+ Dateien kopieren +
```
git rm
```
des alten Pfades verwenden.

Beispiele

Ein gut strukturierter Skill folgt dieser Qualitaetscheckliste:

Ein Agent kann anhand der Beschreibung allein entscheiden, ob er ihn verwenden soll
Der Vorgehensweise kann mechanisch ohne Mehrdeutigkeit gefolgt werden
Jeder Schritt hat ein pruefbares Ergebnis
Fehlermodi haben konkrete Wiederherstellungspfade
Der Skill kann mit verwandten Skills zusammengestellt werden

Groessensreferenz aus dieser Bibliothek:

Grundlegende Skills: ~80-120 Zeilen
Mittlere Skills: ~120-180 Zeilen
Fortgeschrittene Skills: ~180-250 Zeilen
Skills mit erweiterten Beispielen: SKILL.md <=500 Zeilen +
```
references/EXAMPLES.md
```