# nbbaier/agent-skills architecture

> Architecture diagram of the GitHub repository nbbaier/agent-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nbbaier/agent-skills
- Repository: https://github.com/nbbaier/agent-skills

## Overview

#### Purpose and Distribution

This repository is a portable collection of instruction-driven “skills” for coding agents, not an executable application or service. Each skill packages a primary agent workflow in a `SKILL.md`, optionally supported by reference material and static assets. Consumers install or copy selected skill directories into an agent’s skill location.

Plugin metadata is provided at `.claude-plugin/plugin.json`; OpenCode-oriented metadata/configuration lives in `.oc/config.json` and `.oc/config.md`.

#### Primary Entry Points

The repository-level catalog and installation path are defined in `README.md`. Agent runtimes discover individual capabilities through their skill instruction documents, especially:

- `skills/blueprint/SKILL.md`
- `skills/goal-refiner/SKILL.md`
- `skills/implementation-guide/SKILL.md`

There is no server, build pipeline, database, or application runtime represented in the tree.

#### Skill Package Boundary

Each `skills/<name>/` directory is an independently consumable capability boundary. Its `SKILL.md` is the authoritative operational prompt/workflow; colocated `references/` files provide deeper procedures, templates, or domain guidance without necessarily being loaded first.

Representative packages include:

- Planning/specification: `skills/blueprint/SKILL.md`, `skills/blueprint/references/plan-template.md`
- Design discovery: `skills/ideation/SKILL.md`, `skills/goal-refiner/SKILL.md`
- Implementation/review guidance: `skills/implementation-guide/SKILL.md`, `skills/code-refactor-review/SKILL.md`

#### Planning and Execution Flow

The core planning-oriented flow is: refine an ambiguous goal, investigate and shape options, produce a decision-level specification, then generate execution-ready implementation guidance. `blueprint` explicitly contains supporting stages for reconnaissance, decomposition, destinations, and validation/closure:

- `skills/blueprint/references/recon.md`
- `skills/blueprint/references/decomposition.md`
- `skills/blueprint/references/closing-the-loop.md`

These documents make the repository particularly suited to downstream agent planning: they separate problem framing and evidence gathering from plan decomposition and completion criteria.

#### Specialized Guidance Modules

Several standalone skills constrain or improve particular engineering activities rather than orchestrating a full delivery lifecycle:

- UI/prototyping: `skills/wireframe/SKILL.md`, `skills/html-tools/SKILL.md`
- Frontend correctness: `skills/react-effect-patterns/SKILL.md`
- Operations/observability: `skills/logging-best-practices/SKILL.md`
- Visualization critique: `skills/tufte-viz/SKILL.md`
- Knowledge validation: `skills/quiz-gate/SKILL.md`

`wireframe` is the notable asset-bearing package, including a reusable static viewer template at `skills/wireframe/assets/site-template.html`.

#### External Dependencies and Lifecycle

The repository relies primarily on agent-host runtimes that understand installed skill directories, with explicit integration signals for Claude plugins and OpenCode. Installation may use Vercel’s external `skills` CLI (`npx skills add ...`), but no package manifest or runtime dependency is present here.

Legacy capabilities are intentionally isolated under `skills/deprecated/`, including a historical npm supply-chain audit shell script at `skills/deprecated/npm-supply-chain-security/scripts/audit.sh`. They should not be treated as part of the active architecture unless explicitly revived.

