From d2d16ed13e0d835341b5644bba58a9fbc6b688a4 Mon Sep 17 00:00:00 2001 From: sck_0 Date: Sat, 7 Mar 2026 10:35:04 +0100 Subject: [PATCH] =?UTF-8?q?feat(skills):=20Uncle=20Bob=20Craft=20=E2=80=94?= =?UTF-8?q?=20code=20review=20and=20Clean=20Architecture=20guidance=20(#22?= =?UTF-8?q?5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CATALOG.md | 5 +- README.md | 27 ++- data/catalog.json | 50 +++++- skills/uncle-bob-craft/README.md | 12 ++ skills/uncle-bob-craft/SKILL.md | 164 ++++++++++++++++++ .../examples/code-review-checklist.md | 55 ++++++ skills/uncle-bob-craft/reference.md | 146 ++++++++++++++++ .../uncle-bob-craft/references/clean-agile.md | 32 ++++ .../references/clean-architecture.md | 56 ++++++ .../uncle-bob-craft/references/clean-coder.md | 34 ++++ .../references/design-patterns.md | 32 ++++ skills_index.json | 10 ++ 12 files changed, 605 insertions(+), 18 deletions(-) create mode 100644 skills/uncle-bob-craft/README.md create mode 100644 skills/uncle-bob-craft/SKILL.md create mode 100644 skills/uncle-bob-craft/examples/code-review-checklist.md create mode 100644 skills/uncle-bob-craft/reference.md create mode 100644 skills/uncle-bob-craft/references/clean-agile.md create mode 100644 skills/uncle-bob-craft/references/clean-architecture.md create mode 100644 skills/uncle-bob-craft/references/clean-coder.md create mode 100644 skills/uncle-bob-craft/references/design-patterns.md diff --git a/CATALOG.md b/CATALOG.md index d2559139..4f4c4149 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -2,9 +2,9 @@ Generated at: 2026-02-08T00:00:00.000Z -Total skills: 1271 +Total skills: 1272 -## architecture (78) +## architecture (79) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | @@ -91,6 +91,7 @@ pagef... | robius, widget | robius, widget, critical, triggers, apply, textorima | `testing-patterns` | Jest testing patterns, factory functions, mocking strategies, and TDD workflow. Use when writing unit tests, creating test factories, or following TDD red-gr... | | testing, jest, factory, functions, mocking, tdd, writing, unit, tests, creating, test, factories | | `threejs-loaders` | Three.js asset loading - GLTF, textures, images, models, async patterns. Use when loading 3D models, textures, HDR environments, or managing loading progress. | threejs, loaders | threejs, loaders, three, js, asset, loading, gltf, textures, images, models, async, 3d | | `tool-design` | Build tools that agents can use effectively, including architectural reduction patterns | | agents, effectively, including, architectural, reduction | +| `uncle-bob-craft` | Use when performing code review, writing or refactoring code, or discussing architecture; complements clean-code and does not replace project linter/formatter. | clean-code, clean-architecture, solid, code-review, craftsmanship, uncle-bob | clean-code, clean-architecture, solid, code-review, craftsmanship, uncle-bob, uncle, bob, craft, performing, code, review | | `unreal-engine-cpp-pro` | Expert guide for Unreal Engine 5.x C++ development, covering UObject hygiene, performance patterns, and best practices. | unreal, engine, cpp | unreal, engine, cpp, pro, development, covering, uobject, hygiene, performance | | `wcag-audit-patterns` | Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fi... | wcag, audit | wcag, audit, conduct, accessibility, audits, automated, testing, manual, verification, remediation, guidance, auditing | | `wordpress-theme-development` | WordPress theme development workflow covering theme architecture, template hierarchy, custom post types, block editor support, and responsive design. | wordpress, theme | wordpress, theme, development, covering, architecture, hierarchy, custom, post, types, block, editor, responsive | diff --git a/README.md b/README.md index 3a8c7874..736bab77 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ - -# 🌌 Antigravity Awesome Skills: 1,271+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More + -> **The Ultimate Collection of 1,271+ Universal Agentic Skills for AI Coding Assistants β€” Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL** +# 🌌 Antigravity Awesome Skills: 1,272+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More + +> **The Ultimate Collection of 1,272+ Universal Agentic Skills for AI Coding Assistants β€” Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL** [![GitHub stars](https://img.shields.io/badge/⭐%2021%2C000%2B%20Stars-gold?style=for-the-badge)](https://github.com/sickn33/antigravity-awesome-skills/stargazers) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) @@ -19,11 +20,15 @@ [![Buy Me a Book](https://img.shields.io/badge/Buy%20me%20a-book-d13610?logo=buymeacoffee&logoColor=white)](https://buymeacoffee.com/sickn33) <<<<<<< HEAD -**Antigravity Awesome Skills** is a curated, battle-tested library of **1,271+ high-performance agentic skills** designed to work seamlessly across the major AI coding assistants. +<<<<<<< HEAD +**Antigravity Awesome Skills** is a curated, battle-tested library of **1,272+ high-performance agentic skills** designed to work seamlessly across the major AI coding assistants. ======= **Antigravity Awesome Skills** is a curated, battle-tested library of **1,207+ high-performance agentic skills** designed to work seamlessly across the major AI coding assistants. -> > > > > > > HEAD@{1} +> > > > > > > # HEAD@{1} +> > > > > > > +> > > > > > > **Antigravity Awesome Skills** is a curated, battle-tested library of **1,207+ high-performance agentic skills** designed to work seamlessly across the major AI coding assistants. +> > > > > > > aad201f (feat(skills): Uncle Bob Craft β€” code review and Clean Architecture guidance) **Welcome to the V7.0.1 21k Stars Patch Release!** This repository gives your agent reusable playbooks for planning, coding, debugging, testing, security review, infrastructure work, product thinking, and much more. @@ -41,7 +46,7 @@ - [🎁 Curated Collections (Bundles)](#curated-collections) - [🧭 Antigravity Workflows](#antigravity-workflows) - [πŸ“¦ Features & Categories](#features--categories) -- [πŸ“š Browse 1,271+ Skills](#browse-1271-skills) +- [πŸ“š Browse 1,272+ Skills](#browse-1272-skills) - [🀝 How to Contribute](#how-to-contribute) - [πŸ’¬ Community](#community) - [β˜• Support the Project](#support-the-project) @@ -316,7 +321,7 @@ The repository is organized into specialized domains to transform your AI into a Counts change as new skills are added. For the current full registry, see [CATALOG.md](CATALOG.md). -## Browse 1,271+ Skills +## Browse 1,272+ Skills We have moved the full skill registry to a dedicated catalog to keep this README clean, and we've also introduced an interactive **Web App**! @@ -328,10 +333,18 @@ We have moved the full skill registry to a dedicated catalog to keep this README Use @doc-coauthoring to rewrite our setup guide for first-time contributors. ``` +<<<<<<< HEAD + > > > > > > > main ## Browse 1,270+ Skills +======= + +## Browse 1,207+ Skills + +> > > > > > > aad201f (feat(skills): Uncle Bob Craft β€” code review and Clean Architecture guidance) + - Open the interactive browser in [`apps/web-app`](apps/web-app). - Read the full catalog in [`CATALOG.md`](CATALOG.md). - Start with role-based bundles in [`docs/users/bundles.md`](docs/users/bundles.md). diff --git a/data/catalog.json b/data/catalog.json index b8ac7253..0fb812d6 100644 --- a/data/catalog.json +++ b/data/catalog.json @@ -1,6 +1,6 @@ { "generatedAt": "2026-02-08T00:00:00.000Z", - "total": 1271, + "total": 1272, "skills": [ { "id": "00-andruia-consultant", @@ -6493,7 +6493,7 @@ { "id": "blockrun", "name": "blockrun", - "description": "Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models (\\\"blockrun\\\", \\\"use grok\\\", \\\"use gpt\\\", \\\"da...", + "description": "Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models (/\"blockrun/\", /\"use grok/\", /\"use gpt/\", /\"da...", "category": "data-ai", "tags": [ "blockrun" @@ -7744,7 +7744,7 @@ { "id": "claude-code-guide", "name": "claude-code-guide", - "description": "Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies \\\"Thinking\\\" keywords, debugging techniques, and best practices for interacting wit...", + "description": "Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies /\"Thinking/\" keywords, debugging techniques, and best practices for interacting wit...", "category": "general", "tags": [ "claude", @@ -8612,7 +8612,7 @@ { "id": "competitive-landscape", "name": "competitive-landscape", - "description": "This skill should be used when the user asks to \\\\\\\"analyze competitors\", \"assess competitive landscape\", \"identify differentiation\", \"evaluate market positioning\", \"apply Porter's Five Forces\",...", + "description": "This skill should be used when the user asks to ///\"analyze competitors\", \"assess competitive landscape\", \"identify differentiation\", \"evaluate market positioning\", \"apply Porter's Five Forces\",...", "category": "business", "tags": [ "competitive", @@ -17281,6 +17281,7 @@ "path": "skills/legal-advisor/SKILL.md" }, { +<<<<<<< HEAD "id": "leiloeiro-avaliacao", "name": "leiloeiro-avaliacao", "description": "Avaliacao pericial de imoveis em leilao. Valor de mercado, liquidacao forcada, ABNT NBR 14653, metodos comparativo/renda/custo, CUB e margem de seguranca.", @@ -17443,6 +17444,8 @@ "path": "skills/leiloeiro-risco/SKILL.md" }, { +======= +>>>>>>> 4f8cc40 (fix(registry): use POSIX path separators in bundles, catalog, and aliases) "id": "libreoffice/base", "name": "base", "description": "Database management, forms, reports, and data operations with LibreOffice Base.", @@ -18697,7 +18700,7 @@ { "id": "market-sizing-analysis", "name": "market-sizing-analysis", - "description": "This skill should be used when the user asks to \\\\\\\"calculate TAM\\\\\\\", \"determine SAM\", \"estimate SOM\", \"size the market\", \"calculate market opportunity\", \"what's the total addressable market\", or...", + "description": "This skill should be used when the user asks to ///\"calculate TAM///\", \"determine SAM\", \"estimate SOM\", \"size the market\", \"calculate market opportunity\", \"what's the total addressable market\", or...", "category": "business", "tags": [ "market", @@ -26827,7 +26830,7 @@ { "id": "startup-financial-modeling", "name": "startup-financial-modeling", - "description": "This skill should be used when the user asks to \\\\\\\"create financial projections\", \"build a financial model\", \"forecast revenue\", \"calculate burn rate\", \"estimate runway\", \"model cash flow\", or...", + "description": "This skill should be used when the user asks to ///\"create financial projections\", \"build a financial model\", \"forecast revenue\", \"calculate burn rate\", \"estimate runway\", \"model cash flow\", or...", "category": "business", "tags": [ "startup", @@ -26853,7 +26856,7 @@ { "id": "startup-metrics-framework", "name": "startup-metrics-framework", - "description": "This skill should be used when the user asks about \\\\\\\"key startup metrics\", \"SaaS metrics\", \"CAC and LTV\", \"unit economics\", \"burn multiple\", \"rule of 40\", \"marketplace metrics\", or requests...", + "description": "This skill should be used when the user asks about ///\"key startup metrics\", \"SaaS metrics\", \"CAC and LTV\", \"unit economics\", \"burn multiple\", \"rule of 40\", \"marketplace metrics\", or requests...", "category": "testing", "tags": [ "startup", @@ -27566,7 +27569,7 @@ { "id": "team-composition-analysis", "name": "team-composition-analysis", - "description": "This skill should be used when the user asks to \\\\\\\"plan team structure\", \"determine hiring needs\", \"design org chart\", \"calculate compensation\", \"plan equity allocation\", or requests...", + "description": "This skill should be used when the user asks to ///\"plan team structure\", \"determine hiring needs\", \"design org chart\", \"calculate compensation\", \"plan equity allocation\", or requests...", "category": "general", "tags": [ "team", @@ -28820,6 +28823,35 @@ ], "path": "skills/umap/SKILL.md" }, + { + "id": "uncle-bob-craft", + "name": "uncle-bob-craft", + "description": "Use when performing code review, writing or refactoring code, or discussing architecture; complements clean-code and does not replace project linter/formatter.", + "category": "architecture", + "tags": [ + "clean-code", + "clean-architecture", + "solid", + "code-review", + "craftsmanship", + "uncle-bob" + ], + "triggers": [ + "clean-code", + "clean-architecture", + "solid", + "code-review", + "craftsmanship", + "uncle-bob", + "uncle", + "bob", + "craft", + "performing", + "code", + "review" + ], + "path": "skills/uncle-bob-craft/SKILL.md" + }, { "id": "uniprot-database", "name": "uniprot-database", @@ -29715,7 +29747,7 @@ { "id": "web-design-guidelines", "name": "web-design-guidelines", - "description": "Review UI code for Web Interface Guidelines compliance. Use when asked to \\\"review my UI\\\", \\\"check accessibility\\\", \\\"audit design\\\", \\\"review UX\\\", or \\\"check my site aga...", + "description": "Review UI code for Web Interface Guidelines compliance. Use when asked to /\"review my UI/\", /\"check accessibility/\", /\"audit design/\", /\"review UX/\", or /\"check my site aga...", "category": "security", "tags": [ "web", diff --git a/skills/uncle-bob-craft/README.md b/skills/uncle-bob-craft/README.md new file mode 100644 index 00000000..ff761527 --- /dev/null +++ b/skills/uncle-bob-craft/README.md @@ -0,0 +1,12 @@ +# Uncle Bob Craft + +Skill for applying Robert C. Martin (Uncle Bob) criteria to **code review and production**: Clean Code (with `@clean-code`), Clean Architecture, The Clean Coder, Clean Agile, code smells and heuristics, and design-pattern discipline. + +## Contents + +- **[SKILL.md](./SKILL.md)** β€” Main skill: when to use, overview, aggregators, design patterns, smells, review vs production, examples, related skills, limitations. +- **[reference.md](./reference.md)** β€” Expanded reference: Clean Architecture, The Clean Coder, Clean Agile, smells/heuristics, design patterns, scope and attribution. +- **[references/](./references/)** β€” Deep references: [clean-architecture.md](./references/clean-architecture.md), [clean-coder.md](./references/clean-coder.md), [clean-agile.md](./references/clean-agile.md), [design-patterns.md](./references/design-patterns.md). +- **[examples/code-review-checklist.md](./examples/code-review-checklist.md)** β€” Copy-paste checklist for principle-based code review. + +Use with `@uncle-bob-craft`. Complements `@clean-code`; does not replace the project linter or formatter. diff --git a/skills/uncle-bob-craft/SKILL.md b/skills/uncle-bob-craft/SKILL.md new file mode 100644 index 00000000..41b5c816 --- /dev/null +++ b/skills/uncle-bob-craft/SKILL.md @@ -0,0 +1,164 @@ +--- +name: uncle-bob-craft +description: "Use when performing code review, writing or refactoring code, or discussing architecture; complements clean-code and does not replace project linter/formatter." +category: code-quality +risk: safe +source: community +date_added: "2026-03-06" +author: antigravity-contributors +tags: [clean-code, clean-architecture, solid, code-review, craftsmanship, uncle-bob] +tools: [claude, cursor, gemini] +--- + +# Uncle Bob Craft + +Apply Robert C. Martin (Uncle Bob) criteria for **code review and production**: Clean Code, Clean Architecture, The Clean Coder, Clean Agile, and design-pattern discipline. This skill is **complementary** to the existing `@clean-code` skill (which focuses on the Clean Code book) and to your project's linter/formatterβ€”it does not replace them. + +## Overview + +This skill aggregates principles from Uncle Bob's body of work for **reviewing** and **writing** code: naming and functions (via `@clean-code`), architecture and boundaries (Clean Architecture), professionalism and estimation (The Clean Coder), agile values and practices (Clean Agile), and design-pattern use vs misuse. Use it to evaluate structure, dependencies, SOLID in context, code smells, and professional practices. It provides craft and design criteria onlyβ€”not syntax or style enforcement, which remain the responsibility of your linter and formatter. + +## When to Use This Skill + +- **Code review**: Apply Dependency Rule, boundaries, SOLID, and smell heuristics; suggest concrete refactors. +- **Refactoring**: Decide what to extract, where to draw boundaries, and whether a design pattern is justified. +- **Architecture discussion**: Check layer boundaries, dependency direction, and separation of concerns. +- **Design patterns**: Assess correct use vs cargo-cult or overuse before introducing a pattern. +- **Estimation and professionalism**: Apply Clean Coder ideas (saying no, sustainable pace, three-point estimates). +- **Agile practices**: Reference Clean Agile (Iron Cross, TDD, refactoring, pair programming) when discussing process. +- **Do not use** to replace or override the project's linter, formatter, or automated tests. + +## Aggregators by Source + +| Source | Focus | Where to go | +|--------|--------|-------------| +| **Clean Code** | Names, functions, comments, formatting, tests, classes, smells | Use `@clean-code` for detail; this skill references it for review/production. | +| **Clean Architecture** | Dependency Rule, layers, boundaries, SOLID in architecture | See [reference.md](./reference.md) and [references/clean-architecture.md](./references/clean-architecture.md). | +| **The Clean Coder** | Professionalism, estimation, saying no, sustainable pace | See [reference.md](./reference.md) and [references/clean-coder.md](./references/clean-coder.md). | +| **Clean Agile** | Values, Iron Cross, TDD, refactoring, pair programming | See [reference.md](./reference.md) and [references/clean-agile.md](./references/clean-agile.md). | +| **Design patterns** | When to use, misuse, cargo cult | See [reference.md](./reference.md) and [references/design-patterns.md](./references/design-patterns.md). | + +## Design Patterns: Use vs Misuse + +- **Use patterns** when they solve a real design problem (e.g., variation in behavior, lifecycle, or cross-cutting concern), not to look "enterprise." +- **Avoid cargo cult**: Do not add Factory/Strategy/Repository just because the codebase "should" have them; add them when duplication or rigidity justifies the abstraction. +- **Signs of misuse**: Pattern name in every class name, layers that only delegate without logic, patterns that make simple code harder to follow. +- **Rule of thumb**: Introduce a pattern when you feel the third duplication or the second reason to change; name the pattern in code or docs so intent is clear. + +## Smells and Heuristics (Summary) + +| Smell / Heuristic | Meaning | +|-------------------|--------| +| **Rigidity** | Small change forces many edits. | +| **Fragility** | Changes break unrelated areas. | +| **Immobility** | Hard to reuse in another context. | +| **Viscosity** | Easy to hack, hard to do the right thing. | +| **Needless complexity** | Speculative or unused abstraction. | +| **Needless repetition** | DRY violated; same idea in multiple places. | +| **Opacity** | Code is hard to understand. | + +Full lists (including heuristics C1–T9-style) are in [reference.md](./reference.md). Use these in review to name issues and suggest refactors (extract, move dependency, introduce boundary). + +## Review vs Production + +| Context | Apply | +|---------|--------| +| **Code review** | Dependency Rule and boundaries; SOLID in context; list smells; suggest one or two concrete refactors (e.g., extract function, invert dependency); check tests and professionalism (tests present, no obvious pressure hacks). | +| **Writing new code** | Prefer small functions and single responsibility; depend inward (Clean Architecture); write tests first when doing TDD; avoid patterns until duplication or variation justifies them. | +| **Refactoring** | Identify one smell at a time; refactor in small steps with tests green; improve names and structure before adding behavior. | + +## How It Works + +### When reviewing code + +1. **Boundaries and Dependency Rule**: Check that dependencies point inward (e.g., use cases do not depend on UI or DB details). See [references/clean-architecture.md](./references/clean-architecture.md). +2. **SOLID in context**: Check Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion where they apply to the changed code. +3. **Smells**: Scan for rigidity, fragility, immobility, viscosity, needless complexity/repetition, opacity; list them with file/area. +4. **Concrete suggestions**: Propose one or two refactors (e.g., "Extract this into a function named X," "Introduce an interface so this layer does not depend on the concrete DB client"). +5. **Tests and craft**: Note if tests exist and if the change respects sustainable pace (no obvious "we'll fix it later" comments that violate professionalism). + +### When writing or refactoring code + +1. Prefer **small, single-purpose** functions and classes; use `@clean-code` for naming and structure. +2. Keep **dependencies pointing inward**; put business rules in the center, adapters at the edges. +3. Introduce **design patterns** only when duplication or variation justifies them. +4. Refactor in **small steps** with tests staying green. + +## Examples + +### Example 1: Code review prompt (copy-pasteable) + +Use this to ask for an Uncle Bob–oriented review: + +```markdown +Please review this change using Uncle Bob craft criteria (@uncle-bob-craft): +1. Dependency Rule and boundaries β€” do dependencies point inward? +2. SOLID in context β€” any violations in the touched code? +3. Smells β€” list rigidity, fragility, immobility, viscosity, needless complexity/repetition, or opacity. +4. Suggest one or two concrete refactors (e.g., extract function, invert dependency). +Do not duplicate lint/format; focus on structure and design. +``` + +### Example 2: Before/after (extract and name) + +**Before (opacity, does more than one thing):** + +```python +def process(d): + if d.get("t") == 1: + d["x"] = d["a"] * 1.1 + elif d.get("t") == 2: + d["x"] = d["a"] * 1.2 + return d +``` + +**After (clear intent, single level of abstraction):** + +```python +def apply_discount(amount: float, discount_type: int) -> float: + if discount_type == 1: + return amount * 1.1 + if discount_type == 2: + return amount * 1.2 + return amount + +def process(order: dict) -> dict: + order["x"] = apply_discount(order["a"], order.get("t", 0)) + return order +``` + +## Best Practices + +- βœ… Use `@clean-code` for naming, functions, comments, and formatting; use this skill for architecture, boundaries, SOLID, smells, and process. +- βœ… In review, name the smell or principle (e.g., "Dependency Rule violation: use case imports from the web framework"). +- βœ… Suggest at least one concrete refactor per review (extract, rename, invert dependency). +- βœ… Run the project linter and formatter separately; this skill does not replace them. +- ❌ Do not use this skill to enforce syntax or style; that is the linter's job. +- ❌ Do not add design patterns without a clear duplication or variation reason. + +## Common Pitfalls + +- **Problem:** Treating every class as needing a Factory or Strategy. + **Solution:** Introduce patterns only when you have a real design need (third duplication, second axis of change). + +- **Problem:** Review only listing "violates SOLID" without saying where or how. + **Solution:** Point to the file/function and which principle (e.g., "SRP: this function parses and persists; split into parse and persist"). + +- **Problem:** Skipping the project linter because "we applied Uncle Bob." + **Solution:** This skill is about craft and design; always run the project's lint and format. + +## Related Skills + +- **`@clean-code`** β€” Detailed Clean Code book material (names, functions, comments, formatting, tests, classes, smells). Use for day-to-day code quality; use uncle-bob-craft for architecture and cross-book criteria. +- **`@architecture`** β€” General architecture decisions and trade-offs. Use when choosing high-level structure; use uncle-bob-craft for Dependency Rule and boundaries. +- **`@code-review-excellence`** β€” Code review practices. Combine with uncle-bob-craft for principle-based review. +- **`@refactor-clean-code`** β€” Refactoring toward clean code. Use with uncle-bob-craft when refactoring for boundaries and SOLID. +- **`@test-driven-development`** β€” TDD workflow. Aligns with Clean Agile and Clean Coder (tests as requirement, sustainable pace). + +## Limitations + +- **Does not replace the project linter or formatter.** Run lint and format separately; this skill gives design and craft criteria only. +- **Does not replace automated tests.** It can remind you to write tests (Clean Coder, Clean Agile) but does not run or generate them. +- **Complementary to tooling.** Use it alongside existing CI, lint, and test suites. +- **No syntax or style enforcement.** It focuses on structure, dependencies, smells, and professional practice, not on brace style or line length. +- **Summaries, not the books.** Full Clean Code heuristics, component principles (REP/CCP/CRP, ADP/SDP/SAP), and detailed stories are in the books; we reference the most used parts. See [reference.md](./reference.md) "Scope and attribution." diff --git a/skills/uncle-bob-craft/examples/code-review-checklist.md b/skills/uncle-bob-craft/examples/code-review-checklist.md new file mode 100644 index 00000000..71803f9d --- /dev/null +++ b/skills/uncle-bob-craft/examples/code-review-checklist.md @@ -0,0 +1,55 @@ +# Uncle Bob Craft β€” Code Review Checklist + +Copy-paste this checklist when performing a principle-based code review with the uncle-bob-craft skill. Run your project linter/formatter separately; this checklist focuses on structure and design. + +--- + +## 1. Dependency Rule and boundaries + +- [ ] Dependencies point **inward** (use cases / domain do not depend on UI, DB, or framework details). +- [ ] Outer layers depend on interfaces (e.g., repositories, gateways) defined by inner layers. +- [ ] No direct import of framework or driver in the core/use-case code under review. + +## 2. SOLID in context + +- [ ] **SRP** β€” Each class/module has one reason to change (one actor). +- [ ] **OCP** β€” Extension via new implementations, not by editing existing core logic. +- [ ] **LSP** β€” Subtypes are substitutable; no hidden assumptions about concrete types. +- [ ] **ISP** β€” Interfaces are focused; callers do not depend on methods they do not use. +- [ ] **DIP** β€” High-level code depends on abstractions; concretions are injected at the edge. + +## 3. Smells + +- [ ] **Rigidity** β€” Small change does not force edits in many places. +- [ ] **Fragility** β€” Change does not break unrelated areas. +- [ ] **Immobility** β€” Reuse is possible where it makes sense. +- [ ] **Viscosity** β€” Doing the right thing is not harder than hacking. +- [ ] **Needless complexity** β€” No speculative or unused abstraction. +- [ ] **Needless repetition** β€” DRY; no obvious duplication. +- [ ] **Opacity** β€” Names and structure make intent clear. + +## 4. Design patterns + +- [ ] Any pattern used has a clear **reason** (duplication, variation, or boundary). +- [ ] No cargo-cult pattern (e.g., Factory with a single implementation and no plan for variation). +- [ ] Pattern improves readability or testability, not the opposite. + +## 5. Tests and professionalism + +- [ ] Touched code has or is covered by tests where appropriate. +- [ ] No "we'll fix it later" or "TODO: refactor" that clearly violates sustainable pace or quality. +- [ ] Commit/PR is coherent and does not leave the codebase worse. + +--- + +## Suggested output format for review + +1. **Boundaries**: One or two sentences on dependency direction and any violations. +2. **SOLID**: List any violations with file/function and principle (e.g., "SRP: `OrderService` parses and persists β€” split."). +3. **Smells**: List smells found with location (e.g., "Rigidity: changing discount rule touches 4 files."). +4. **Concrete refactors**: One or two specific suggestions (e.g., "Extract `applyDiscount` from `process`"; "Introduce `OrderRepository` interface and inject in the use case."). +5. **Tests / professionalism**: Brief note on test coverage and any concerns. + +--- + +*Use with the skill: @uncle-bob-craft. For naming, functions, and formatting detail, also use @clean-code. Always run the project linter and formatter separately.* diff --git a/skills/uncle-bob-craft/reference.md b/skills/uncle-bob-craft/reference.md new file mode 100644 index 00000000..81e6125f --- /dev/null +++ b/skills/uncle-bob-craft/reference.md @@ -0,0 +1,146 @@ +# Uncle Bob Craft β€” Expanded Reference + +This document expands the criteria referenced in the main skill. Sources: *Clean Code*, *Clean Architecture*, *The Clean Coder*, *Clean Agile* (Robert C. Martin). Use for progressive disclosure when you need full lists or deeper context. + +--- + +## Clean Architecture + +### Dependency Rule + +Source code dependencies must point only **inward** (toward higher-level policies). Inner layers do not know about outer layers (e.g., use cases do not import from the web framework or the database driver). + +- **Entities** (enterprise business rules) β€” center, no outward dependencies. +- **Use cases** (application business rules) β€” depend only on entities. +- **Interface adapters** (presenters, gateways) β€” depend on use cases/entities. +- **Frameworks and drivers** (UI, DB, HTTP) β€” outermost; depend inward. + +### Layers (hexagonal / ports and adapters) + +| Layer | Responsibility | Depends on | +|-------|----------------|------------| +| Entities | Core business entities and rules | Nothing (innermost) | +| Use cases | Application-specific business rules, orchestration | Entities | +| Interface adapters | Convert data between use cases and external world | Use cases, entities | +| Frameworks & drivers | DB, UI, HTTP, file I/O | Interface adapters | + +### SOLID in architecture context + +- **SRP** β€” A module should have one reason to change (one actor). +- **OCP** β€” Open for extension, closed for modification (use abstractions and boundaries). +- **LSP** β€” Subtypes must be substitutable for their base types (interfaces and implementations). +- **ISP** β€” Many client-specific interfaces are better than one general-purpose interface (splitting interfaces at boundaries). +- **DIP** β€” Depend on abstractions, not concretions (invert dependencies at boundaries). + +### Component design (summary) + +For grouping classes into components: **REP** (reuse/release equivalence), **CCP** (common closure), **CRP** (common reuse); **ADP** (acyclic dependencies), **SDP** (stable dependencies), **SAP** (stable abstractions). See [references/clean-architecture.md](./references/clean-architecture.md) for brief definitions. + +--- + +## The Clean Coder + +### Professionalism + +- **Do no harm** β€” Do not leave the code worse than you found it; leave it better when you can. +- **Work ethic** β€” Know your craft, practice, stay current. +- **Saying no** β€” Say no when the request is unreasonable or would compromise quality; offer alternatives. +- **Saying yes** β€” When you say yes, mean it; commit to deadlines you can meet. + +### Estimation + +- **Three-point estimates** β€” Best case, nominal, worst case; use for planning, not promises. +- **Velocity** β€” Use historical velocity for iteration planning; do not inflate commitments. +- **Uncertainty** β€” Communicate uncertainty; avoid false precision. + +### Sustainable pace + +- Avoid sustained overtime; it reduces quality and long-term output. +- Tests and refactoring are part of the job, not "extra." + +### Tests as requirement + +- Code without tests is legacy by definition. Writing tests is a professional requirement. + +### Mentoring and collaboration + +- Helping others (mentoring, pairing) and leaving the team and codebase better are part of professionalism. + +--- + +## Clean Agile + +### Values (from Agile manifesto, emphasized by Uncle Bob) + +- Individuals and interactions over processes and tools. +- Working software over comprehensive documentation. +- Customer collaboration over contract negotiation. +- Responding to change over following a plan. + +### Iron Cross (four values that support the above) + +| Value | Meaning | +|-------|--------| +| **Communication** | Prefer face-to-face and collaboration; reduce information loss. | +| **Courage** | Courage to refactor, to say no, to change design when needed. | +| **Feedback** | Short feedback loops (tests, demos, iterations). | +| **Simplicity** | Do the simplest thing that could work; avoid speculative design. | + +### Practices + +- **TDD** β€” Red, green, refactor; tests first as specification and safety net. +- **Refactoring** β€” Continuous small improvements; keep tests green. +- **Pair programming** β€” Two people at one machine; design and quality improve. +- **Simple design** β€” No duplication, express intent, minimal elements, small abstractions. + +--- + +## Smells and Heuristics (expanded) + +### Design smells (from Clean Code / Clean Architecture) + +| Code | Name | Brief | +|------|------|--------| +| **Rigidity** | Hard to change; one change triggers many. | Reduce coupling; introduce boundaries. | +| **Fragility** | Breaks in unexpected places. | Isolate changes; improve tests. | +| **Immobility** | Hard to reuse. | Extract reusable parts; reduce coupling. | +| **Viscosity** | Easy to hack, hard to do right. | Make right thing easy (abstractions, tests). | +| **Needless complexity** | Speculative or unused design. | YAGNI; remove until needed. | +| **Needless repetition** | DRY violated. | Extract common logic; name the abstraction. | +| **Opacity** | Hard to understand. | Rename, extract, clarify intent. | + +### Heuristics (review checklist style) + +- **C1 / Naming** β€” Names reveal intent; no disinformation (e.g., `accountList` when it is not a list). +- **C2 / Functions** β€” Small, one thing, one level of abstraction; few arguments. +- **C3 / Comments** β€” Prefer self-explanatory code; good comments for why, not what. +- **C4 / Formatting** β€” Newspaper metaphor; vertical density; variables near use. +- **C5 / Error handling** β€” Exceptions over return codes; don’t return or pass null without contract. +- **C6 / Tests** β€” F.I.R.S.T.; TDD when applicable. +- **C7 / Classes** β€” Small, single responsibility; stepdown rule. +- **T1 / Boundaries** β€” Dependencies point inward; no outer details in inner layers. +- **T2 / SOLID** β€” Check SRP, OCP, LSP, ISP, DIP in context. +- **T3 / Patterns** β€” Pattern used to solve a real problem, not for show. + +(You can extend to a full C1–T9 list in your team; the above is a compact reference.) + +--- + +## Design patterns (when and when not) + +- **Use** when: you have repeated variation (Strategy), lifecycle/creation complexity (Factory), or a clear cross-cutting concern (e.g., logging, validation at a boundary). +- **Avoid** when: the code is simple and a pattern would add indirection without reducing duplication or clarifying intent. +- **Cargo cult** β€” Applying a pattern by name everywhere (e.g., everything is a Factory) without a design reason. Prefer "simplest thing that could work" until duplication or change axis appears. + +--- + +--- + +## Scope and attribution + +- **Clean Code** β€” Full heuristics and chapter-by-chapter detail: use the `@clean-code` skill. This skill references Clean Code for review context and defers naming/functions/formatting there. +- **Clean Architecture** β€” We cover the Dependency Rule, layers, boundaries, SOLID in architecture, and component cohesion/coupling (REP, CCP, CRP, ADP, SDP, SAP) in summary; the book has full treatment and more nuance. +- **The Clean Coder** β€” We summarize professionalism, estimation, sustainable pace, tests, and mentoring; the book has full chapters and stories. +- **Clean Agile** β€” We summarize values, Iron Cross, and key practices (TDD, refactoring, pairing, simple design); the book ties them to agile history and adoption. + +*Attribution: Principles and structure drawn from Robert C. Martin, Clean Code (2008), Clean Architecture (2017), The Clean Coder (2011), Clean Agile (2019). This reference is a summary for agent use, not a substitute for the books.* diff --git a/skills/uncle-bob-craft/references/clean-agile.md b/skills/uncle-bob-craft/references/clean-agile.md new file mode 100644 index 00000000..7e7c1cd0 --- /dev/null +++ b/skills/uncle-bob-craft/references/clean-agile.md @@ -0,0 +1,32 @@ +# Clean Agile β€” Deep Reference + +Based on Robert C. Martin, *Clean Agile* (2019). Use this when discussing agile values, practices, and the "Iron Cross." + +## Agile values (manifesto) + +- Individuals and interactions over processes and tools. +- Working software over comprehensive documentation. +- Customer collaboration over contract negotiation. +- Responding to change over following a plan. + +Uncle Bob stresses that the right-hand side still has value; the left-hand side is preferred when there is a trade-off. + +## Iron Cross (four supporting values) + +| Value | What it means in practice | +|-------|---------------------------| +| **Communication** | Prefer face-to-face (or high-bandwidth) communication; reduce information loss; keep the team aligned. | +| **Courage** | Courage to refactor, to say no to unreasonable requests, to change the design when the code tells you to. | +| **Feedback** | Short feedback loopsβ€”unit tests, integration tests, demos, small iterations. Learn fast what works and what doesn’t. | +| **Simplicity** | Do the simplest thing that could possibly work. Avoid speculative design and unnecessary abstraction. | + +## Practices + +- **TDD (Test-Driven Development)** β€” Red, green, refactor. Write a failing test first, then minimal code to pass, then refactor. Tests act as specification and safety net. +- **Refactoring** β€” Continuous small improvements. Keep tests green; improve structure, names, and design in small steps. +- **Pair programming** β€” Two people at one machine. Improves design and quality; spreads knowledge. Not mandatory every hour, but a recognized practice for hard or critical work. +- **Simple design** β€” No duplication; express intent; minimal elements (classes, methods); small, focused abstractions. Add complexity only when the code asks for it (e.g., third duplication). + +## Relationship to craft + +Clean Agile ties agile values to craft: sustainable pace, tests as requirement, refactoring as part of the loop, and simplicity over speculation. Use this reference when discussing how TDD, refactoring, or pairing support agility and quality. diff --git a/skills/uncle-bob-craft/references/clean-architecture.md b/skills/uncle-bob-craft/references/clean-architecture.md new file mode 100644 index 00000000..c89bd0fb --- /dev/null +++ b/skills/uncle-bob-craft/references/clean-architecture.md @@ -0,0 +1,56 @@ +# Clean Architecture β€” Deep Reference + +Based on Robert C. Martin, *Clean Architecture* (2017). Use this when you need detailed criteria for dependency direction, layers, and boundaries. + +## Dependency Rule + +**Dependencies point inward only.** Code in the center (entities, use cases) must not depend on code in outer circles (UI, DB, frameworks). Outer circles depend on inner circles; inner circles define interfaces, outer circles implement them. + +- **Violation**: A use case that imports from Express, Django, or a concrete repository implementation. +- **Correct**: Use case depends on an interface (e.g., `OrderRepository`); the adapter in the outer layer implements it and uses Express/DB. + +## Layers (from inside out) + +1. **Entities** β€” Enterprise business rules. Plain structures and rules that apply across the application. No dependencies on frameworks or UI. +2. **Use cases** β€” Application business rules. Orchestrate entities and define application-specific workflows. Depend only on entities and on interfaces for I/O (repositories, presenters). +3. **Interface adapters** β€” Convert data between use cases and the outside world. Presenters, gateways, controllers that translate external format to/from use-case format. Depend on use cases (and entities only via use cases). +4. **Frameworks and drivers** β€” Web framework, DB driver, messaging, file I/O. Implement interfaces defined by use cases or interface adapters. Depend inward. + +## Boundaries + +- **Boundary** = interface or abstract type that inner code depends on; outer code implements. +- Good boundaries make it easy to swap implementations (e.g., in-memory repo for tests, SQL repo for production). +- Draw boundaries where there is a reason to vary or replace (different persistence, different UI, different transport). + +## SOLID in this context + +- **SRP** β€” Each module (class/package) has one reason to change (one actor). E.g., separate "report formatting" from "report calculation" if they change for different reasons. +- **OCP** β€” Extend behavior via new implementations of interfaces (new adapters), not by editing existing use-case or entity code. +- **LSP** β€” Any implementation of a repository or gateway interface must be substitutable without breaking the use case. +- **ISP** β€” Small, focused interfaces (e.g., `ReadOrderRepository` and `WriteOrderRepository` if read and write evolve differently) instead of one fat `OrderRepository`. +- **DIP** β€” Use cases depend on `OrderRepository` (interface); the composition root wires in `SqlOrderRepository`. High-level policy does not depend on low-level details. + +## Inversion of dependencies + +- **Without inversion**: Use case imports and calls `SqlOrderRepository` directly β†’ use case depends on DB. +- **With inversion**: Use case depends on `OrderRepository` (interface); `SqlOrderRepository` implements it and is injected at the edge. Use case stays independent of SQL. + +## Component cohesion and coupling (for larger systems) + +When grouping classes into **components** (modules, packages), Uncle Bob defines: + +**Cohesion:** +- **REP (Reuse/Release Equivalence)** β€” The unit of reuse is the unit of release; group classes that are reused and released together. +- **CCP (Common Closure)** β€” Classes that change for the same reasons belong in the same component; reduces impact of change. +- **CRP (Common Reuse)** β€” Classes reused together should be packaged together; avoid forcing dependents to pull in more than they need. + +**Coupling:** +- **ADP (Acyclic Dependencies)** β€” Component dependency graph must have no cycles. +- **SDP (Stable Dependencies)** β€” Depend in the direction of stability; less stable components depend on more stable ones. +- **SAP (Stable Abstractions)** β€” Stable components should be abstract; unstable components can be concrete. + +Use this when discussing module/package boundaries beyond single layers. For full treatment see *Clean Architecture* (Martin, 2017). + +--- + +Use this reference when reviewing for "dependency direction," "layer violations," or "missing boundaries." diff --git a/skills/uncle-bob-craft/references/clean-coder.md b/skills/uncle-bob-craft/references/clean-coder.md new file mode 100644 index 00000000..cb16c06b --- /dev/null +++ b/skills/uncle-bob-craft/references/clean-coder.md @@ -0,0 +1,34 @@ +# The Clean Coder β€” Deep Reference + +Based on Robert C. Martin, *The Clean Coder* (2011). Use this when discussing professionalism, estimation, and sustainable pace. + +## Professionalism + +- **Do no harm** β€” Do not leave the codebase in a worse state. If you must leave a mess, leave a clear TODO and track it. Prefer leaving code better than you found it (boy scout rule). +- **Know your craft** β€” Practice (e.g., katas), read, stay current. Estimate only what you understand enough to estimate. +- **Saying no** β€” When a request would compromise quality or is unreasonable, say no. Offer alternatives (e.g., "We can do X by date Y if we drop Z" or "We need two more weeks for tests"). +- **Saying yes** β€” When you commit, mean it. Do not say yes to please and then miss; communicate early if you cannot meet a commitment. + +## Estimation + +- **Three-point estimate** β€” Best / nominal / worst case. Use for planning and risk, not as a single "promise" number. +- **Velocity** β€” Use historical velocity for iteration planning. Do not inflate; if the team goes fast once, use that as data for the next time, not as the new permanent commitment. +- **Uncertainty** β€” Make uncertainty visible. Prefer ranges and confidence levels over false precision. +- **Refusal to estimate** β€” It is professional to refuse to give a date when the request is vague or the work is unknown; offer to break it down first or to give a range after discovery. + +## Sustainable pace + +- Sustained overtime reduces quality and long-term output. Occasional crunch may happen; make it rare and recover afterward. +- Tests, refactoring, and learning are part of the job. Skipping them to "hit the date" creates technical debt and is unprofessional in the long run. + +## Tests as a requirement + +- Code without tests is legacy. Writing and maintaining tests is part of professional delivery, not optional. +- When under pressure, the first thing to protect is the test suite and the ability to refactor safely. + +## Mentoring and collaboration + +- **Helping others** β€” Part of professionalism is mentoring, pairing, and leaving the codebase (and the team) better than you found it. +- **Collaboration** β€” Communicate clearly with stakeholders and peers; say no when needed, and offer alternatives when saying yes is not possible. + +Use this reference when the discussion involves commitment, estimates, saying no, sustainable development practices, or teamwork. diff --git a/skills/uncle-bob-craft/references/design-patterns.md b/skills/uncle-bob-craft/references/design-patterns.md new file mode 100644 index 00000000..94796a8a --- /dev/null +++ b/skills/uncle-bob-craft/references/design-patterns.md @@ -0,0 +1,32 @@ +# Design Patterns β€” Use vs Misuse + +Use this when evaluating whether a design pattern is justified or is cargo cult / overuse. + +## When to use a pattern + +- **Repeated variation** β€” Same algorithm or structure with different behavior (e.g., different discount rules) β†’ Strategy or similar. +- **Lifecycle or creation complexity** β€” Object creation has many variants or steps β†’ Factory, Builder when the duplication or complexity is real. +- **Cross-cutting concern** β€” Logging, validation, auth at a boundary β†’ Decorator, middleware, or adapter at the edge. +- **Stable abstraction, varying implementation** β€” You expect to swap implementations (e.g., repository, gateway) β†’ Interface + implementations; dependency injection. + +Rule of thumb: introduce a pattern when you feel the **third duplication** or the **second axis of change** (second reason to open the same module). Name the pattern in code or docs so intent is clear. + +## When not to use a pattern + +- **Simple, linear code** β€” No duplication, one reason to change. Adding a Factory or Strategy here adds indirection without benefit. +- **Speculative need** β€” "We might need to swap implementations later." Prefer YAGNI; add the abstraction when you actually have a second implementation or a second reason to change. +- **Every class is a pattern** β€” Not every class needs to be behind a Factory or an Interface. Use patterns where they solve a real design problem. + +## Cargo cult and misuse + +- **Cargo cult** β€” Using a pattern because "that’s what we do" or "enterprise code has Factories," without a clear design reason. Symptoms: Factory that only calls `new`, Strategy with one implementation and no plan for a second. +- **Overuse** β€” Pattern names in every class name; layers that only delegate and add no logic; code that is harder to follow than a straightforward version. +- **Misuse** β€” Wrong pattern for the problem (e.g., Singleton for something that should be testable and replaceable); pattern that hides the real design (e.g., God Object behind a Facade). + +## Good signals + +- The pattern name appears in design docs or comments where it helps (e.g., "Strategy for discount calculation"). +- There are at least two concrete variants or a clear, stated reason for future variation. +- Tests and call sites are simpler because of the abstraction (e.g., tests inject a fake repository). + +Use this reference in review when someone proposes or has added a Factory, Strategy, Repository, or other patternβ€”ask "what duplication or variation does this solve?" and "is there a second implementation or a second reason to change?" diff --git a/skills_index.json b/skills_index.json index d0590a6d..9ec835f6 100644 --- a/skills_index.json +++ b/skills_index.json @@ -11819,6 +11819,16 @@ "source": "unknown", "date_added": null }, + { + "id": "uncle-bob-craft", + "path": "skills/uncle-bob-craft", + "category": "code-quality", + "name": "uncle-bob-craft", + "description": "Use when performing code review, writing or refactoring code, or discussing architecture; complements clean-code and does not replace project linter/formatter.", + "risk": "safe", + "source": "community", + "date_added": "2026-03-06" + }, { "id": "uniprot-database", "path": "skills/uniprot-database",