تخطَّ إلى المحتوى
TakoAPI
العودة إلى المهارات

uncle-bob

بواسطة robert-hoffmann

Copilot
—لم يُقيَّم بعد
تقييمك

موجز

Curated GitHub Copilot skills, custom agents, and governance workflows for consistent, high-quality AI-assisted development.

الوصف

# Uncle Bob

<table>
<tr>
<td width="300">
<img src="assets/brand/uncle-bob.png" alt="Uncle Bob" width="280" />
</td>
<td>

Uncle Bob is a practical collection of skills and a focused teaching agent for GitHub Copilot in VS Code, Copilot CLI, Claude Code, and Codex users. It gives agentic coding tools a coordinated core of quality, authoring, workflow, and governance, with implementation specialists and customization tooling layered on top without forcing a heavy framework around day-to-day development.

I use these skills in an actual corporate production environment for supply-chain management in the aerospace industry.

</td>
</tr>
</table>

## What This Is

This repository is a practical operating system for guided agentic coding work.

Its center of gravity is not the framework-specific skills.
The core stack is:

1. `ub-quality` for the mandatory baseline of structure, readability, and code
   or document hygiene
2. `ub-authoring` for reusable routing, naming, non-use boundaries, and shared
   authoring conventions
3. `ub-workflow` for planning, lightweight specs, initiatives, sprints, audit,
   and archive
4. `ub-governance` for testing posture, evidence depth, decision memory, and
   repository-control discipline

Those four skills stand together as a complete baseline for planning,
review, authoring, and governance work even before any language or framework
specialist is involved.

`ub-customizations` sits next to that core when you need to build or maintain
skills, hooks, or MCP configs.

The language and framework skills still matter, but they are supporting
specialists that plug in after the work has been shaped and routed correctly.

## Why Use It

Use it when you want your coding agent to work through a coherent operating
model instead of acting like a collection of disconnected prompts.

The repository is designed so quality, authoring, workflow, and governance
reinforce each other instead of competing:

1. `ub-quality` acts as the companion baseline for formatting, readability,
   decision analysis, and touched-scope discipline
2. `ub-authoring` keeps reusable skill guidance portable and treats
   descriptions as routing logic instead of marketing copy
3. `ub-workflow` picks the smallest safe planning surface, promotes work out of
   direct mode when needed, and uses explicit artifacts and readiness gates
4. `ub-governance` stays lean by default and escalates only when the scope,
   risk, or audit path truly requires it

You do not need a framework-specific skill for every task.
Many planning, review, documentation, authoring, and governance tasks are
handled cleanly by the core stack alone.

## How The Core Skills Work Together

The current repo workflow is more explicit than a simple "pick a skill and
go" model:

1. `ub-workflow` chooses the lane: direct bounded work, lightweight spec, or
   initiative
2. `ub-quality` travels with touched documents and code as the formatting,
   readability, and decision-analysis baseline
3. `ub-authoring` owns shared installable guidance and reusable routing rules
   when the catalog itself is being shaped
4. `ub-governance` stays on the Level 1 fast path for ordinary workflow-backed
   work and escalates to heavier evidence or ADR machinery only when needed
5. `ub-customizations` classifies the artifact first, then builds the smallest
   sufficient customization: skill, hook, or MCP config

## Tooling Footnote

For repository Python commands, prefer `uv run python ...`.

For short ad hoc local inspection when `uv` is not needed, use the interpreter
command that matches your environment instead of assuming one universal
fallback name across platforms.

When the repo already exposes a Taskfile entrypoint, prefer that wrapper over a
custom shell command.

## Workflow At A Glance

Within that core stack, `ub-workflow` provides the planning model.

The planning model in this repo is intentionally tiered:

1. direct bounded work for truly small tasks that do not need a durable
   planning artifact
2. lightweight specs under `./.ub-workflows/specs/` for bounded work that has
   become planning-heavy enough to need assumptions, scope, options,
   validation, or an execution shape written down
3. initiatives for broader, higher-impact work where PRD, roadmap, sprint
   preparation, sprint execution, final audit, and retained notes improve
   delivery quality

In practice, specs are the preferred small planning surface, while initiatives
plus sprints are the heavier delivery path for bigger impact areas.

The repo's default operating root for durable workflow state is
`./.ub-workflows/`.
The workflow contract also expects explicit promotion when work outgrows direct
mode, roadmap approval before sprint initialization, and standalone prepared
`sprint.md` files before execution starts.

