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