# pantheon-org/skill-quality-auditor architecture

> Architecture diagram of the GitHub repository pantheon-org/skill-quality-auditor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pantheon-org/skill-quality-auditor
- Repository: https://github.com/pantheon-org/skill-quality-auditor

## Overview

1. **Repository purpose**
   - This is a Go-based CLI for auditing “skills” represented as `SKILL.md` files.
   - Its core job is to score a skill against a 9-dimension rubric, detect duplication, generate remediation guidance, and validate supporting artifacts/evals.

2. **Top-level execution path**
   - `main.go` and `cmd/root.go` form the CLI entrypoint.
   - Subcommands under `cmd/` implement the user-facing workflows: `evaluate`, `batch`, `analyze`, `duplication`, `aggregate`, `remediate`, `trend`, `validate`, `init`, `update`, and `prune`.
   - The CLI is the orchestration layer; most other packages are domain engines or output adapters.

3. **Skill evaluation pipeline**
   - `scorer/` contains the D1–D9 dimension logic, grade thresholds, and shared scoring utilities.
   - Input is a skill directory or `SKILL.md`; output is a structured score, grade, and warnings tied to specific dimensions.
   - The scoring layer is intentionally split by dimension so each criterion has its own boundary and can evolve independently.

4. **Analysis and signal extraction**
   - `analysis/` provides TF-IDF keyword extraction and pattern detectors used to characterize a skill beyond its raw score.
   - This layer feeds commands like `analyze` and also supports reporting by identifying structural signals, repeated concepts, and notable patterns.
   - `internal/tokenize/` is the low-level text normalization boundary used by analysis and similarity logic.

5. **Duplication detection subsystem**
   - `duplication/` computes similarity between skills using Jaccard-style overlap and inventory/similarity helpers.
   - It powers the `duplication` command and supports family-level consolidation analysis.
   - This subsystem is separate from scoring: it answers “how much overlap exists?” rather than “how good is this skill?”

6. **Reporting and persistence**
   - `reporter/` converts raw scoring/analysis results into human-readable or machine-readable outputs.
   - It also handles storing audit snapshots and generating remediation plans.
   - `trend` depends on persisted audit history to compare score deltas over time, so the reporting layer is also the repository’s audit archive interface.

7. **Validation and quality gates**
   - `cmd/validate.go` plus reporter validation helpers check repository conventions and artifact/report structure.
   - This is the quality-control boundary for generated content, especially review reports and remediation plans.
   - CI uses these checks as gates, so invalid artifact structure is treated as a release-quality issue, not just a formatting problem.

8. **Agent/environment bootstrapping**
   - `agents/registry.go` defines supported agent targets for the `init` command.
   - This subsystem is responsible for installing or registering the auditor skill into external agent environments, making it a deployment/onboarding boundary rather than part of scoring.

9. **Embedded assets and specs**
   - `cmd/assets/` and `.agents/skills/` contain the bundled skill content, schemas, templates, eval scenarios, and reference docs used at runtime.
   - These assets are effectively the product’s embedded specification: they define expected file shapes, evaluation scenarios, remediation templates, and command behavior references.
   - `docs/ADR/` records architectural decisions that explain why major boundaries exist and should be treated as the design history.

10. **External service boundary**
   - `internal/llmclient/` abstracts provider-specific clients for OpenAI, Anthropic, and Gemini behind a shared interface.
   - This is an optional integration boundary for any LLM-assisted features, insulated from the main scoring engine so provider changes do not leak into core CLI logic.

11. **Automation and release workflow**
   - `.github/workflows/` defines CI, release, and skill-quality checks; `scripts/` contains install and maintenance scripts.
   - `goreleaser`, `release-please`, and the install script support distribution of the CLI binary, while CI validates tests, linting, and repository quality.
   - The architecture therefore includes a build/release pipeline as a first-class system boundary, not just a developer convenience.

12. **Test and fixture model**
   - `testdata/fixtures/` provides representative skill directories used to test the evaluator, analyzer, and validator behavior.
   - Tests are organized around the same subsystem boundaries as production code, which suggests the repo is structured around end-to-end command behavior plus focused unit logic.

