# twostraws/swiftui-agent-skill architecture

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

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

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **not a running app/service**; it’s a **content-based “Agent Skill” package** (AgentSkills format) that AI coding assistants can install and invoke to review/generate **modern SwiftUI guidance** (API usage, design, performance, accessibility, navigation, etc.).

- **Distribution/installation** (how the skill gets onto a developer machine / into a project)
- **Invocation/runtime integration** (how Claude Code/Codex/Gemini/Cursor trigger the skill)
- **Skill contents & structure** (what files are used as the knowledge/rules source)
- **Data flow** (user prompt → agent triggers skill → skill content injected → assistant produces output)

This is closer to a **plugin/content pack architecture** than a typical backend/frontend architecture.

From the tree, the repo is essentially:

##### Core skill content
- `swiftui-pro/SKILL.md`
The primary “skill” rules/checklist. This is the main artifact consumed by agent runtimes.

##### Agent runtime configuration
- `swiftui-pro/agents/openai.yaml`

##### Reference knowledge base (supporting docs)
- `swiftui-pro/references/*.md`
Topic modules: `accessibility`, `api`, `data`, `design`, `hygiene`, `navigation`, `performance`, `swift`, `views`. These are likely cited/used by SKILL.md (or intended as deeper context). Architecturally: “Knowledge modules / documentation corpus”.

##### Assets / branding
- `assets/` and `swiftui-pro/assets/`
Logos/images; not involved in runtime logic, but still part of distribution/package.

##### Repo-level meta
- `README.md`, `LICENSE`, `CODE_OF_CONDUCT.md`
Operational governance, onboarding, licensing.

##### README → key interactions to capture
The README tells you the operational flow:
- Install via Node:
`npx skills add https://github.com/twostraws/swiftui-agent-skill --skill swiftui-pro`
- Usable across multiple AI assistants (Claude Code, Codex, Gemini, Cursor, etc.)
- Triggering mechanisms:
- Claude Code: `/swiftui-pro`
- Codex: `$swiftui-pro`
- Also natural language triggers (“Use SwiftUI Pro skill…”)

So the “system” includes:
- **User developer**
- **AI coding assistant (host)** with a skill/plugin mechanism
- **npx / Node tooling** doing install
- **GitHub repo** (source of truth)
- **Local project scope vs global scope** install option (important boundary)

##### Recommended “as-many-components-as-possible” decomposition (specific to this repo)

- SwiftUI Pro Skill Package
- Rule set: `SKILL.md`
- Provider adapters:
- `agents/openai.yaml` (explicit)
- (Implicit) other hosts (Claude/Cursor/Gemini) — represent as “host-specific adapters” even if not present as files
- Knowledge modules:
- `references/accessibility.md`
- `references/api.md`
- `references/data.md`
- `references/design.md`
- `references/hygiene.md`
- `references/navigation.md`
- `references/performance.md`
- `references/swift.md`
- `references/views.md`
- Non-runtime assets:
- `assets/logo.svg` (from README)
- `swiftui-pro/assets/*`

- “Focus on accessibility” → prioritize `references/accessibility.md`
- “Check for deprecated API” → prioritize `references/api.md`
- “Look for performance problems” → prioritize `references/performance.md`

Even if the host runtime does not literally “route” like this, it’s an accurate conceptual model of how the content is intended to be used.

- Developer enters `/swiftui-pro Focus on accessibility`
- Host resolves skill name
- Loads config + SKILL.md + relevant references
- Produces output to developer