If you want guided help choosing the right lane, ask the main coding agent to
explain `ub-workflow` from its skill contract and choose the smallest correct
planning surface.

## Interaction Modes

`ub-workflow` supports four modes that change how visible and hands-on the
execution flow feels. They do not weaken readiness rules. They change how much
analysis is surfaced, when follow-up questions appear, and whether the
workflow pauses between sprints or execution chunks.

1. `reviewed`
   The most interactive and hands-on mode. Before execution, it surfaces the
   analysis, exposes meaningful options when there is a real choice, and asks
   follow-up questions when confirmation or direction is needed. After
   execution, it reports what changed, why it mattered, what to watch out for
   next, and then pauses for manual advancement before the next sprint or
   execution chunk.
2. `flow`
   A little faster and lighter. It still gives a short explanatory note before
   execution and a fuller update after execution, but it does not normally stop
   to ask pre-execution questions unless something important is unclear or
   risky. It still waits for manual advancement after each sprint or chunk.
3. `auto`
   More autonomous. Most pre-execution analysis stays internal, and the updates
   back to the user are shorter and more focused. It keeps moving forward
   automatically unless it hits an interruption condition such as a blocker, a
   conflict, a material ambiguity, or a decision that could significantly
   reshape the work.
4. `continuous` (`yolo`)
   The least interruptive mode. It still does internal analysis, planning, and
   artifact updates, but it does not stop to provide routine before-and-after
   user-facing notes, and it does not pause between sprints unless a major
   blocker, contradiction, or conflict forces the work to stop and be resolved
   before continuing.

## How The Workflow Feels

Within the core stack, the workflow layer is what gives bigger work a durable
shape.

The intended rhythm looks like this:

1. start with rough R&D, discovery, or problem framing
   Capture what is unclear, what needs to be true, and what level of planning
   the work actually deserves.
2. choose the smallest planning surface that will hold
   Use direct work for very small tasks, a spec for bounded one-offs, and an
   initiative when the work needs a PRD, roadmap, and staged delivery.
3. turn bigger work into explicit sprints
   Instead of one long fuzzy thread, the work gets broken into prepared sprint
   slices with validation focus, dependencies, and likely touched surfaces.
4. execute with durable handoffs
   Each sprint is designed to be resumable. Decisions, evidence, closeout, and
   rollup artifacts make it easier to stop, resume, review, or hand the work
   to another human or agent later.
5. validate and close intentionally
   The workflow is built around proving what changed, surfacing risks, and
   finishing with a final audit instead of letting bigger work fade out in chat
   history.

That is why the workflow layer matters so much here, even though it is only one
part of the core stack.
It turns agent use into a delivery system:

- research and planning before blind execution
- explicit scope before broad refactors
- sprints for bigger impact areas instead of one sprawling session
- handoffs and validation so progress survives across time, tools, and people

If the work is small, this stays lightweight.
If the work is important, it becomes structured without becoming bureaucratic.

In `reviewed` mode, that structure is deliberately strict: starting the next
sprint opens a preview first, not execution in the same turn, and execution
waits for a later approval message.

## Prompt-Driven Initiative Flow

If you already have a PRD, the workflow can be driven almost entirely through
prompts while still keeping the work structured and resumable.

The usual progression is:

1. scaffold the initiative from the PRD
   Start by invoking `ub-workflow` once and giving it the PRD. The first prompt
   is simply to scaffold a new initiative from that PRD. That creates the
   working structure and establishes a self-contained `prd.md` as the source of
   truth.
2. generate and review the roadmap
   Next, ask it to generate the roadmap from the PRD. Review the roadmap before
   moving forward so the sprint sequence, dependencies, and planned slices are
   correct before `roadmap_ready` is treated as passed.
3. prepare and initialize the sprint set
   Once the roadmap looks right, ask it to prepare the sprints from that
   roadmap and then initialize them so the sprint structure is ready for
   execution. Each sprint should be prepared as a standalone `sprint.md`
   before the sprint begins. `reviewed` or `flow` mode is usually the cleanest
   fit here.
4. execute Sprint 01 with the generated artifacts as context
   Start Sprint 01, work through the sprint using the prepared artifacts as the
   context system, then close out the sprint and prepare the handoff into the
   next one.
