documentation-fundamentals
Klare Dokumentation schreiben
Schlechte Dokumentation verschwendet Teamzeit und sorgt für Verwirrung. Dieser Skill erzwingt Dokumentationsstandards für README-Dateien, JSDoc-Kommentare und Inline-Code-Erklärungen nach dem WARUM-nicht-WAS-Prinzip. Erhalten Sie konsistente, wartbare Dokumentation, die Kontext und Begründung erklärt.
スキルZIPをダウンロード
Claudeでアップロード
設定 → 機能 → スキル → スキルをアップロードへ移動
オンにして利用開始
テストする
「documentation-fundamentals」を使用しています。 Überprüfe die README und Inline-Kommentare in meinem Projekt
期待される結果:
- README-Bewertung: Fehlender Why-Abschnitt, der das Problem erklärt, das dieses Projekt löst
- Zu verbessernde Inline-Kommentare: Zeilen 24-26 wiederholen nur Code, Zeilen 89-91 sind veraltet - sagt Filter inaktiv, aber Code filtert nach Rolle
- Fehlende JSDoc: 3 exportierte Funktionen ohne Dokumentation
- Gefundene gute Beispiele: Zeilen 45-48 erklären die Begründung für den Rate-Limit-Puffer
「documentation-fundamentals」を使用しています。 Hilf mir, JSDoc für meine API-Funktionen zu schreiben
期待される結果:
- Für validateUser-Funktion: @param email mit Typ string hinzufügen, @returns ValidationResult, Beispielverwendung einschließen, dokumentieren, dass AuthenticationError geworfen wird, wenn Anmeldedaten ungültig sind
- Für createSession-Funktion: @param userId, @param expiresIn hinzufügen, @returns sessionToken, dokumentieren, dass Tokens automatisch aktualisiert werden
- Für getUserProfile-Funktion: @param userId hinzufügen, @returns UserProfile, @see-Referenzen zu verwandten Funktionen einschließen
「documentation-fundamentals」を使用しています。 Was macht gute Inline-Kommentare aus?
期待される結果:
- Gute Kommentare erklären WARUM: Geschäftsgrund, Grenzfall, Entscheidungshistorie
- Gute Kommentare verweisen auf Tickets oder Stakeholder-Anforderungen
- Vermeiden Sie Kommentare, die nur beschreiben, was der Code tut - der Code zeigt das
- Entfernen Sie Magic Numbers: Verwenden Sie benannte Konstanten mit erklärenden Kommentaren
セキュリティ監査
安全This is a pure prompt-based documentation skill containing only guidelines, examples, and templates for writing better documentation. The static findings are false positives caused by the scanner misinterpreting code examples and legitimate metadata fields. There is no executable code, no network access, no filesystem access, and no command execution in this skill. The skill only provides documentation review criteria and best practices.
リスク要因
🌐 ネットワークアクセス (1)
📁 ファイルシステムへのアクセス (1)
⚙️ 外部コマンド (39)
品質スコア
作れるもの
Onboarding mit klaren READMEs
Neue Teammitglieder können Projekte sofort ausführen mit vollständiger README-Dokumentation einschließlich Installations- und Schnellstart-Schritten.
Mitwirkungsfreundliche Projekte erstellen
Gewinnen Sie Mitwirkende mit klaren Installationsanweisungen, Beitragsrichtlinien und gut dokumentierten APIs.
Team-Dokumentationsstandards durchsetzen
Konsistente Dokumentation über Codebasen hinweg mit umsetzbaren Überprüfungskriterien und Anti-Pattern-Warnungen aufrechterhalten.
これらのプロンプトを試す
Review the README file for this project. Does it include these essential sections: What (one-sentence description), Why (problem solved), Installation, Quick Start, and Contributing? Point out any missing sections and suggest specific improvements.
Review the inline comments in this code. Flag any comments that just repeat what the code does (WHAT) and rewrite them to explain the context and rationale (WHY). Include the business reason or ticket reference where applicable.
Write complete JSDoc documentation for the exported functions in this file. Include: brief description, parameter descriptions with types, return value description, example usage, and any error conditions that may be thrown. Reference the function implementation to ensure accuracy.
Audit this codebase for documentation quality. Report: missing JSDoc on exported functions, outdated comments that contradict code, commented-out code that should be deleted, magic numbers without explanation, and empty or auto-generated READMEs that need expansion.
ベストプラクティス
- Schreiben Sie Kommentare, die WARUM beantworten, nicht WAS - der Code zeigt bereits, was passiert
- Fügen Sie Geschäftskontext in Kommentare ein - Ticketnummern, Stakeholder-Anforderungen oder Grenzfall-Erklärungen
- Halten Sie READMEs aktuell - eine veraltete README ist schlimmer als keine README
- Verwenden Sie JSDoc für alle exportierten Funktionen - mit Beispielen, die korrekte Verwendung zeigen
回避
- Offensichtlichen Code kommentieren wie Setze x auf 5 oder Durchlaufe Items
- Auskommentierten Code in der Codebasis belassen - verwenden Sie git, um alten Code wiederherzustellen
- Dokumentation einmal schreiben und nie aktualisieren, wenn sich der Code ändert
- Magic Numbers ohne Erklärung ihrer Bedeutung oder Herkunft verwenden
よくある質問
Welche Tools funktionieren mit diesem Skill?
Generiert dies Dokumentation aus Code?
Wie unterscheidet sich dies von Dokumentationsgeneratoren?
Sind meine Daten bei Verwendung dieses Skills sicher?
Warum ist das WARUM-nicht-WAS-Prinzip wichtig?
Kann dies bei API-Dokumentation helfen?
開発者の詳細
作成者
DanielPodolskyライセンス
MIT
リポジトリ
https://github.com/DanielPodolsky/mentor-spec/tree/main/.claude/skills/fundamentals/documentation参照
main
ファイル構成
📄 SKILL.md