That combination captures both the operational lifecycle and the internal structure without pretending there’s an app backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Diagram A: Context / Ecosystem (C4 L1)
  %% =========================================================
  subgraph "A) Ecosystem Context: Distribution, Installation, Invocation"
    direction TB

    Dev["Developer"]:::actor

    subgraph "AI Coding Assistant Hosts (Runtime)"
      direction TB
      Host["AI Assistant Runtime\n(Claude Code / Codex / Cursor / Gemini)"]:::host
      Triggers["Invocation Interface\n/command, $command, or natural language"]:::host
    end

    subgraph "Distribution / Installer Tooling"
      direction TB
      NPX["Node + npx\n\"npx skills add ...\""]:::tool
      SkillsCLI["Agent Skills Installer\n(skills CLI)"]:::tool
    end

    subgraph "Upstream Source of Truth (External)"
      direction TB
      GitHub["GitHub Repository\n(twostraws/swiftui-agent-skill)"]:::external
      Spec["AgentSkills Format / Spec\n(agentskills.io)"]:::external
    end

    subgraph "Local Developer Environment"
      direction TB
      Workspace["Local Machine / Workspace"]:::boundary
      subgraph "Local Skill Registry (Scope Boundary)"
        direction TB
        GlobalReg[("Global Skill Registry\n(~/.agentskills or similar)")]:::storage
        ProjectReg[("Project Skill Registry\n(./.agentskills or similar)")]:::storage
      end
    end

    Dev -->|"install_skill"| NPX
    NPX -->|"executes"| SkillsCLI
    SkillsCLI -->|"fetch_repo_content"| GitHub
    SkillsCLI -->|"validate_format"| Spec
    SkillsCLI -->|"install_to_global"| GlobalReg
    SkillsCLI -->|"install_to_project"| ProjectReg

    Dev -->|"invoke_skill\n(/swiftui-pro, $swiftui-pro, NL)"| Triggers
    Triggers -->|"dispatch_to_runtime"| Host
    Host -->|"load_skill_content"| GlobalReg
    Host -->|"load_skill_content"| ProjectReg
    Host -->|"produce_swiftui_guidance\n(review, recommendations)"| Dev
  end

  %% =========================================================
  %% Diagram B: Skill Package Components (C4 L2/3 hybrid)
  %% =========================================================
  subgraph "B) Skill Package Internals: 'swiftui-pro' (Installed Deliverable)"
    direction TB

    PackageRoot["SwiftUI Pro Skill Package\n(deliverable: swiftui-pro/)"]:::package

    subgraph "Core Skill Content (Runtime-Critical)"
      direction TB
      SkillMD["SKILL.md\nPrimary Rules / Checklist"]:::artifact
    end

    subgraph "Provider / Runtime Adapter (Host-Specific)"
      direction TB
      AgentsDir["agents/"]:::dir
      OpenAIYAML["openai.yaml\nProvider Manifest / Adapter\n(OpenAI-family)"]:::artifact
      OtherAdapters["Other Host Adapters (Implicit)\n(Claude/Cursor/Gemini)"]:::note
    end

    subgraph "Reference Knowledge Base (Supporting Modules)"
      direction TB
      RefsDir["references/"]:::dir
      RefAccessibility["accessibility.md"]:::ref
      RefAPI["api.md"]:::ref
      RefData["data.md"]:::ref
      RefDesign["design.md"]:::ref
      RefHygiene["hygiene.md"]:::ref
      RefNavigation["navigation.md"]:::ref
      RefPerformance["performance.md"]:::ref
      RefSwift["swift.md"]:::ref
      RefViews["views.md"]:::ref
    end

    subgraph "Non-Runtime Assets / Branding"
      direction TB
      RepoAssets["assets/"]:::assets
      PackagedAssets["swiftui-pro/assets/"]:::assets
      AssetsNote["Note: Assets are distributed but not required at runtime"]:::note
    end

    subgraph "Repo Meta (Onboarding / Governance)"
      direction TB
      Readme["README.md\nInstall + Invocation Instructions"]:::meta
      License["LICENSE"]:::meta
      CoC["CODE_OF_CONDUCT.md"]:::meta
    end

    PackageRoot -->|"contains"| SkillMD
    PackageRoot -->|"contains"| AgentsDir
    AgentsDir -->|"contains"| OpenAIYAML
    AgentsDir -.->|"conceptual"| OtherAdapters

    PackageRoot -->|"contains"| RefsDir
    RefsDir -->|"modules"| RefAccessibility
    RefsDir -->|"modules"| RefAPI
    RefsDir -->|"modules"| RefData
    RefsDir -->|"modules"| RefDesign
    RefsDir -->|"modules"| RefHygiene
    RefsDir -->|"modules"| RefNavigation
    RefsDir -->|"modules"| RefPerformance
    RefsDir -->|"modules"| RefSwift
    RefsDir -->|"modules"| RefViews

    PackageRoot -->|"contains"| PackagedAssets
    RepoAssets -->|"branding"| AssetsNote
    PackagedAssets -->|"branding"| AssetsNote

    %% Runtime usage (host reads artifacts)
    Host -->|"reads_manifest"| OpenAIYAML
    Host -->|"injects_rules"| SkillMD
    Host -.->|"optional_on_demand_load"| RefAccessibility
    Host -.->|"optional_on_demand_load"| RefAPI
    Host -.->|"optional_on_demand_load"| RefData
    Host -.->|"optional_on_demand_load"| RefDesign
    Host -.->|"optional_on_demand_load"| RefHygiene
    Host -.->|"optional_on_demand_load"| RefNavigation
    Host -.->|"optional_on_demand_load"| RefPerformance
    Host -.->|"optional_on_demand_load"| RefSwift
    Host -.->|"optional_on_demand_load"| RefViews

    SkillMD -.->|"may_reference"| RefAccessibility
    SkillMD -.->|"may_reference"| RefAPI
    SkillMD -.->|"may_reference"| RefData
    SkillMD -.->|"may_reference"| RefDesign
    SkillMD -.->|"may_reference"| RefHygiene
    SkillMD -.->|"may_reference"| RefNavigation
    SkillMD -.->|"may_reference"| RefPerformance
    SkillMD -.->|"may_reference"| RefSwift
    SkillMD -.->|"may_reference"| RefViews
  end

  %% =========================================================
  %% Diagram C: Invocation Sequence (Optional)
  %% =========================================================
  subgraph "C) Invocation Sequence (Host-Dependent; Dashed = Conceptual)"
    direction TB

    Step1["1. Developer prompt\n\"/swiftui-pro Focus on accessibility\""]:::sequence
    Step2["2. Host resolves skill name\n\"swiftui-pro\""]:::sequence
    Step3["3. Host loads adapter/manifest\n(openai.yaml or equivalent)"]:::sequence
    Step4["4. Host injects canonical rules\n(SKILL.md)"]:::sequence
    Step5["5. Host selects references\n(e.g., accessibility.md)"]:::sequence
    Step6["6. Assistant generates output\nSwiftUI review + recommendations"]:::sequence

    Step1 --> Step2 --> Step3 --> Step4
    Step4 -.-> Step5
    Step5 --> Step6
  end

  %% Cross-links to show where Step artifacts live
  Step3 -->|"reads"| OpenAIYAML
  Step4 -->|"reads"| SkillMD
  Step5 -.->|"prioritizes"| RefAccessibility

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click PackageRoot "https://github.com/twostraws/swiftui-agent-skill/tree/main/swiftui-pro/"
  click SkillMD "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/SKILL.md"
  click OpenAIYAML "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/agents/openai.yaml"
  click AgentsDir "https://github.com/twostraws/swiftui-agent-skill/tree/main/swiftui-pro/agents/"
  click RefsDir "https://github.com/twostraws/swiftui-agent-skill/tree/main/swiftui-pro/references/"
  click RefAccessibility "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/accessibility.md"
  click RefAPI "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/api.md"
  click RefData "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/data.md"
  click RefDesign "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/design.md"
  click RefHygiene "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/hygiene.md"
  click RefNavigation "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/navigation.md"
  click RefPerformance "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/performance.md"
  click RefSwift "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/swift.md"
  click RefViews "https://github.com/twostraws/swiftui-agent-skill/blob/main/swiftui-pro/references/views.md"
  click RepoAssets "https://github.com/twostraws/swiftui-agent-skill/tree/main/assets/"
  click PackagedAssets "https://github.com/twostraws/swiftui-agent-skill/tree/main/swiftui-pro/assets/"
  click Readme "https://github.com/twostraws/swiftui-agent-skill/blob/main/README.md"
  click License "https://github.com/twostraws/swiftui-agent-skill/tree/main/LICENSE"
  click CoC "https://github.com/twostraws/swiftui-agent-skill/blob/main/CODE_OF_CONDUCT.md"

  %% =========================================================
  %% Styles (Color Coding)
  %% =========================================================
  classDef actor fill:#ffffff,stroke:#111827,stroke-width:2,color:#111827
  classDef host fill:#dbeafe,stroke:#1d4ed8,stroke-width:2,color:#0f172a
  classDef tool fill:#dcfce7,stroke:#16a34a,stroke-width:2,color:#052e16
  classDef external fill:#e5e7eb,stroke:#374151,stroke-width:2,color:#111827
  classDef storage fill:#fef3c7,stroke:#b45309,stroke-width:2,color:#111827
  classDef boundary fill:#f3f4f6,stroke:#6b7280,stroke-width:2,color:#111827,stroke-dasharray: 6 4
  classDef package fill:#ffedd5,stroke:#c2410c,stroke-width:2,color:#7c2d12
  classDef artifact fill:#fed7aa,stroke:#9a3412,stroke-width:2,color:#7c2d12
  classDef dir fill:#ffd7b5,stroke:#9a3412,stroke-width:2,color:#7c2d12
  classDef ref fill:#fffbeb,stroke:#d97706,stroke-width:2,color:#7c2d12
  classDef assets fill:#f5f3ff,stroke:#6d28d9,stroke-width:2,color:#1f2937
  classDef meta fill:#f3f4f6,stroke:#374151,stroke-width:2,color:#111827
  classDef note fill:#fff7ed,stroke:#c2410c,stroke-width:1,color:#7c2d12,stroke-dasharray: 4 4
  classDef sequence fill:#ecfeff,stroke:#0891b2,stroke-width:2,color:#0f172a
```