5. repeat sprint by sprint until final audit
   From there, the flow becomes intentionally simple: start the next sprint,
   complete the work, close it out, and move forward. When the delivery work is
   done, run the final audit, write the retained note, and archive
   intentionally.

In other words, the prompts drive the workflow, but the artifacts hold the
state. That is the key difference.

You are not relying on one long chat thread to remember what the plan was.
The PRD, roadmap, sprint pack, decision logs, closeouts, and rollups carry the
context forward.

Practical note:

- after a cold restart, it is usually worth resuming in a more context-heavy
  mode first, or simply reusing the existing session when possible, so the
  agent reloads the initiative state before continuing execution

## Core Stack

These are the four skills that explain how the repo actually works:

1. `ub-quality`
   The mandatory companion baseline. It keeps code and documents readable,
   reviewable, aligned, and consistent, and it enforces touched-scope
   formatting and response-structure discipline.
2. `ub-authoring`
   The reusable authoring contract. It owns routing-quality descriptions,
   naming, non-use boundaries, progressive disclosure, and other shared skill
   conventions that should travel with the catalog.
3. `ub-workflow`
   The planning and orchestration layer. It shapes work into direct tasks,
   lightweight specs, or initiatives, then carries larger work through
   roadmap, gated sprint preparation, execution, final-audit, and archive flow.
4. `ub-governance`
   The control layer. It defaults to a lean profile, treats workflow artifacts
   as the normal Level 1 record, and only escalates to heavier governance
   machinery when scope or risk requires it.
   The extracted repo-maintenance checks in this development repository are a
   separate surface, not part of the distributable governance command path.

Adjacent to that core is `ub-customizations`, which is the builder surface for
skills, hooks, and MCP configs when you are extending VS Code Copilot
customizations themselves. Its workflow is classification-first: interview the
request, choose the smallest sufficient artifact, then generate and validate.

The other skills are implementation specialists that become useful after the
core stack has already shaped the work.

## What's Included

| Skill             | Description                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| ub-quality        | Companion baseline for touched-scope quality: alignment, readability, decision analysis, documentation cleanup, and structured responses. |
| ub-authoring      | Shared authoring workflow for installable skills and reusable references: routing quality, portability, naming, and non-use boundaries. |
| ub-workflow       | Canonical lane-and-gate workflow for direct work, lightweight specs in `./.ub-workflows/specs/`, and initiatives with roadmaps and prepared sprints. |
| ub-governance     | Lean-by-default governance workflow for testing posture, evidence depth, repository controls, gate semantics, and bounded exceptions. |
| ub-customizations | Classification-first builder workflow for VS Code Copilot skills, hooks, and MCP configs, plus supporting references, validation, and portability notes. |
| ub-python         | Python workflow for repo-truth detection, strict typing, tests-first behavior changes, tooling validation, and forward-compatible implementation. |
| ub-ts             | TypeScript workflow for archetype detection, runtime-faithful module strategy, strict typing, config baselines, and modernization. |
| ub-css            | CSS workflow for token-first styling, cascade layers, modern selectors, container queries, and progressive enhancement. |
| ub-vuejs          | Vue workflow for modern SFC authoring, strict TypeScript, current reactivity patterns, and hydration-aware component design. |
| ub-nuxt           | Nuxt workflow for app-structure detection, runtime/rendering choices, modern framework-native patterns, and migration away from legacy layouts. |
| ub-tailwind       | Tailwind workflow for environment detection, CSS-first setup, modern directives, upgrade-safe migration, and framework-specific integration. |

| Agent             | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| ub-teacher        | Beginner-friendly explanations and code walkthroughs.                                |

## Install Options

There are three practical ways to consume this repo. The best choice depends on
your host tool and how much control you want over updates.

1. Copilot CLI plugin install
   Best fit for GitHub Copilot and Copilot CLI users because GitHub's official
   plugin docs support direct repository installs when `plugin.json` lives at
   the repository root or in `.github/plugin/`, which this repo provides.

   ```bash
   copilot plugin install robert-hoffmann/uncle-bob
   ```

   If you prefer marketplace registration for team discovery, GitHub's docs
   also support registering a repository that contains
   `.github/plugin/marketplace.json`:

   ```bash
   copilot plugin marketplace add robert-hoffmann/uncle-bob
   ```

   Pros:
   - most native path for Copilot CLI
   - uses the repo's plugin metadata directly
   - keeps agent and skill distribution tied to GitHub's documented plugin flow

   Cons:
   - primarily Copilot-oriented, not the most portable path for non-Copilot
     hosts

