# avdlee/swiftui-agent-skill architecture

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

- Interactive diagram: https://gitdiagram.com/avdlee/swiftui-agent-skill
- Repository: https://github.com/avdlee/swiftui-agent-skill

## Overview

This repository is **not an executable SwiftUI app**. It’s a **content + packaging repo** that publishes “Agent Skills” in the **Agent Skills open format** so AI coding tools can load them and use them during coding/review.

It contains:
- A primary skill: `swiftui-expert-skill/` (checklists + reference docs about SwiftUI best practices)
- A maintenance skill: `.agents/skills/update-swiftui-apis/` (workflow to scan Apple docs and refresh `latest-apis.md`)
- Distribution integrations:
- **skills.sh** install path (`npx skills add …`)
- **Claude Code plugin** metadata (`.claude-plugin/…`)
- CI automation (GitHub Actions) that appears to keep docs/README in sync and handle releases.

So the “system design” here is best expressed as **content architecture + distribution/consumption architecture + maintenance pipeline**, rather than the classic “frontend/backend/db”.

##### Core skill content
- `swiftui-expert-skill/SKILL.md`
- `swiftui-expert-skill/references/*.md`
- This is the core “runtime” artifact that users install into their AI tool.

##### Maintenance / updater skill
- `.agents/skills/update-swiftui-apis/SKILL.md`
- `.agents/skills/update-swiftui-apis/references/scan-manifest.md`
- This is a separate skill that **updates** part of the core skill content (notably `swiftui-expert-skill/references/latest-apis.md`).
- README states it requires **Sosumi MCP** (an external dependency).

##### Claude plugin packaging
- `.claude-plugin/plugin.json`
- `.claude-plugin/marketplace.json`
- These are **distribution descriptors** for Claude Code plugin installation and marketplace discovery.

##### Repo governance + automation
- `.github/workflows/release.yml`
- `.github/workflows/sync-readme-references.yml`
- `.github/scripts/sync-readme.js`
- There’s a CI pipeline that likely:
- publishes releases
- keeps README reference structure in sync with `references/` via the sync script
- This is your “build/release system”, even though it’s content-focused.

