# mark-groves/skills-nexus architecture

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

- Interactive diagram: https://gitdiagram.com/mark-groves/skills-nexus
- Repository: https://github.com/mark-groves/skills-nexus

## Overview

skills-nexus is a repository-owned foundry for portable agent-workflow plugins, with evaluation and quality contracts plus an evidence-based improvement loop. The main workflow is author or use a packaged skill, evaluate it against repository cases (with behavioral proof through the documented Cloud Agent path), then process execution observations and promote accepted evidence into regression cases. Separate capabilities include local harness deployment and draw.io shape-catalog/diagram support. The graph reflects README-documented links and sampled tool responsibilities; unsampled implementation wiring is intentionally omitted.

Main entry points: [`plugins`](https://github.com/mark-groves/skills-nexus/tree/main/plugins) (Plugin bundles), [`plugins/drawio/skills/cloud-diagram/SKILL.md`](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/cloud-diagram/SKILL.md) (Cloud diagram skill), [`plugins/drawio/skills/drawio-shapes/SKILL.md`](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/drawio-shapes/SKILL.md) (Draw.io shapes skill), [`scripts/validate_repo.py`](https://github.com/mark-groves/skills-nexus/blob/main/scripts/validate_repo.py) (Repository validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugins["Portable plugins"]
  node_bundles["Plugin bundles"]
  node_git["Git workflow"]
  node_skillarchitect["Skill architect<br/>[SKILL.md]"]
end

subgraph group_eval["Evaluation and learning"]
  node_casecatalog["Evaluation cases<br/>[eval_cases.py]"]
  node_evaldata[("Skill eval suites")]
  node_proof["Behavioral proof<br/>[eval_evidence.py]"]
  node_observation["Observation handling<br/>[core.py]"]
  node_classify["Observation triage"]
  node_promote["Case promotion<br/>[promote.py]"]
end

subgraph group_contracts["Repository contracts"]
  node_deploy["Skill deployment<br/>[deploy-skills.sh]"]
  node_harnessconfig["Harness targets"]
  node_repository["Plugin index"]
  node_validation["Repository validation<br/>[validate_repo.py]"]
  node_schemas["Versioned contracts"]
end

subgraph group_drawio["Diagram tooling"]
  node_cloudskill["Cloud diagram skill<br/>[SKILL.md]"]
  node_shapeskill["Draw.io shapes skill<br/>[SKILL.md]"]
  node_catalog["Shape catalog<br/>[shape_catalog.py]"]
  node_diagramcheck["Diagram validation"]
  node_shapeextract["Shape extraction<br/>[extract.py]"]
  node_cataloggenerate["Catalog generation"]
end

node_author(("Skill author"))
node_agent(("Agent harness"))
node_cloudagent(("Cloud Agent"))

node_author -->|"authors skills"| node_bundles
node_bundles -->|"includes"| node_git
node_bundles -->|"includes"| node_skillarchitect
node_bundles -->|"includes"| node_cloudskill
node_bundles -->|"includes"| node_shapeskill
node_agent -->|"invokes"| node_git
node_agent -->|"invokes"| node_skillarchitect
node_agent -->|"invokes"| node_cloudskill
node_agent -->|"invokes"| node_shapeskill
node_deploy -->|"resolves bundles"| node_repository
node_deploy -->|"targets"| node_harnessconfig
node_repository -->|"indexes"| node_bundles
node_validation -->|"checks contract"| node_repository
node_validation -->|"validates"| node_evaldata
node_validation -->|"validates"| node_harnessconfig
node_casecatalog -->|"loads cases"| node_evaldata
node_cloudagent -->|"runs prove path"| node_proof
node_proof -->|"uses cases"| node_casecatalog
node_agent -.->|"execution evidence"| node_observation
node_observation -->|"records evidence"| node_classify
node_classify -->|"accepts evidence"| node_promote
node_promote -->|"updates cases"| node_evaldata
node_observation -->|"validates format"| node_schemas
node_cloudskill -->|"looks up shapes"| node_catalog
node_cloudskill -->|"validates diagrams"| node_diagramcheck
node_shapeskill -->|"extracts definitions"| node_shapeextract
node_shapeskill -->|"generates catalogs"| node_cataloggenerate
node_shapeextract -->|"provides shape data"| node_cataloggenerate

click node_bundles "https://github.com/mark-groves/skills-nexus/tree/main/plugins"
click node_git "https://github.com/mark-groves/skills-nexus/tree/main/plugins/git-workflow/skills"
click node_skillarchitect "https://github.com/mark-groves/skills-nexus/blob/main/plugins/skill-architect/skills/skill-architect/SKILL.md"
click node_cloudskill "https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/cloud-diagram/SKILL.md"
click node_shapeskill "https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/drawio-shapes/SKILL.md"
click node_catalog "https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/cloud-diagram/scripts/shape_catalog.py"
click node_diagramcheck "https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/cloud-diagram/scripts/validate_diagram.py"
click node_shapeextract "https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/drawio-shapes/scripts/extract.py"
click node_cataloggenerate "https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/drawio-shapes/scripts/generate_catalog.py"
click node_deploy "https://github.com/mark-groves/skills-nexus/blob/main/scripts/deploy-skills.sh"
click node_harnessconfig "https://github.com/mark-groves/skills-nexus/tree/main/harnesses"
click node_repository "https://github.com/mark-groves/skills-nexus/blob/main/scripts/plugin_repository.py"
click node_validation "https://github.com/mark-groves/skills-nexus/blob/main/scripts/validate_repo.py"
click node_casecatalog "https://github.com/mark-groves/skills-nexus/blob/main/scripts/eval_cases.py"
click node_evaldata "https://github.com/mark-groves/skills-nexus/tree/main/evals"
click node_proof "https://github.com/mark-groves/skills-nexus/blob/main/scripts/eval_evidence.py"
click node_observation "https://github.com/mark-groves/skills-nexus/blob/main/scripts/skill_observation/core.py"
click node_classify "https://github.com/mark-groves/skills-nexus/tree/main/scripts/skill_triage"
click node_promote "https://github.com/mark-groves/skills-nexus/blob/main/scripts/skill_triage/promote.py"
click node_schemas "https://github.com/mark-groves/skills-nexus/tree/main/schemas"

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_bundles,node_git,node_skillarchitect toneBlue
class node_casecatalog,node_evaldata,node_proof,node_observation,node_classify,node_promote toneAmber
class node_deploy,node_harnessconfig,node_repository,node_validation,node_schemas toneMint
class node_cloudskill,node_shapeskill,node_catalog,node_diagramcheck,node_shapeextract,node_cataloggenerate toneRose
class node_author,node_agent,node_cloudagent toneIndigo
```

## Components

### Portable plugins

- [Plugin bundles](https://github.com/mark-groves/skills-nexus/tree/main/plugins): `plugins`
- [Git workflow](https://github.com/mark-groves/skills-nexus/tree/main/plugins/git-workflow/skills): `plugins/git-workflow/skills`
- [Skill architect](https://github.com/mark-groves/skills-nexus/blob/main/plugins/skill-architect/skills/skill-architect/SKILL.md): `plugins/skill-architect/skills/skill-architect/SKILL.md`

### Evaluation and learning

- [Evaluation cases](https://github.com/mark-groves/skills-nexus/blob/main/scripts/eval_cases.py): `scripts/eval_cases.py`
- [Skill eval suites](https://github.com/mark-groves/skills-nexus/tree/main/evals): `evals`
- [Behavioral proof](https://github.com/mark-groves/skills-nexus/blob/main/scripts/eval_evidence.py): `scripts/eval_evidence.py`
- [Observation handling](https://github.com/mark-groves/skills-nexus/blob/main/scripts/skill_observation/core.py): `scripts/skill_observation/core.py`
- [Observation triage](https://github.com/mark-groves/skills-nexus/tree/main/scripts/skill_triage): `scripts/skill_triage`
- [Case promotion](https://github.com/mark-groves/skills-nexus/blob/main/scripts/skill_triage/promote.py): `scripts/skill_triage/promote.py`

### Repository contracts

- [Skill deployment](https://github.com/mark-groves/skills-nexus/blob/main/scripts/deploy-skills.sh): `scripts/deploy-skills.sh`
- [Harness targets](https://github.com/mark-groves/skills-nexus/tree/main/harnesses): `harnesses`
- [Plugin index](https://github.com/mark-groves/skills-nexus/blob/main/scripts/plugin_repository.py): `scripts/plugin_repository.py`
- [Repository validation](https://github.com/mark-groves/skills-nexus/blob/main/scripts/validate_repo.py): `scripts/validate_repo.py`
- [Versioned contracts](https://github.com/mark-groves/skills-nexus/tree/main/schemas): `schemas`

### Diagram tooling

- [Cloud diagram skill](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/cloud-diagram/SKILL.md): `plugins/drawio/skills/cloud-diagram/SKILL.md`
- [Draw.io shapes skill](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/drawio-shapes/SKILL.md): `plugins/drawio/skills/drawio-shapes/SKILL.md`
- [Shape catalog](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/cloud-diagram/scripts/shape_catalog.py): `plugins/drawio/skills/cloud-diagram/scripts/shape_catalog.py`
- [Diagram validation](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/cloud-diagram/scripts/validate_diagram.py): `plugins/drawio/skills/cloud-diagram/scripts/validate_diagram.py`
- [Shape extraction](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/drawio-shapes/scripts/extract.py): `plugins/drawio/skills/drawio-shapes/scripts/extract.py`
- [Catalog generation](https://github.com/mark-groves/skills-nexus/blob/main/plugins/drawio/skills/drawio-shapes/scripts/generate_catalog.py): `plugins/drawio/skills/drawio-shapes/scripts/generate_catalog.py`

### Other components

- **Skill author**
- **Agent harness**
- **Cloud Agent**

## Connections

- Skill author → Plugin bundles: authors skills
- Plugin bundles → Git workflow: includes
- Plugin bundles → Skill architect: includes
- Plugin bundles → Cloud diagram skill: includes
- Plugin bundles → Draw.io shapes skill: includes
- Agent harness → Git workflow: invokes
- Agent harness → Skill architect: invokes
- Agent harness → Cloud diagram skill: invokes
- Agent harness → Draw.io shapes skill: invokes
- Skill deployment → Plugin index: resolves bundles
- Skill deployment → Harness targets: targets
- Plugin index → Plugin bundles: indexes
- Repository validation → Plugin index: checks contract
- Repository validation → Skill eval suites: validates
- Repository validation → Harness targets: validates
- Evaluation cases → Skill eval suites: loads cases
- Cloud Agent → Behavioral proof: runs prove path
- Behavioral proof → Evaluation cases: uses cases
- Agent harness → Observation handling: execution evidence
- Observation handling → Observation triage: records evidence
- Observation triage → Case promotion: accepts evidence
- Case promotion → Skill eval suites: updates cases
- Observation handling → Versioned contracts: validates format
- Cloud diagram skill → Shape catalog: looks up shapes
- Cloud diagram skill → Diagram validation: validates diagrams
- Draw.io shapes skill → Shape extraction: extracts definitions
- Draw.io shapes skill → Catalog generation: generates catalogs
- Shape extraction → Catalog generation: provides shape data