2. `skills.sh` install
   Best fit when you want one install/update flow across multiple agent hosts.
   The official `skills` CLI supports repository installs plus agent, skill,
   copy, and update flags, and Claude Code documents compatibility with the
   Agent Skills open standard.

   ```bash
   npx skills add robert-hoffmann/uncle-bob
   ```

   Useful follow-ups:

   ```bash
   npx skills add robert-hoffmann/uncle-bob --list
   npx skills add robert-hoffmann/uncle-bob --skill ub-workflow --agent claude-code codex
   npx skills update
   ```

   Pros:
   - easiest cross-tool story for Claude Code, Codex-style setups, and other
     Agent Skills-compatible environments
   - supports targeted installs and updates
   - avoids hand-managed copy or symlink drift

   Cons:
   - installs whatever is currently pushed to GitHub, not uncommitted local
     changes
   - the public docs are still lighter than the Copilot plugin docs, so the CLI
     help output matters in practice

3. Manual vendoring
   Best fit when a team wants full control over what gets committed into a
   downstream repository. In that model, treat `AGENTS.md`, `.agents/skills/`,
   and `.github/agents/` as the main portable surfaces and manage updates on
   your own terms.

   Pros:
   - maximum control over review, pinning, and local adaptation
   - works even where plugin or skills managers are not allowed

   Cons:
   - highest maintenance overhead
   - easiest path to drift if you stop syncing upstream changes

### How Custom Agents Are Installed

Skills and custom agents do not currently have the same portability story.

1. VS Code Copilot
   Custom agents are workspace-discovered from `.github/agents/*.agent.md`.
   If you vendor this repo manually into another project, include
   `.github/agents/` alongside `.agents/skills/` and `AGENTS.md`.

2. Copilot CLI
   The plugin install path includes custom agents automatically because this
   repo's [plugin.json](./plugin.json) explicitly points its `agents` field to
   `.github/agents/`. After installing, you can verify that the agents loaded
   in a Copilot CLI session with `/agent`.

3. `skills.sh`
   `skills.sh` is excellent for distributing the skills, but it is not the
   install path for these repo-local Copilot custom agents. Its job is to place
   skills into host-specific skill directories, not to vend `.github/agents`
   style agent profiles from this repository.

4. Claude Code and Codex
   This repo is usable there today through skills and instruction surfaces, but
   these specific custom agents are not yet mirrored into host-native agent
   directories such as `.claude/agents/`. So there is not currently a
   first-class one-command custom-agent install story for those hosts from this
   repo alone.

### Support Notes

- VS Code Copilot and Copilot CLI are the strongest native targets today.
  Official docs explicitly support workspace-level agents in `.github/agents`,
  skill discovery under `.agents/skills`, and direct plugin installs from repos
  with `plugin.json`.
- Claude Code is compatible through the Agent Skills open standard and its
  native `.claude/skills` model. The smoothest path from this repo today is
  `skills.sh`, because this repository does not mirror every skill into a
  dedicated `.claude/skills/` tree.
- Codex users are supported through `AGENTS.md` and the broader Agent Skills
  ecosystem. This repo is usable there today, but its most polished packaging
  remains Copilot-first plus `skills.sh`.

For most real work, the best starting point is the main coding agent with the
core stack available in the repo: `ub-quality`, `ub-authoring`,
`ub-workflow`, and `ub-governance`.
Within that stack, `ub-workflow` helps decide whether the work should stay
direct, become a lightweight spec, or become a full initiative.
Then add a specialist skill or `ub-customizations` only when the execution
surface is genuinely owned there.

Use `ub-teacher` when you want explanation-first help instead of execution.

## Philosophy

Keep agentic coding practical. Start with strong quality defaults, add focused domain knowledge only where it helps, and prefer reusable instructions over one-off prompting. The goal is to make coding agents more dependable for day-to-day engineering work, not just better at generating snippets.

## License

MIT. See [LICENSE](LICENSE).

التثبيت

ثبّت المهارة من https://github.com/robert-hoffmann/uncle-bob

هذه المهارة غير منشورة في سجلّ ClawHub. الصق النص في وكيل البرمجة لديك — Claude Code أو Cursor أو Codex — وسيثبّت المهارة مباشرةً من المستودع المصدر.

افتح المستودع

الروابط