Main entry points: [`skills/blueprint/SKILL.md`](https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/SKILL.md) (Blueprint), [`skills/goal-refiner/SKILL.md`](https://github.com/nbbaier/agent-skills/blob/main/skills/goal-refiner/SKILL.md) (Goal refiner), [`skills/ideation/SKILL.md`](https://github.com/nbbaier/agent-skills/blob/main/skills/ideation/SKILL.md) (Ideation), [`skills/implementation-guide/SKILL.md`](https://github.com/nbbaier/agent-skills/blob/main/skills/implementation-guide/SKILL.md) (Implementation guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_distribution["Distribution"]
  node_catalog["Skill catalog<br/>repository guide<br/>[README.md]"]
  node_claude_plugin["Claude plugin metadata<br/>plugin manifest<br/>[plugin.json]"]
  node_opencode_config["OpenCode metadata<br/>host configuration<br/>[config.json]"]
  node_skill_host{{"Agent skill hosts<br/>external runtime"}}
  node_skills_cli{{"Skills CLI<br/>external installer"}}
end

subgraph group_planning["Planning Flow"]
  node_goal_refiner["Goal refiner<br/>skill workflow<br/>[SKILL.md]"]
  node_ideation["Ideation<br/>skill workflow<br/>[SKILL.md]"]
  node_blueprint["Blueprint<br/>skill workflow<br/>[SKILL.md]"]
  node_recon["Reconnaissance<br/>blueprint reference<br/>[recon.md]"]
  node_decomposition["Decomposition<br/>blueprint reference<br/>[decomposition.md]"]
  node_closure["Validation and closure<br/>blueprint reference"]
  node_implementation_guide["Implementation guide<br/>skill workflow<br/>[SKILL.md]"]
end

subgraph group_specialized["Specialized Skills"]
  node_review["Refactor review<br/>skill workflow<br/>[SKILL.md]"]
  node_wireframe["Wireframe<br/>skill workflow<br/>[SKILL.md]"]
  node_wireframe_template["Viewer template<br/>static asset<br/>[site-template.html]"]
  node_frontend_guidance["React effect patterns<br/>skill workflow<br/>[SKILL.md]"]
  node_operations_guidance["Logging practices<br/>skill workflow<br/>[SKILL.md]"]
end

subgraph group_legacy["Legacy"]
  node_deprecated_audit["Deprecated audit script<br/>legacy shell script<br/>[audit.sh]"]
end

node_catalog -->|"documents install via"| node_skills_cli
node_skills_cli -->|"installs selected skills into"| node_skill_host
node_claude_plugin -->|"integrates with"| node_skill_host
node_opencode_config -->|"configures"| node_skill_host
node_skill_host -->|"discovers"| node_goal_refiner
node_skill_host -->|"discovers"| node_blueprint
node_skill_host -->|"discovers"| node_implementation_guide
node_goal_refiner -->|"frames work for"| node_ideation
node_ideation -->|"shapes options into"| node_blueprint
node_blueprint -->|"uses"| node_recon
node_blueprint -->|"uses"| node_decomposition
node_blueprint -->|"uses"| node_closure
node_blueprint -->|"feeds specification to"| node_implementation_guide
node_wireframe -->|"uses"| node_wireframe_template
node_deprecated_audit -.->|"excluded from active capabilities"| node_skill_host

click node_catalog "https://github.com/nbbaier/agent-skills/blob/main/README.md"
click node_claude_plugin "https://github.com/nbbaier/agent-skills/blob/main/.claude-plugin/plugin.json"
click node_opencode_config "https://github.com/nbbaier/agent-skills/blob/main/.oc/config.json"
click node_goal_refiner "https://github.com/nbbaier/agent-skills/blob/main/skills/goal-refiner/SKILL.md"
click node_ideation "https://github.com/nbbaier/agent-skills/blob/main/skills/ideation/SKILL.md"
click node_blueprint "https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/SKILL.md"
click node_recon "https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/references/recon.md"
click node_decomposition "https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/references/decomposition.md"
click node_closure "https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/references/closing-the-loop.md"
click node_implementation_guide "https://github.com/nbbaier/agent-skills/blob/main/skills/implementation-guide/SKILL.md"
click node_review "https://github.com/nbbaier/agent-skills/blob/main/skills/code-refactor-review/SKILL.md"
click node_wireframe "https://github.com/nbbaier/agent-skills/blob/main/skills/wireframe/SKILL.md"
click node_wireframe_template "https://github.com/nbbaier/agent-skills/blob/main/skills/wireframe/assets/site-template.html"
click node_frontend_guidance "https://github.com/nbbaier/agent-skills/blob/main/skills/react-effect-patterns/SKILL.md"
click node_operations_guidance "https://github.com/nbbaier/agent-skills/blob/main/skills/logging-best-practices/SKILL.md"
click node_deprecated_audit "https://github.com/nbbaier/agent-skills/blob/main/skills/deprecated/npm-supply-chain-security/scripts/audit.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog,node_claude_plugin,node_opencode_config,node_skill_host,node_skills_cli toneBlue
class node_goal_refiner,node_ideation,node_blueprint,node_recon,node_decomposition,node_closure,node_implementation_guide toneAmber
class node_review,node_wireframe,node_wireframe_template,node_frontend_guidance,node_operations_guidance toneMint
class node_deprecated_audit toneRose
```

## Components

### Distribution

Repository catalog and host-runtime integration metadata.

- [Skill catalog](https://github.com/nbbaier/agent-skills/blob/main/README.md): repository guide · Documents installation and available skills. · `README.md`
- [Claude plugin metadata](https://github.com/nbbaier/agent-skills/blob/main/.claude-plugin/plugin.json): plugin manifest · Signals integration with Claude plugin hosts. · `.claude-plugin/plugin.json`
- [OpenCode metadata](https://github.com/nbbaier/agent-skills/blob/main/.oc/config.json): host configuration · Provides OpenCode-oriented configuration and documentation. · `.oc/config.json`
- **Agent skill hosts**: external runtime · Discover and run installed skill directories.
- **Skills CLI**: external installer · Optional npx-based installer for selected packages.

### Planning Flow

Composable skills for moving from an ambiguous goal to execution guidance.

- [Goal refiner](https://github.com/nbbaier/agent-skills/blob/main/skills/goal-refiner/SKILL.md): skill workflow · Turns an ambiguous goal into a clearer problem framing. · `skills/goal-refiner/SKILL.md`
- [Ideation](https://github.com/nbbaier/agent-skills/blob/main/skills/ideation/SKILL.md): skill workflow · Investigates and shapes solution options. · `skills/ideation/SKILL.md`
- [Blueprint](https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/SKILL.md): skill workflow · Produces a decision-level specification and planning workflow. · `skills/blueprint/SKILL.md`
- [Reconnaissance](https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/references/recon.md): blueprint reference · Guides evidence gathering before planning. · `skills/blueprint/references/recon.md`
- [Decomposition](https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/references/decomposition.md): blueprint reference · Guides plan breakdown into actionable work. · `skills/blueprint/references/decomposition.md`
- [Validation and closure](https://github.com/nbbaier/agent-skills/blob/main/skills/blueprint/references/closing-the-loop.md): blueprint reference · Defines completion and validation criteria. · `skills/blueprint/references/closing-the-loop.md`
- [Implementation guide](https://github.com/nbbaier/agent-skills/blob/main/skills/implementation-guide/SKILL.md): skill workflow · Generates execution-ready implementation guidance. · `skills/implementation-guide/SKILL.md`

### Specialized Skills

Standalone guidance for focused engineering activities.

- [Refactor review](https://github.com/nbbaier/agent-skills/blob/main/skills/code-refactor-review/SKILL.md): skill workflow · `skills/code-refactor-review/SKILL.md`
- [Wireframe](https://github.com/nbbaier/agent-skills/blob/main/skills/wireframe/SKILL.md): skill workflow · UI prototyping skill with reusable viewer assets. · `skills/wireframe/SKILL.md`
- [Viewer template](https://github.com/nbbaier/agent-skills/blob/main/skills/wireframe/assets/site-template.html): static asset · `skills/wireframe/assets/site-template.html`
- [React effect patterns](https://github.com/nbbaier/agent-skills/blob/main/skills/react-effect-patterns/SKILL.md): skill workflow · `skills/react-effect-patterns/SKILL.md`
- [Logging practices](https://github.com/nbbaier/agent-skills/blob/main/skills/logging-best-practices/SKILL.md): skill workflow · `skills/logging-best-practices/SKILL.md`

### Legacy

Intentionally isolated historical capabilities.

- [Deprecated audit script](https://github.com/nbbaier/agent-skills/blob/main/skills/deprecated/npm-supply-chain-security/scripts/audit.sh): legacy shell script · Historical npm supply-chain audit capability; not active architecture. · `skills/deprecated/npm-supply-chain-security/scripts/audit.sh`

## Connections

- Skill catalog → Skills CLI: documents install via
- Skills CLI → Agent skill hosts: installs selected skills into
- Claude plugin metadata → Agent skill hosts: integrates with
- OpenCode metadata → Agent skill hosts: configures
- Agent skill hosts → Goal refiner: discovers
- Agent skill hosts → Blueprint: discovers
- Agent skill hosts → Implementation guide: discovers
- Goal refiner → Ideation: frames work for
- Ideation → Blueprint: shapes options into
- Blueprint → Reconnaissance: uses
- Blueprint → Decomposition: uses
- Blueprint → Validation and closure: uses
- Blueprint → Implementation guide: feeds specification to
- Wireframe → Viewer template: uses
- Deprecated audit script → Agent skill hosts: excluded from active capabilities