# wondelai/skills architecture

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

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

## Overview

#### Purpose and Entry Points
This is a Markdown-first distribution repository for 50 expert-framework agent skills and 12 orchestration metaskills. It targets Claude-family agents, Codex, Cursor, Windsurf, Pi, and agentskills.io-compatible tooling; it is not a runtime application or web service. Canonical user-facing entry points are individual `SKILL.md` files, plugin marketplaces, and `npx skills` installation. Key paths: `README.md`, `jobs-to-be-done/SKILL.md`, `.claude-plugin/marketplace.json`.

#### Canonical Skill Content
Each top-level skill directory is a self-contained knowledge module: an instruction contract in `SKILL.md` plus supporting reference documents. Agents load the skill to apply a named product, business, UX, or engineering framework. This is the source content that all distribution forms expose. Examples: `clean-architecture/SKILL.md`, `clean-architecture/references/dependency-rule.md`, `cro-methodology/SKILL.md`.

#### Metaskill Orchestration Layer
Twelve metaskills compose multiple individual skills into ordered, interactive journeys for creating, improving, or growing businesses, websites, apps, and codebases. They persist progress and generated decision artifacts in the consuming project’s `docs/` directory, allowing session resumption. Artifact conventions are documented in `docs/ARTIFACT-REGISTRY.md`; metaskill entry modules include `create-app/SKILL.md`, `improve-code-quality/SKILL.md`, and `design-code-architecture/SKILL.md`.

#### Plugin Collection Boundary
Skills are packaged into curated domain collections for plugin consumers. Plugin manifests define the installable collections; collection directories expose selected skills rather than redefining their contents. The primary manifest source is `.claude-plugin/marketplace.json`, with Codex plugin outputs under `plugins/*/.codex-plugin/plugin.json`, e.g. `plugins/systems-architecture/.codex-plugin/plugin.json` and `plugins/metaskills/.codex-plugin/plugin.json`.

#### Cross-Agent Distribution Mirrors
The repository maintains platform-specific skill trees for agent discovery. These are deployment/distribution representations of the canonical top-level skills, including Claude, Codex, Cursor, Pi, and Windsurf targets. Important boundaries are `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.pi/skills/`, and `.windsurf/skills/`; consumers should treat top-level skill directories as the authoring source unless synchronization rules state otherwise.

#### Generation and Synchronization Flow
Maintenance scripts transform canonical marketplace and skill content into consumer-facing artifacts. `scripts/generate-codex-plugins.sh` generates Codex plugin definitions from the Claude marketplace source; `scripts/sync-ide-skills.sh` synchronizes cross-IDE skill mirrors; `scripts/sync-marketplace-versions.sh` updates marketplace version metadata. GitHub Actions automates marketplace-version synchronization via `.github/workflows/sync-marketplace-version.yml`.

#### Runtime, Infrastructure, and External Dependencies
No application server, database, or deployed runtime appears in the repository. Execution happens inside installed AI coding-agent runtimes and through Node-based `npx skills` installation. External integration points are the Claude/Codex plugin systems, agentskills.io-compatible clients, skills.sh, GitHub Actions, and the public catalog at `https://skills.wondel.ai/`.

