# wenyuchiou/ai-research-skills architecture

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

- Interactive diagram: https://gitdiagram.com/wenyuchiou/ai-research-skills
- Repository: https://github.com/wenyuchiou/ai-research-skills

## Overview

AI Research Skills is a catalog and distribution layer for portable research skills, organized as an eight-stage workflow with explicit evidence-aware handoffs and human decision gates. The README describes the principal path: a researcher installs the workspace, requests a research outcome, and progresses through the lifecycle; the separate research-hub runtime executes resumable workflows. The tree shows the catalog and marketplace metadata, but not the skill implementation files or runtime source. Thus the skill-stage nodes represent documented capabilities, not inspected implementations; external integrations are shown only where the README documents them.

Main entry points: [`.claude-plugin/marketplace.json`](https://github.com/wenyuchiou/ai-research-skills/blob/main/.claude-plugin/marketplace.json) (Plugin Marketplace), [`docs/pipeline.md`](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md) (Orientation), [`catalog/skills.yml`](https://github.com/wenyuchiou/ai-research-skills/blob/main/catalog/skills.yml) (Skill Catalog), [`docs/img/hitl-state-machine.mmd`](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/img/hitl-state-machine.mmd) (Human Decision Gates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_distribution["Catalog and Distribution"]
  node_skill_catalog[("Skill Catalog<br/>[skills.yml]")]
  node_marketplace["Plugin Marketplace<br/>[marketplace.json]"]
  node_portable_skills["Portable Skills"]
  node_writing_plugin["Writing Plugin"]
  node_zotero_plugin["Zotero Plugin"]
  node_delegation_plugins["Delegation Plugins"]
end

subgraph group_lifecycle["Research Lifecycle"]
  node_orientation["Orientation<br/>[pipeline.md]"]
  node_literature["Literature Discovery<br/>[pipeline.md]"]
  node_design["Research Design<br/>[pipeline.md]"]
  node_data["Data and Experiments<br/>[pipeline.md]"]
  node_analysis["Analysis and Synthesis<br/>[pipeline.md]"]
  node_manuscript["Manuscript<br/>[pipeline.md]"]
  node_review["Scientific Review<br/>[pipeline.md]"]
  node_release["Release<br/>[pipeline.md]"]
end

subgraph group_controls["Trust and Extensions"]
  node_research_hub["Research Hub Runtime"]
  node_human_gates["Human Decision Gates"]
  node_truth_stores[("Truth Stores")]
  node_collab_harness["Collaboration Harness"]
end

node_researcher(("Researcher"))

node_skill_catalog -->|"catalogs"| node_portable_skills
node_marketplace -->|"distributes"| node_portable_skills
node_researcher -->|"installs"| node_marketplace
node_researcher -->|"requests work"| node_portable_skills
node_portable_skills -->|"guides"| node_orientation
node_orientation -->|"hands off"| node_literature
node_literature -->|"hands off"| node_design
node_design -->|"hands off"| node_data
node_data -->|"hands off"| node_analysis
node_analysis -->|"hands off"| node_manuscript
node_manuscript -->|"hands off"| node_review
node_review -->|"hands off"| node_release
node_researcher -->|"runs workflows"| node_research_hub
node_research_hub -->|"pauses at"| node_human_gates
node_research_hub -.->|"integrates with"| node_truth_stores
node_research_hub -.->|"governed by"| node_collab_harness
node_marketplace -->|"offers"| node_writing_plugin
node_marketplace -->|"offers"| node_zotero_plugin
node_marketplace -->|"offers"| node_delegation_plugins

click node_skill_catalog "https://github.com/wenyuchiou/ai-research-skills/blob/main/catalog/skills.yml"
click node_marketplace "https://github.com/wenyuchiou/ai-research-skills/blob/main/.claude-plugin/marketplace.json"
click node_orientation "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_literature "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_design "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_data "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_analysis "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_manuscript "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_review "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_release "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md"
click node_human_gates "https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/img/hitl-state-machine.mmd"

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_skill_catalog,node_marketplace,node_portable_skills,node_writing_plugin,node_zotero_plugin,node_delegation_plugins toneBlue
class node_orientation,node_literature,node_design,node_data,node_analysis,node_manuscript,node_review,node_release toneAmber
class node_research_hub,node_human_gates,node_truth_stores,node_collab_harness toneMint
class node_researcher toneIndigo
```

## Components

### Catalog and Distribution

- [Skill Catalog](https://github.com/wenyuchiou/ai-research-skills/blob/main/catalog/skills.yml): `catalog/skills.yml`
- [Plugin Marketplace](https://github.com/wenyuchiou/ai-research-skills/blob/main/.claude-plugin/marketplace.json): `.claude-plugin/marketplace.json`
- **Portable Skills**
- **Writing Plugin**
- **Zotero Plugin**
- **Delegation Plugins**

### Research Lifecycle

- [Orientation](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`
- [Literature Discovery](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`
- [Research Design](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`
- [Data and Experiments](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`
- [Analysis and Synthesis](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`
- [Manuscript](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`
- [Scientific Review](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`
- [Release](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/pipeline.md): `docs/pipeline.md`

### Trust and Extensions

- **Research Hub Runtime**
- [Human Decision Gates](https://github.com/wenyuchiou/ai-research-skills/blob/main/docs/img/hitl-state-machine.mmd): `docs/img/hitl-state-machine.mmd`
- **Truth Stores**
- **Collaboration Harness**

### Other components

- **Researcher**

## Connections

- Skill Catalog → Portable Skills: catalogs (evidence: `README.md`)
- Plugin Marketplace → Portable Skills: distributes (evidence: `README.md`)
- Researcher → Plugin Marketplace: installs (evidence: `README.md`)
- Researcher → Portable Skills: requests work (evidence: `README.md`)
- Portable Skills → Orientation: guides (evidence: `README.md`)
- Orientation → Literature Discovery: hands off (evidence: `README.md`)
- Literature Discovery → Research Design: hands off (evidence: `README.md`)
- Research Design → Data and Experiments: hands off (evidence: `README.md`)
- Data and Experiments → Analysis and Synthesis: hands off (evidence: `README.md`)
- Analysis and Synthesis → Manuscript: hands off (evidence: `README.md`)
- Manuscript → Scientific Review: hands off (evidence: `README.md`)
- Scientific Review → Release: hands off (evidence: `README.md`)
- Researcher → Research Hub Runtime: runs workflows (evidence: `README.md`)
- Research Hub Runtime → Human Decision Gates: pauses at (evidence: `README.md`)
- Research Hub Runtime → Truth Stores: integrates with (evidence: `README.md`)
- Research Hub Runtime → Collaboration Harness: governed by (evidence: `README.md`)
- Plugin Marketplace → Writing Plugin: offers (evidence: `README.md`)
- Plugin Marketplace → Zotero Plugin: offers (evidence: `README.md`)
- Plugin Marketplace → Delegation Plugins: offers (evidence: `README.md`)
