How twostraws/swiftui-agent-skill works
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.