13. **How the pieces fit together**
   - Typical flow: the CLI loads a skill, the scorer computes dimension scores, analysis and duplication engines add diagnostics, and reporter formats/stores the result.
   - Optional flows: `trend` reads stored audits, `remediate` generates fix guidance, `aggregate` reasons about a skill family, and `validate` checks output artifacts.
   - The main architectural separation is between command orchestration, domain engines, reporting/persistence, and embedded specification/assets.

Main entry points: [`cmd`](https://github.com/pantheon-org/skill-quality-auditor/tree/main/cmd) (workflows), [`reporter`](https://github.com/pantheon-org/skill-quality-auditor/tree/main/reporter) (reporter), [`analysis`](https://github.com/pantheon-org/skill-quality-auditor/tree/main/analysis) (analysis), [`duplication`](https://github.com/pantheon-org/skill-quality-auditor/tree/main/duplication) (duplication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI orchestration"]
  node_main_go["main.go<br/>entrypoint<br/>[main.go]"]
  node_cmd_root["root cmd<br/>CLI root<br/>[root.go]"]
  node_cmd_workflows["workflows<br/>CLI commands"]
end

subgraph group_group_engine["Core engines"]
  node_scorer[("scorer<br/>9-dim engine")]
  node_analysis{{"analysis<br/>signal engine"}}
  node_tokenize["tokenize<br/>text normalize"]
  node_duplication[("duplication<br/>similarity engine")]
end

subgraph group_group_reporting["Reporting and audit"]
  node_reporter["reporter<br/>output layer"]
  node_store[("audit store<br/>history store<br/>[store.go]")]
  node_remediation["remediation<br/>plan generator<br/>[remediation.go]"]
  node_validate["validate<br/>quality gate<br/>[validate.go]"]
end

subgraph group_group_integrations["Integrations"]
  node_agents["agents<br/>bootstrap"]
  node_llmclient["llm client<br/>provider adapter"]
end

subgraph group_group_spec["Embedded spec"]
  node_cmd_assets["cmd assets<br/>bundled spec"]
  node_skill_assets["skill specs<br/>embedded skills<br/>[skills]"]
  node_docs_adr["ADR docs<br/>design history"]
end

subgraph group_group_delivery["Delivery pipeline"]
  node_ci_workflows["CI workflows<br/>automation<br/>[workflows]"]
  node_scripts["scripts"]
end

node_main_go -->|"starts"| node_cmd_root
node_cmd_root -->|"dispatches"| node_cmd_workflows
node_cmd_workflows -->|"scores"| node_scorer
node_cmd_workflows -->|"analyzes"| node_analysis
node_cmd_workflows -->|"compares"| node_duplication
node_cmd_workflows -->|"formats"| node_reporter
node_cmd_workflows -->|"checks"| node_validate
node_scorer -->|"normalizes"| node_tokenize
node_analysis -->|"tokenizes"| node_tokenize
node_duplication -->|"tokenizes"| node_tokenize
node_reporter -->|"persists"| node_store
node_reporter -->|"generates"| node_remediation
node_analysis -->|"feeds"| node_reporter
node_duplication -->|"feeds"| node_reporter
node_validate -->|"validates"| node_reporter
node_agents -->|"supports init"| node_cmd_workflows
node_llmclient -.->|"optional"| node_cmd_workflows
node_cmd_assets -->|"supplies"| node_cmd_workflows
node_skill_assets -->|"installs"| node_agents
node_docs_adr -->|"documents"| node_scorer
node_docs_adr -->|"documents"| node_reporter
node_ci_workflows -->|"gates"| node_validate
node_ci_workflows -->|"runs"| node_scripts

click node_main_go "https://github.com/pantheon-org/skill-quality-auditor/blob/main/main.go"
click node_cmd_root "https://github.com/pantheon-org/skill-quality-auditor/blob/main/cmd/root.go"
click node_cmd_workflows "https://github.com/pantheon-org/skill-quality-auditor/tree/main/cmd"
click node_scorer "https://github.com/pantheon-org/skill-quality-auditor/tree/main/scorer"
click node_analysis "https://github.com/pantheon-org/skill-quality-auditor/tree/main/analysis"
click node_tokenize "https://github.com/pantheon-org/skill-quality-auditor/tree/main/internal/tokenize"
click node_duplication "https://github.com/pantheon-org/skill-quality-auditor/tree/main/duplication"
click node_reporter "https://github.com/pantheon-org/skill-quality-auditor/tree/main/reporter"
click node_store "https://github.com/pantheon-org/skill-quality-auditor/blob/main/reporter/store.go"
click node_remediation "https://github.com/pantheon-org/skill-quality-auditor/blob/main/reporter/remediation.go"
click node_validate "https://github.com/pantheon-org/skill-quality-auditor/blob/main/cmd/validate.go"
click node_agents "https://github.com/pantheon-org/skill-quality-auditor/tree/main/agents"
click node_llmclient "https://github.com/pantheon-org/skill-quality-auditor/tree/main/internal/llmclient"
click node_cmd_assets "https://github.com/pantheon-org/skill-quality-auditor/tree/main/cmd/assets"
click node_skill_assets "https://github.com/pantheon-org/skill-quality-auditor/blob/main/.agents/skills"
click node_docs_adr "https://github.com/pantheon-org/skill-quality-auditor/tree/main/docs/ADR"
click node_ci_workflows "https://github.com/pantheon-org/skill-quality-auditor/blob/main/.github/workflows"
click node_scripts "https://github.com/pantheon-org/skill-quality-auditor/tree/main/scripts"

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_main_go,node_cmd_root,node_cmd_workflows toneBlue
class node_scorer,node_analysis,node_tokenize,node_duplication toneAmber
class node_reporter,node_store,node_remediation,node_validate toneMint
class node_agents,node_llmclient toneRose
class node_cmd_assets,node_skill_assets,node_docs_adr toneIndigo
class node_ci_workflows,node_scripts toneTeal
```

## Components

### CLI orchestration

Entrypoint and user-facing commands that coordinate repository workflows.

- [main.go](https://github.com/pantheon-org/skill-quality-auditor/blob/main/main.go): entrypoint · Program entry that hands off to the CLI root command. · `main.go`
- [root cmd](https://github.com/pantheon-org/skill-quality-auditor/blob/main/cmd/root.go): CLI root · Command tree setup and shared CLI wiring. · `cmd/root.go`
- [workflows](https://github.com/pantheon-org/skill-quality-auditor/tree/main/cmd): CLI commands · Evaluate, batch, analyze, duplication, aggregate, remediate, trend, validate, init, update, and prune commands. · `cmd`

### Core engines

Domain logic for scoring, analysis, duplication, and validation.

- [scorer](https://github.com/pantheon-org/skill-quality-auditor/tree/main/scorer): 9-dim engine · Dimension scoring, thresholds, grades, and shared scoring utilities. · `scorer`
- [analysis](https://github.com/pantheon-org/skill-quality-auditor/tree/main/analysis): signal engine · Keyword extraction and pattern detection for structural signals beyond raw score. · `analysis`
- [tokenize](https://github.com/pantheon-org/skill-quality-auditor/tree/main/internal/tokenize): text normalize · Low-level tokenization and normalization used by analysis and similarity logic. · `internal/tokenize`
- [duplication](https://github.com/pantheon-org/skill-quality-auditor/tree/main/duplication): similarity engine · Jaccard-style overlap, inventory, and similarity helpers for skill duplication. · `duplication`

### Reporting and audit

Formatting, persistence, remediation, and trend/history access.

- [reporter](https://github.com/pantheon-org/skill-quality-auditor/tree/main/reporter): output layer · Turns scores and analysis into reports, remediation plans, and persisted audits. · `reporter`
- [audit store](https://github.com/pantheon-org/skill-quality-auditor/blob/main/reporter/store.go): history store · Persistence boundary for saved audits and trend comparisons. · `reporter/store.go`
- [remediation](https://github.com/pantheon-org/skill-quality-auditor/blob/main/reporter/remediation.go): plan generator · Creates remediation guidance and structured fix plans. · `reporter/remediation.go`
- [validate](https://github.com/pantheon-org/skill-quality-auditor/blob/main/cmd/validate.go): quality gate · Checks repository conventions and artifact/report structure. · `cmd/validate.go`

### Integrations

External runtime boundaries and environment bootstrap logic.

- [agents](https://github.com/pantheon-org/skill-quality-auditor/tree/main/agents): bootstrap · Registers supported agent targets and installs the auditor skill into external environments. · `agents`
- [llm client](https://github.com/pantheon-org/skill-quality-auditor/tree/main/internal/llmclient): provider adapter · Provider-agnostic wrapper over OpenAI, Anthropic, and Gemini clients. · `internal/llmclient`

### Embedded spec

Bundled assets, reference material, and design history that define expected behavior.

- [cmd assets](https://github.com/pantheon-org/skill-quality-auditor/tree/main/cmd/assets): bundled spec · Embedded schemas, templates, references, evals, and command asset docs used at runtime. · `cmd/assets`
- [skill specs](https://github.com/pantheon-org/skill-quality-auditor/blob/main/.agents/skills): embedded skills · Bundled SKILL.md content, schemas, templates, eval scenarios, and references for agent skills. · `.agents/skills`
- [ADR docs](https://github.com/pantheon-org/skill-quality-auditor/tree/main/docs/ADR): design history · Architecture decision records explaining major boundaries and policies. · `docs/ADR`

### Delivery pipeline

Automation, scripts, and release/CI workflow boundary.

- [CI workflows](https://github.com/pantheon-org/skill-quality-auditor/blob/main/.github/workflows): automation · GitHub Actions, release tooling, and quality checks for build and publication. · `.github/workflows`
- [scripts](https://github.com/pantheon-org/skill-quality-auditor/tree/main/scripts): ops scripts · Install and maintenance scripts supporting setup and release workflows. · `scripts`

## Connections

- main.go → root cmd: starts · Main hands execution to the root CLI command.
- root cmd → workflows: dispatches · Root command exposes the user-facing subcommands.
- workflows → scorer: scores · Evaluate and batch commands invoke the dimension scoring engine.
- workflows → analysis: analyzes · Analyze and reporting-oriented commands use signal extraction.
- workflows → duplication: compares · Duplication and aggregate workflows use similarity detection.
- workflows → reporter: formats · Commands pass results into report generation and remediation output.
- workflows → validate: checks · Validate command gates generated artifacts and repository conventions.
- scorer → tokenize: normalizes · Scoring logic shares token/text normalization helpers where needed.
- analysis → tokenize: tokenizes · Pattern and TF-IDF analysis consume normalized tokens.
- duplication → tokenize: tokenizes · Similarity logic relies on shared tokenization for overlap comparison.
- reporter → audit store: persists · Reporter stores audit snapshots and serves trend history.
- reporter → remediation: generates · Reporter produces remediation plans from audit findings.
- analysis → reporter: feeds · Analysis outputs are incorporated into human-readable reports.
- duplication → reporter: feeds · Duplication findings are rendered through the reporting layer.
- validate → reporter: validates · Validation helpers check report and remediation structure.
- agents → workflows: supports init · Agent registry powers onboarding and installation workflows.
- llm client → workflows: optional · LLM-backed features are isolated behind a provider adapter boundary.
- cmd assets → workflows: supplies · Embedded command assets define schemas, templates, and reference docs.
- skill specs → agents: installs · Bundled skill content and specs support agent environment bootstrap.
- ADR docs → scorer: documents · ADR history explains scoring dimension and threshold design choices.
- ADR docs → reporter: documents · ADR history captures reporting and remediation architecture decisions.
- CI workflows → validate: gates · CI uses validation and quality checks as release gates.
- CI workflows → scripts: runs · Automation and release jobs rely on maintenance scripts.