##### Documentation/process
- `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, `LICENSE`

**Goal:** Show the ecosystem and installation vectors.

**Include these nodes:**
- “This GitHub Repository”
- “AI Coding Tools that support Agent Skills format”
- Codex
- Claude
- Cursor
- “skills.sh” (distribution/installer path)
- “Claude Code Plugin Marketplace” (via `.claude-plugin/*`)
- “Developers / Teams” (humans)

- Repo → skills.sh: “skill index / install source”
- Developer machine → `npx skills add …` → AI Tool: “installs skill content”
- Repo → Claude Marketplace: “plugin metadata”
- Claude Code → GitHub repo: “fetches plugin/skill”
- Developers → Repo: “contribute updates via PRs”

There is no server. The “runtime” is the AI tool reading local skill files installed from this repo.

**Goal:** Show internal modules and their dependency relationships.

##### SwiftUI Expert Skill Package
- `swiftui-expert-skill/SKILL.md` (entrypoint/workflow)
- `swiftui-expert-skill/references/*` (knowledge base)
- Call out `latest-apis.md` as a frequently-updated artifact

##### Update SwiftUI APIs Skill (Maintenance)
- `.agents/skills/update-swiftui-apis/SKILL.md` (update workflow)
- `scan-manifest.md` (what to scan)

##### Claude Plugin Packaging
- `.claude-plugin/plugin.json`
- `.claude-plugin/marketplace.json`

##### CI / Automation
- `.github/workflows/*`
- `.github/scripts/sync-readme.js`

##### Docs & Governance
- `README.md`
- `CONTRIBUTING.md`
- `AGENTS.md`

- SwiftUI Expert Skill → References: “SKILL.md routes agent to specific reference docs”
- Update Skill → `latest-apis.md`: “updates API guidance”
- CI sync script → `README.md`: “generates/updates ‘REFERENCE STRUCTURE’ section”
- Release workflow → GitHub Releases: “tags + publishes versioned artifact”
- Claude plugin metadata → SwiftUI Expert Skill: “points to / bundles skill for plugin install” (even if indirect, show association)

**Important design principle to annotate:**
- “Agent Skills open format requires specific structure.”
(This explains why the directory structure is part of the “architecture”.)

**Goal:** Make the update mechanism and external dependency explicit.

**Nodes:**
- Maintainer (human)
- Update SwiftUI APIs Skill (`.agents/skills/update-swiftui-apis/…`)
- Sosumi MCP (external)
- Apple documentation sources (external; conceptual)
- Output file: `swiftui-expert-skill/references/latest-apis.md`
- PR → GitHub → CI workflows → merged main

- Maintainer triggers update skill → uses Sosumi MCP → queries Apple docs
- Update skill produces changes → modifies `latest-apis.md`
- Maintainer opens PR → CI runs sync-readme workflow → README updated if needed
- Merge → release workflow → publishes new release / version

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% Diagram A — System Context (installation & consumption)
    %% =========================================================
    subgraph "Diagram A — System Context (installation & consumption)"
        direction TB

        Devs["Developers / Teams"]:::human

        subgraph "GitHub Repository (this repo)"
            direction TB
            Repo["Content + Packaging Repository"]:::repo
            RepoSkillPkg["SwiftUI Expert Skill Package"]:::core
            RepoUpdSkill["Update SwiftUI APIs Skill"]:::maint
            RepoClaudePkg["Claude Plugin Packaging Metadata"]:::dist
            RepoCI["CI / Automation (GitHub Actions)"]:::ci
            RepoDocs["Docs & Governance"]:::docs
        end

        SkillsSh[("skills.sh\n(distribution/index)")]:::registry
        ClaudeMkt[("Claude Code Plugin Marketplace")]:::registry

        subgraph "AI Coding Tools (Agent Skills consumers)"
            direction TB
            ToolClaude["Claude / Claude Code"]:::external
            ToolCursor["Cursor"]:::external
            ToolCodex["Codex"]:::external
        end

        DevMachine["Developer Machine\n(npx skills add …)"]:::human

        Repo -->|"skill_index/install_source"| SkillsSh
        Repo -->|"plugin_metadata"| ClaudeMkt

        Devs -->|"runs_install"| DevMachine
        DevMachine -->|"installs_folder swiftui-expert-skill/"| ToolClaude
        DevMachine -->|"installs_folder swiftui-expert-skill/"| ToolCursor
        DevMachine -->|"installs_folder swiftui-expert-skill/"| ToolCodex

        ToolClaude -->|"fetches_plugin_or_skill"| Repo
        Devs -->|"contribute_updates_via_PRs"| Repo
    end

    %% =========================================================
    %% Diagram B — Repo Component Diagram (internal architecture)
    %% =========================================================
    subgraph "Diagram B — Repo Component Diagram (internal architecture)"
        direction TB

        NoteFormat["Note: Agent Skills open format requires\nspecific directory + entrypoint structure"]:::note

        subgraph "1) SwiftUI Expert Skill Package"
            direction TB
            SkillPkg["swiftui-expert-skill/"]:::core
            SkillEntry["SKILL.md (Entrypoint)"]:::core
            SkillRefs["references/ (Knowledge Base)"]:::core
            LatestApis["latest-apis.md (Frequently updated)"]:::core
        end

        subgraph "2) Update SwiftUI APIs Skill (Maintenance)"
            direction TB
            UpdPkg[".agents/skills/update-swiftui-apis/"]:::maint
            UpdEntry["SKILL.md (Update workflow)"]:::maint
            ScanManifest["scan-manifest.md (What to scan)"]:::maint
            Sosumi["Sosumi MCP (external dependency)"]:::external
        end

        subgraph "3) Claude Plugin Packaging"
            direction TB
            ClaudePkg[".claude-plugin/"]:::dist
            PluginJson["plugin.json"]:::dist
            MarketplaceJson["marketplace.json"]:::dist
        end

        subgraph "4) CI / Automation"
            direction TB
            CIWorkflows[".github/workflows/"]:::ci
            ReleaseYml["release.yml"]:::ci
            SyncYml["sync-readme-references.yml"]:::ci
            CIScripts[".github/scripts/"]:::ci
            SyncScript["sync-readme.js"]:::ci
            Releases[("GitHub Releases")]:::registry
        end

        subgraph "5) Docs & Governance"
            direction TB
            Readme["README.md"]:::docs
            Contrib["CONTRIBUTING.md"]:::docs
            Agents["AGENTS.md"]:::docs
            License["LICENSE"]:::docs
            CopilotInstr["copilot-instructions.md"]:::docs
        end

        NoteFormat -->|"constrains_structure"| SkillPkg
        NoteFormat -->|"constrains_structure"| UpdPkg

        SkillPkg -->|"contains"| SkillEntry
        SkillPkg -->|"contains"| SkillRefs
        SkillRefs -->|"includes"| LatestApis
        SkillEntry -->|"routes_agent_to_reference_docs"| SkillRefs

        UpdPkg -->|"contains"| UpdEntry
        UpdPkg -->|"contains"| ScanManifest
        UpdEntry -.->|"uses"| Sosumi
        UpdPkg -->|"updates"| LatestApis

        ClaudePkg -->|"contains"| PluginJson
        ClaudePkg -->|"contains"| MarketplaceJson
        PluginJson -->|"points_to_or_bundles"| SkillPkg
        MarketplaceJson -->|"enables_discovery_of"| ClaudePkg

        CIWorkflows -->|"includes"| ReleaseYml
        CIWorkflows -->|"includes"| SyncYml
        CIScripts -->|"includes"| SyncScript

        SyncYml -->|"runs"| SyncScript
        SyncScript -->|"generates_or_updates_REFERENCE_STRUCTURE"| Readme

        ReleaseYml -->|"tags_and_publishes_versioned_artifact"| Releases

        Readme -->|"documents"| SkillPkg
        Contrib -->|"governs_contribution_flow"| SkillPkg
        Agents -->|"repo_agent_guidelines"| SkillPkg
        CopilotInstr -->|"assistant_repo_guidance"| SkillPkg
        License -->|"license_terms"| SkillPkg
    end

    %% =========================================================
    %% Diagram C — Maintenance / Data Flow (update loop)
    %% =========================================================
    subgraph "Diagram C — Maintenance / Data Flow (update loop)"
        direction TB

        Maintainer["Maintainer (human)"]:::human
        AppleDocs["Apple Documentation Sources"]:::external
        PR["Pull Request"]:::repo
        GitHub["GitHub Repo (main branch)"]:::repo

        subgraph "Update Mechanism"
            direction TB
            UpdSkillFlow["Update SwiftUI APIs Skill\n(.agents/skills/update-swiftui-apis/)"]:::maint
            SosumiFlow["Sosumi MCP"]:::external
            LatestApisOut["Output: latest-apis.md\n(swiftui-expert-skill/references/)"]:::core
        end

        subgraph "CI Enforcement"
            direction TB
            SyncCI["sync-readme-references.yml"]:::ci
            ReleaseCI["release.yml"]:::ci
            ReadmeOut["README.md (updated if needed)"]:::docs
            ReleasesOut[("GitHub Releases")]:::registry
        end

        Maintainer -->|"triggers_update_skill"| UpdSkillFlow
        UpdSkillFlow -.->|"invokes"| SosumiFlow
        SosumiFlow -.->|"queries"| AppleDocs
        UpdSkillFlow -->|"writes_updates"| LatestApisOut

        Maintainer -->|"opens"| PR
        PR -->|"proposes_changes_to"| GitHub
        GitHub -->|"CI_runs_on_PR"| SyncCI
        SyncCI -->|"syncs_reference_tree"| ReadmeOut

        GitHub -->|"merge_to_main"| GitHub
        GitHub -->|"on_release"| ReleaseCI
        ReleaseCI -->|"publishes"| ReleasesOut
    end

    %% =========================================================
    %% Click Events (from component_mapping)
    %% =========================================================
    click SkillPkg "https://github.com/avdlee/swiftui-agent-skill/tree/main/swiftui-expert-skill/"
    click SkillEntry "https://github.com/avdlee/swiftui-agent-skill/blob/main/swiftui-expert-skill/SKILL.md"
    click SkillRefs "https://github.com/avdlee/swiftui-agent-skill/tree/main/swiftui-expert-skill/references/"
    click LatestApis "https://github.com/avdlee/swiftui-agent-skill/blob/main/swiftui-expert-skill/references/latest-apis.md"

    click UpdPkg "https://github.com/avdlee/swiftui-agent-skill/tree/main/.agents/skills/update-swiftui-apis/"
    click UpdEntry "https://github.com/avdlee/swiftui-agent-skill/blob/main/.agents/skills/update-swiftui-apis/SKILL.md"
    click ScanManifest "https://github.com/avdlee/swiftui-agent-skill/blob/main/.agents/skills/update-swiftui-apis/references/scan-manifest.md"

    click ClaudePkg "https://github.com/avdlee/swiftui-agent-skill/tree/main/.claude-plugin/"
    click PluginJson "https://github.com/avdlee/swiftui-agent-skill/blob/main/.claude-plugin/plugin.json"
    click MarketplaceJson "https://github.com/avdlee/swiftui-agent-skill/blob/main/.claude-plugin/marketplace.json"

    click CIWorkflows "https://github.com/avdlee/swiftui-agent-skill/tree/main/.github/workflows/"
    click ReleaseYml "https://github.com/avdlee/swiftui-agent-skill/blob/main/.github/workflows/release.yml"
    click SyncYml "https://github.com/avdlee/swiftui-agent-skill/blob/main/.github/workflows/sync-readme-references.yml"
    click CIScripts "https://github.com/avdlee/swiftui-agent-skill/tree/main/.github/scripts/"
    click SyncScript "https://github.com/avdlee/swiftui-agent-skill/blob/main/.github/scripts/sync-readme.js"

    click Readme "https://github.com/avdlee/swiftui-agent-skill/blob/main/README.md"
    click Contrib "https://github.com/avdlee/swiftui-agent-skill/blob/main/CONTRIBUTING.md"
    click Agents "https://github.com/avdlee/swiftui-agent-skill/blob/main/AGENTS.md"
    click License "https://github.com/avdlee/swiftui-agent-skill/tree/main/LICENSE"
    click CopilotInstr "https://github.com/avdlee/swiftui-agent-skill/blob/main/.github/copilot-instructions.md"

    %% =========================================================
    %% Styles (color-coded)
    %% =========================================================
    classDef core fill:#1f6feb,stroke:#0b3d91,stroke-width:1.5px,color:#ffffff
    classDef maint fill:#7c3aed,stroke:#4c1d95,stroke-width:1.5px,color:#ffffff
    classDef dist fill:#f59e0b,stroke:#92400e,stroke-width:1.5px,color:#111827
    classDef ci fill:#22c55e,stroke:#166534,stroke-width:1.5px,color:#052e16
    classDef docs fill:#38bdf8,stroke:#075985,stroke-width:1.5px,color:#0b1220
    classDef external fill:#9ca3af,stroke:#374151,stroke-dasharray: 4 3,stroke-width:1.5px,color:#111827
    classDef registry fill:#fb7185,stroke:#9f1239,stroke-width:1.5px,color:#111827
    classDef human fill:#e5e7eb,stroke:#6b7280,stroke-width:1.5px,color:#111827
    classDef repo fill:#111827,stroke:#334155,stroke-width:1.5px,color:#ffffff
    classDef note fill:#fef3c7,stroke:#b45309,stroke-width:1.5px,color:#111827
```