Main entry points: [`jobs-to-be-done/SKILL.md`](https://github.com/wondelai/skills/blob/main/jobs-to-be-done/SKILL.md) (Canonical skill modules), [`scripts/sync-ide-skills.sh`](https://github.com/wondelai/skills/blob/main/scripts/sync-ide-skills.sh) (IDE skill synchronizer), [`.claude-plugin/marketplace.json`](https://github.com/wondelai/skills/blob/main/.claude-plugin/marketplace.json) (Claude marketplace), [`create-app/SKILL.md`](https://github.com/wondelai/skills/blob/main/create-app/SKILL.md) (Metaskill journeys)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Canonical authoring"]
  node_readme["Repository guide<br/>documentation<br/>[README.md]"]
  node_skill_modules["Canonical skill modules<br/>Markdown skills<br/>[SKILL.md]"]
  node_skill_references["Skill references<br/>supporting docs<br/>[dependency-rule.md]"]
  node_architecture_skill["Architecture skill<br/>example module<br/>[SKILL.md]"]
  node_cro_skill["CRO skill<br/>example module<br/>[SKILL.md]"]
  node_metaskills["Metaskill journeys<br/>orchestration skills<br/>[SKILL.md]"]
  node_artifact_registry["Artifact registry<br/>convention docs"]
end

subgraph group_packaging["Packaging &amp; automation"]
  node_marketplace["Claude marketplace<br/>marketplace manifest<br/>[marketplace.json]"]
  node_codex_generator{{"Codex plugin generator<br/>shell generator"}}
  node_mirror_sync{{"IDE skill synchronizer<br/>shell sync<br/>[sync-ide-skills.sh]"}}
  node_version_sync{{"Marketplace version sync<br/>shell sync"}}
  node_github_action{{"Version-sync workflow<br/>GitHub Actions workflow"}}
end

subgraph group_distribution["Distribution surfaces"]
  node_codex_plugins["Codex plugin outputs<br/>plugin manifests<br/>[plugin.json]"]
  node_claude_mirror["Claude skill mirror<br/>skill tree"]
  node_codex_mirror["Codex skill mirror<br/>skill tree"]
  node_ide_mirrors["Cursor, Pi &amp; Windsurf mirrors<br/>skill trees"]
end

subgraph group_consumption["Consumer environment"]
  node_agent_runtimes(("AI agent runtimes<br/>external consumers"))
  node_npx_install{{"npx skills installer<br/>external installer"}}
  node_consumer_docs["Consuming project docs<br/>persisted artifacts"]
  node_public_catalog["Public skill catalog<br/>external catalog"]
end

node_readme -->|"documents"| node_skill_modules
node_skill_references -->|"supports"| node_architecture_skill
node_architecture_skill -.->|"is a module"| node_skill_modules
node_cro_skill -.->|"is a module"| node_skill_modules
node_skill_modules -->|"composed by"| node_metaskills
node_artifact_registry -->|"defines artifacts for"| node_metaskills
node_metaskills -->|"persists progress"| node_consumer_docs
node_skill_modules -->|"curated into"| node_marketplace
node_marketplace -->|"source manifest"| node_codex_generator
node_codex_generator -->|"generates"| node_codex_plugins
node_skill_modules -->|"sync source"| node_mirror_sync
node_mirror_sync -->|"synchronizes"| node_claude_mirror
node_mirror_sync -->|"synchronizes"| node_codex_mirror
node_mirror_sync -->|"synchronizes"| node_ide_mirrors
node_github_action -->|"automates"| node_version_sync
node_version_sync -->|"updates versions"| node_marketplace
node_marketplace -->|"plugin collections"| node_agent_runtimes
node_codex_plugins -->|"installable plugins"| node_agent_runtimes
node_claude_mirror -->|"skill discovery"| node_agent_runtimes
node_codex_mirror -->|"skill discovery"| node_agent_runtimes
node_ide_mirrors -->|"skill discovery"| node_agent_runtimes
node_npx_install -->|"installs skills for"| node_agent_runtimes
node_skill_modules -->|"distributed through"| node_npx_install
node_skill_modules -->|"published in"| node_public_catalog

click node_readme "https://github.com/wondelai/skills/blob/main/README.md"
click node_skill_modules "https://github.com/wondelai/skills/blob/main/jobs-to-be-done/SKILL.md"
click node_skill_references "https://github.com/wondelai/skills/blob/main/clean-architecture/references/dependency-rule.md"
click node_architecture_skill "https://github.com/wondelai/skills/blob/main/clean-architecture/SKILL.md"
click node_cro_skill "https://github.com/wondelai/skills/blob/main/cro-methodology/SKILL.md"
click node_metaskills "https://github.com/wondelai/skills/blob/main/create-app/SKILL.md"
click node_artifact_registry "https://github.com/wondelai/skills/blob/main/docs/ARTIFACT-REGISTRY.md"
click node_marketplace "https://github.com/wondelai/skills/blob/main/.claude-plugin/marketplace.json"
click node_codex_generator "https://github.com/wondelai/skills/blob/main/scripts/generate-codex-plugins.sh"
click node_mirror_sync "https://github.com/wondelai/skills/blob/main/scripts/sync-ide-skills.sh"
click node_version_sync "https://github.com/wondelai/skills/blob/main/scripts/sync-marketplace-versions.sh"
click node_github_action "https://github.com/wondelai/skills/blob/main/.github/workflows/sync-marketplace-version.yml"
click node_codex_plugins "https://github.com/wondelai/skills/blob/main/plugins/systems-architecture/.codex-plugin/plugin.json"

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_readme,node_skill_modules,node_skill_references,node_architecture_skill,node_cro_skill,node_metaskills,node_artifact_registry toneBlue
class node_marketplace,node_codex_generator,node_mirror_sync,node_version_sync,node_github_action toneAmber
class node_codex_plugins,node_claude_mirror,node_codex_mirror,node_ide_mirrors toneMint
class node_agent_runtimes,node_npx_install,node_consumer_docs,node_public_catalog toneRose
```

## Components

### Canonical authoring

Markdown source skills and orchestration content.

- [Repository guide](https://github.com/wondelai/skills/blob/main/README.md): documentation · Explains the skill catalog and installation options. · `README.md`
- [Canonical skill modules](https://github.com/wondelai/skills/blob/main/jobs-to-be-done/SKILL.md): Markdown skills · Top-level SKILL.md modules are the authoring source. · `jobs-to-be-done/SKILL.md`
- [Skill references](https://github.com/wondelai/skills/blob/main/clean-architecture/references/dependency-rule.md): supporting docs · Framework details support each skill instruction contract. · `clean-architecture/references/dependency-rule.md`
- [Architecture skill](https://github.com/wondelai/skills/blob/main/clean-architecture/SKILL.md): example module · `clean-architecture/SKILL.md`
- [CRO skill](https://github.com/wondelai/skills/blob/main/cro-methodology/SKILL.md): example module · `cro-methodology/SKILL.md`
- [Metaskill journeys](https://github.com/wondelai/skills/blob/main/create-app/SKILL.md): orchestration skills · Twelve interactive workflows compose individual skills. · `create-app/SKILL.md`
- [Artifact registry](https://github.com/wondelai/skills/blob/main/docs/ARTIFACT-REGISTRY.md): convention docs · Defines resumable decision artifacts for consuming projects. · `docs/ARTIFACT-REGISTRY.md`

### Packaging & automation

Manifests and scripts produce distribution artifacts.

- [Claude marketplace](https://github.com/wondelai/skills/blob/main/.claude-plugin/marketplace.json): marketplace manifest · Primary source for curated plugin collections. · `.claude-plugin/marketplace.json`
- [Codex plugin generator](https://github.com/wondelai/skills/blob/main/scripts/generate-codex-plugins.sh): shell generator · Derives Codex plugin definitions from the marketplace. · `scripts/generate-codex-plugins.sh`
- [IDE skill synchronizer](https://github.com/wondelai/skills/blob/main/scripts/sync-ide-skills.sh): shell sync · Synchronizes canonical skills into agent-specific trees. · `scripts/sync-ide-skills.sh`
- [Marketplace version sync](https://github.com/wondelai/skills/blob/main/scripts/sync-marketplace-versions.sh): shell sync · Updates marketplace version metadata. · `scripts/sync-marketplace-versions.sh`
- [Version-sync workflow](https://github.com/wondelai/skills/blob/main/.github/workflows/sync-marketplace-version.yml): GitHub Actions workflow · `.github/workflows/sync-marketplace-version.yml`

### Distribution surfaces

Agent-specific mirrors and installable plugin outputs.

- [Codex plugin outputs](https://github.com/wondelai/skills/blob/main/plugins/systems-architecture/.codex-plugin/plugin.json): plugin manifests · Generated installable Codex collections. · `plugins/systems-architecture/.codex-plugin/plugin.json`
- **Claude skill mirror**: skill tree
- **Codex skill mirror**: skill tree
- **Cursor, Pi & Windsurf mirrors**: skill trees · Platform-specific discovery copies of canonical skills.

### Consumer environment

Installed agent runtimes and consuming projects.

- **AI agent runtimes**: external consumers · Claude, Codex, Cursor, Windsurf, Pi, and compatible clients load skills.
- **npx skills installer**: external installer · Node-based installation surface.
- **Consuming project docs**: persisted artifacts · Metaskills save progress and decisions here for resumption.
- **Public skill catalog**: external catalog

## Connections

- Repository guide → Canonical skill modules: documents
- Skill references → Architecture skill: supports
- Architecture skill → Canonical skill modules: is a module
- CRO skill → Canonical skill modules: is a module
- Canonical skill modules → Metaskill journeys: composed by
- Artifact registry → Metaskill journeys: defines artifacts for
- Metaskill journeys → Consuming project docs: persists progress
- Canonical skill modules → Claude marketplace: curated into
- Claude marketplace → Codex plugin generator: source manifest
- Codex plugin generator → Codex plugin outputs: generates
- Canonical skill modules → IDE skill synchronizer: sync source
- IDE skill synchronizer → Claude skill mirror: synchronizes
- IDE skill synchronizer → Codex skill mirror: synchronizes
- IDE skill synchronizer → Cursor, Pi & Windsurf mirrors: synchronizes
- Version-sync workflow → Marketplace version sync: automates
- Marketplace version sync → Claude marketplace: updates versions
- Claude marketplace → AI agent runtimes: plugin collections
- Codex plugin outputs → AI agent runtimes: installable plugins
- Claude skill mirror → AI agent runtimes: skill discovery
- Codex skill mirror → AI agent runtimes: skill discovery
- Cursor, Pi & Windsurf mirrors → AI agent runtimes: skill discovery
- npx skills installer → AI agent runtimes: installs skills for
- Canonical skill modules → npx skills installer: distributed through
- Canonical skill modules → Public skill catalog: published in