writing-skills

Übersicht

Was die writing-skills Skill macht

Die writing-skills Skill ist eine Meta-Skill für alle, die andere Skills für Agenten wie Claude schreiben, verfeinern und testen. Sie überträgt klassische Test-Driven Development (TDD) auf Prozessdokumentation, sodass Ihre Skills:

• auf realen Druckszenarien basieren
• anhand tatsächlicher Agentenfehler verifiziert werden
• so nachgeschärft werden, dass sie Schlupflöcher schließen und Rationalisierungen widerstehen

Sie nutzen writing-skills, um Skills so zu entwerfen, dass Agenten sie entdecken, befolgen und auch unter Zeitdruck, Sunk-Cost-Bias oder widersprüchlichen Anreizen weiter befolgen.

Für wen writing-skills gedacht ist

Verwenden Sie die writing-skills Skill, wenn Sie:

• Developer sind, die Skills für Claude oder ähnliche Agenten erstellen
• Team Lead sind und Workflows in ~/.claude/skills oder ~/.agents/skills/ standardisieren
• Verantwortliche für Dokumentation sind, deren Skills tatsächlich befolgt werden müssen – nicht nur gelesen
• Tester sind, die prüfen, ob Skills das Agentenverhalten vor dem Rollout wirklich verändern

Der Fokus liegt nicht auf generellem Schreibstil. Es geht konkret um das Schreiben wirksamer, testbarer Agent-Skills.

Probleme, bei denen diese Skill hilft

writing-skills ist für Situationen konzipiert, in denen:

• Agenten Ihre Skills unter Druck ignorieren oder nur teilweise befolgen
• Sie unsicher sind, ob eine neue Skill das Verhalten wirklich verändert
• Sie eine wiederholbare Methode brauchen, um Skills mit Subagents zu testen, bevor sie live gehen
• Sie sich ohne Ratespiel an Anthropic Best Practices für Skill Authoring ausrichten möchten
• Sie komplexe Skill-Workflows mit Graphviz visualisieren und kommunizieren müssen

Wenn Ihre Skills sich eher wie einmalige Stories oder Notizen verhalten, hilft writing-skills, sie in wiederverwendbare, testbare Referenz-Guides zu überführen.

Wann writing-skills passt – und wann nicht

Gute Eignung:

• Skills, die Disziplin erzwingen (TDD, Verifikation, Review-Checklisten)
• Skills mit spürbarem Compliance-Aufwand (Zeit, Rework, verzögertes Shipping)
• Skills, die Agenten gerne umgehen würden ("nur dieses eine Mal")
• Skills, bei denen Sie messbare Verbesserungen der Compliance-Rate wollen

Keine gute Eignung:

• Reine Referenz-Skills (z. B. API-Syntax, einfache Language Cheatsheets)
• Skills, die bewusst keine regelverletzbaren Vorgaben enthalten
• Leichte Notizen, bei denen Sie weder TDD-Tests noch Druckszenarien benötigen

Wenn Sie nur eine schnelle, informelle Notiz für ein einziges Gespräch brauchen, benötigen Sie writing-skills wahrscheinlich nicht. Wenn Sie eine Skill wollen, die Produktionsdruck übersteht, schon.

Verwendung

Installation und Basiskonfiguration

So installieren Sie die writing-skills Skill in einer skills-fähigen Umgebung:

npx skills add https://github.com/obra/superpowers --skill writing-skills

Damit wird die writing-skills Skill aus dem obra/superpowers Repository geladen und neben Ihren anderen Skills registriert.

Persönliche Skills liegen in der Regel in agent-spezifischen Verzeichnissen, zum Beispiel:

• ~/.claude/skills/ für Claude Code
• ~/.agents/skills/ für Codex oder ähnliche Agenten

Legen Sie das writing-skills Verzeichnis unter dem relevanten Skills-Root ab oder prüfen Sie, ob es dort vorhanden ist, damit Ihr Agent bei Bedarf SKILL.md und zugehörige Dateien laden kann.

Wichtige Dateien und Ordner in writing-skills

Nach der Installation sollten Sie diese Dateien zuerst öffnen, um Workflow und Konzept zu verstehen:

• SKILL.md – Zentrale Skill-Definition und Übersicht zu writing-skills, inklusive TDD-Mapping für Skills.
• anthropic-best-practices.md – Guidance im Stil offizieller Dokumentation zum Schreiben prägnanter, auffindbarer und wirksamer Skills für Claude.
• testing-skills-with-subagents.md – Praxisleitfaden für Aufbau und Durchführung von Druckszenarien und Testkampagnen.
• persuasion-principles.md – Evidenzbasierte Persuasionsmuster, um die Agenten-Compliance mit Ihren Skills zu erhöhen.
• graphviz-conventions.dot – Konventionen zur Darstellung von Skill-Workflows und Prozessen als Graphviz-Diagramme.
• render-graphs.js – Hilfsskript, das ```dot Blöcke aus SKILL.md extrahiert und als SVG-Diagramme rendert.
• examples/CLAUDE_MD_TESTING.md – Vollständig durchgearbeitetes Beispiel für eine Testkampagne mit Varianten der CLAUDE.md Dokumentation.

Zusammen bieten diese Dateien einen vollständigen Workflow aus Authoring + Testing + Visualisierung für Skills.

Kernworkflow: TDD für Skills

writing-skills überträgt TDD-Konzepte direkt auf das Schreiben von Skills. Die Schleife auf hoher Ebene lautet:

1. Testfälle schreiben (Druckszenarien)

   • Entwerfen Sie realistische Situationen, in denen ein Agent versucht, Ihren vorgesehenen Prozess zu umgehen oder zu verbiegen.
   • Nutzen Sie Subagents, um diese Szenarien auszuführen und ihr Verhalten zu protokollieren.

2. Baseline-Tests laufen lassen und scheitern sehen

   • Führen Sie die Szenarien ohne Ihre neue oder aktualisierte Skill aus.
   • Erfassen Sie, wo der Agent scheitert: was er auslässt, rationalisiert oder missversteht.

3. Die Skill schreiben oder verfeinern

   • Entwerfen oder aktualisieren Sie SKILL.md und unterstützende Dateien so, dass sie die beobachteten Fehler gezielt adressieren.
   • Verwenden Sie präzise, imperative Sprache, die zu den Grenzen des Context Windows passt.

4. Tests erneut mit geladener Skill ausführen

   • Führen Sie dieselben Szenarien erneut aus – diesmal mit aktiver Skill.
   • Prüfen Sie, ob der Agent die Skill jetzt entdeckt, ankündigt und befolgt.

5. Refactoring, um Schlupflöcher zu schließen

   • Identifizieren Sie verbleibende Rationalisierungen oder Teil-Compliance.
   • Nutzen Sie Persuasionsprinzipien (Authority, Commitment etc.), um die Befolgung zu stärken.
   • Entfernen Sie überflüssige Tokens, um die Skill schlank zu halten.

Diese Schleife entspricht RED → GREEN → REFACTOR im klassischen TDD, angewandt auf Dokumentation und Prozessorzwingung statt auf Code.

anthropic-best-practices.md für bessere Skills nutzen

Die Datei anthropic-best-practices.md bietet Claude-spezifische Guidance, darunter:

• Warum konzise Skills die Context-Nutzung und Modell-Performance verbessern
• Wie und wann Claude SKILL.md und andere Dateien ins Context Window lädt
• Wie Sie Skill-Sektionen so schreiben, dass sie ihren Token-Kosten gerecht werden

Sie können die Datei als Checkliste für Ihre eigenen Skills verwenden:

• Entfernen Sie Erklärungen, die Claude bereits kennt
• Fokussieren Sie sich auf handhabbare Patterns, Regeln und Workflows
• Strukturieren Sie Skills so, dass die wichtigsten Anweisungen früh und klar erscheinen

In Kombination mit der TDD-Schleife aus writing-skills stellen Sie sicher, dass Ihre Skills sowohl auffindbar als auch effizient sind.

Skills mit Subagents testen

Die Datei testing-skills-with-subagents.md erweitert den TDD-Ansatz um eine konkrete Testmethodik:

• Entwerfen Sie Szenarien, die echten Produktionsdruck imitieren (Zeit, Sunk Cost, Speed vs. Quality).
• Führen Sie sie mit Subagents aus, die das Verhalten Ihres Hauptagents abbilden.
• Erfassen Sie Fehler und Rationalisierungen in strukturierten Formaten.

Das ist besonders hilfreich für Skills, die:

• zeitaufwendige Best Practices durchsetzen (z. B. zuerst Tests schreiben)
• mit kurzfristigen Zielen konkurrieren (z. B. schneller shippen vs. gründlich verifizieren)
• stabil bleiben müssen, selbst wenn Nutzer ausdrücklich nach Abkürzungen fragen

Wenn Sie den Testmustern in dieser Datei folgen, können Sie Skills unter Druck verifizieren, bevor sie Endnutzer erreichen.

Persuasionsprinzipien im Skill-Design anwenden

persuasion-principles.md fasst psychologische Prinzipien zusammen, die auch LLM-Verhalten beeinflussen, zum Beispiel:

• Authority – Klare, nicht verhandelbare Formulierungen für sicherheitskritische Regeln
• Commitment – Agenten dazu verpflichten, anzukündigen, wenn sie eine Skill nutzen, und einem gewählten Pfad treu zu bleiben
• Scarcity u. a. – Sorgfältig eingesetzt, um kritische Praktiken zu priorisieren

In der Praxis können Sie:

• für nicht optionale Schritte deutlich zwingendere Formulierungen nutzen
• den Agent explizit sagen lassen: "I am using [Skill Name] now", wenn eine Skill aktiv ist
• Checklisten so entwerfen, dass sie zur Abarbeitung zwingen, statt nur passiv gelesen zu werden

Ziel ist keine Manipulation, sondern sicherzustellen, dass kritische Praktiken konsequent befolgt werden.

Skill-Flows mit Graphviz visualisieren

Komplexe Skills profitieren oft von einer visuellen Darstellung. writing-skills enthält:

• graphviz-conventions.dot – Vorgeschlagene Struktur und Stil für Diagramme
• render-graphs.js – Ein Node.js-Skript, das ```dot Blöcke aus SKILL.md extrahiert und in SVG-Dateien umwandelt.

Grundlegende Nutzung des Renderers:

./render-graphs.js path/to/your/skill
# oder
./render-graphs.js path/to/your/skill --combine

Das hilft Ihnen dabei:

• den Flow einer Skill gegenüber menschlichen Stakeholdern zu vermitteln
• Lücken oder Schleifen in Ihrem Prozessdesign zu erkennen
• Dokumentation und Visualisierungen synchron zu halten, indem Sie Diagramme als ```dot Codeblöcke in SKILL.md einbetten.

writing-skills an Ihre Umgebung anpassen

Das Repository beschreibt Patterns, die Sie anpassen sollten – nicht blind kopieren. Bei der Integration von writing-skills in Ihren eigenen Workflow:

• Behalten Sie die TDD-Schleife bei, passen Sie aber Format und Struktur der Szenarien an Ihre Tools an
• Nutzen Sie bei Bedarf Ihre eigene Verzeichnisstruktur, solange Skill-Grenzen klar bleiben
• Binden Sie Testkampagnen in bestehende CI-, Review- oder Release-Prozesse ein

Ziel ist ein wiederholbarer, testgetriebener Authoring-Workflow, der zu Ihrem Team und Ihrer Infrastruktur passt.

FAQ

Wann sollte ich die writing-skills Skill laden?

Nutzen Sie writing-skills immer dann, wenn Sie:

• eine neue Skill erstellen, die unter ~/.claude/skills oder ähnlichen Verzeichnissen leben soll
• eine bestehende Skill überarbeiten, die ausfranst oder ignoriert wird
• eine Skill für den Rollout an Teammitglieder oder für den Produktionseinsatz vorbereiten
• eine Testkampagne für Skills mit Subagents entwerfen oder durchführen

Wenn Sie nur in einer einzelnen, kurzlebigen Session experimentieren, benötigen Sie den kompletten writing-skills Workflow möglicherweise nicht.

Muss ich TDD verstehen, bevor ich writing-skills nutze?

Ja. Die Skill setzt Vertrautheit mit superpowers:test-driven-development ausdrücklich voraus. writing-skills geht davon aus, dass Sie den RED → GREEN → REFACTOR Zyklus bereits kennen und überträgt ihn dann auf Dokumentation:

• RED: Szenarien ohne Skill ausführen, Fehler erfassen
• GREEN: Skill ergänzen oder verfeinern, damit diese Szenarien bestehen
• REFACTOR: Klarheit verbessern, Schlupflöcher schließen und Tokenkosten reduzieren

Wenn TDD neu für Sie ist, laden und studieren Sie zuerst die TDD-bezogene Skill.

Wie hilft writing-skills bei Claude-spezifischem Verhalten?

writing-skills ist für Umgebungen wie Claude ausgelegt. Das Repository enthält anthropic-best-practices.md mit Guidance, die sich an der Anthropic-Dokumentation orientiert. Zusammen helfen sie Ihnen:

• Skills zu schreiben, die Claude zuverlässig discovern kann
• das Context Window und das Token-Budget zu respektieren
• SKILL-Dateien so zu strukturieren, dass Claude sie effektiv lädt und nutzt

Damit ist writing-skills besonders hilfreich, wenn Sie eine Claude-Skill-Bibliothek aufbauen.

Kann ich writing-skills für nicht-technische oder nicht Code-bezogene Skills nutzen?

Ja, solange die Skill einen wiederholbaren Prozess beschreibt, der per Szenarien testbar ist. Beispiele:

• Incident-Response-Checklisten
• Code-Review-Workflows
• Prozesse zur Dokumentationsprüfung oder -freigabe

Wichtig ist, dass der Prozess:

• klare Regeln hat, die Agenten befolgen oder verletzen können
• reale Konsequenzen hat, wenn Schritte ausgelassen werden
• Szenarien bietet, in denen Sie Compliance sinnvoll testen können

Rein beschreibende oder narrative Inhalte sind keine gute Passung.

Wozu dient die Datei examples/CLAUDE_MD_TESTING.md?

examples/CLAUDE_MD_TESTING.md ist ein vollständig durchgearbeitetes Beispiel, das zeigt, wie Sie:

• realistische Szenarien entwerfen (Zeitdruck, Sunk Cost, Authority vs. Speed)
• sie gegen verschiedene CLAUDE.md Dokumentationsvarianten laufen lassen
• vergleichen, wie gut jede Variante zu Skill Discovery und Nutzung führt

Nutzen Sie sie als Template, wenn Sie eigene Skill-Testkampagnen entwerfen.

Worin unterscheidet sich eine Skill von einer Story oder Case Study?

Im writing-skills Modell gilt:

• Eine Skill ist ein wiederverwendbarer Referenz-Guide, der erprobte Patterns, Tools oder Workflows kodiert.
• Eine Story oder Case Study beschreibt, wie Sie einmal ein konkretes Problem gelöst haben.

writing-skills hilft Ihnen, von einmaligen Stories zu verallgemeinerten, testbaren Skills zu wechseln, die zukünftige Agenten in neuen Situationen finden und anwenden können.

Was, wenn meine Skill lang ist – spielt das eine Rolle?

Die Länge ist wichtig wegen des Context Windows. anthropic-best-practices.md erklärt, warum kompakte Skills besser performen:

• Zunächst wird nur Metadata geladen, aber sobald SKILL.md gelesen wird, konkurriert jedes Token mit der Gesprächshistorie.
• Sie sollten fortlaufend prüfen, ob jeder Abschnitt seinen Platz verdient.

writing-skills ermutigt Sie dazu:

• redundante Erklärungen zu kürzen
• Beispiele bei Bedarf in unterstützende Dateien auszulagern
• SKILL.md auf den Kernprozess und die Regeln zu fokussieren, die Ihre Tests bestehen lassen

Woran erkenne ich, dass writing-skills wirkt?

Sie sehen Wirkung, wenn:

• Skills, die früher unter Druck ignoriert wurden, jetzt befolgt werden
• neue Skills mit expliziten Szenarien und Tests kommen – nicht nur mit Text
• Sie für bestimmte Szenarien konkretes Vorher/Nachher-Verhalten von Agenten belegen können

Wenn Sie keinen Unterschied zwischen Verhalten mit und ohne Skill nachweisen können, sollten Sie die TDD-Schleife sowie die Persuasions- und Test-Guides aus writing-skills noch einmal gezielt durchgehen.