If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Juanpe/SkeletonView shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5w ago
• 18 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Juanpe/SkeletonView repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Juanpe/SkeletonView.

What it runs against: a local clone of Juanpe/SkeletonView — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Juanpe/SkeletonView | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 62 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Juanpe/SkeletonView. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Juanpe/SkeletonView.git
#   cd SkeletonView
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Juanpe/SkeletonView and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Juanpe/SkeletonView(\\.git)?\\b" \\
  && ok "origin remote is Juanpe/SkeletonView" \\
  || miss "origin remote is not Juanpe/SkeletonView (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata" \\
  && ok ".swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata" \\
  || miss "missing critical file: .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata"
test -f "Examples/iOS Example/Sources/ViewController.swift" \\
  && ok "Examples/iOS Example/Sources/ViewController.swift" \\
  || miss "missing critical file: Examples/iOS Example/Sources/ViewController.swift"
test -f ".github/workflows/main.yml" \\
  && ok ".github/workflows/main.yml" \\
  || miss "missing critical file: .github/workflows/main.yml"
test -f ".swiftlint.yml" \\
  && ok ".swiftlint.yml" \\
  || miss "missing critical file: .swiftlint.yml"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 62 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~32d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Juanpe/SkeletonView"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SkeletonView is a Swift UIView extension library that renders elegant skeleton/placeholder screens while content loads asynchronously. It automatically generates animated shimmer effects over a hierarchy of UIViews (tables, collections, labels, images) to show users content is loading and preview the layout of incoming data — similar to LinkedIn's skeleton loading pattern but built natively for iOS. Single-package library structure: core skeleton logic is in compiled Swift, with example apps and tests organized alongside. Uses .swiftpm/ workspace for SPM integration, .swiftlint.yml for code quality gates, and a standard iOS package structure with resources in Assets/. CI workflows orchestrate testing, linting, and releases automatically.

iOS developers building apps with async data fetching (API calls, database queries) who need polished loading states without building custom placeholder views. Particularly useful for teams shipping consumer apps where perceived performance and user experience matter.

Production-ready and actively maintained. The repo shows comprehensive CI/CD setup (.github/workflows/ with pod_lib_lint, validations, CD, release automation), support for multiple package managers (CocoaPods, Carthage, SPM), and multilingual documentation (6+ README translations). Multiple shields indicate healthy community adoption.

Low risk for stability but single-maintainer dependent (Juanpe as primary author visible in repo). No explicit risks from the file structure; the Swift-only dependency footprint (133k lines) is self-contained. Consider checking open issues for edge cases with complex view hierarchies or concurrent animations.

Active maintenance visible from release automation workflows (.github/workflows/release.yml, pod_trunk.yml) and stale issue detection (.github/needs-attention.yml, stale.yml). Recent focus on multi-platform support (platforms badge in README) and documentation updates (multiple translations, FUNDING.yml for sponsorship).

Clone and install via: git clone https://github.com/Juanpe/SkeletonView.git && cd SkeletonView. For CocoaPods: add pod 'SkeletonView' to Podfile and pod install. For SPM: use .swiftpm/xcode/package.xcworkspace or add dependency via Xcode package manager UI.

Daily commands: Open .swiftpm/xcode/package.xcworkspace in Xcode or build via swift build. Run tests with swift test. CI validates via pod_lib_lint (CocoaPods spec), swiftlint (linting), and SPM compilation checks in .github/workflows/validations.yml.

• .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata — Swift Package Manager workspace configuration; defines how the library is built and distributed across iOS, tvOS, and macOS
• Examples/iOS Example/Sources/ViewController.swift — Primary integration example showing how to use SkeletonView API on UITableView and UICollectionView; essential reference for understanding the public API
• .github/workflows/main.yml — CI/CD pipeline defining build, test, and lint processes; critical for understanding quality gates contributors must pass
• .swiftlint.yml — SwiftLint configuration enforcing code style and quality standards across the entire codebase
• CONTRIBUTING.md — Contributor guidelines documenting workflow, PR expectations, and development setup required before submitting changes
• Examples/CollectionView/CollectionViewCell.swift — Demonstrates SkeletonView application on collection view cells; shows reusable cell skeletoning patterns

• Skeletonable Protocol (Swift Protocol, UIView extension) — Core abstraction defining which views can display skeleton loading states; implemented by UIView, UITableView, UICollectionView, etc.
  • Failure mode: Views not conforming to Skeletonable will not show skeleton; silent no-op on showSkeleton() call
• SkeletonView Framework (View Extension) (Swift Extensions, CABasicAnimation, CAGradientLayer) — Main API surface; provides showSkeleton(), hideSkeleton(), and configuration methods (color, animation type, gradient direction)
  • Failure mode: Runtime crashes if skeleton configuration is invalid (e.g., wrong animation type); no compile-time type safety
• View Hierarchy Scanner (UIView tree traversal, CALayer) — Recursively walks view tree at skeleton show-time; identifies all Skeletonable subviews and injects skeleton layers
  • Failure mode: May miss deeply nested custom views or views with hidden parent containers; performance degrades O(n) with view count
• Animation Engine (CABasicAnimation) — Drives gradient

Add a new skeleton animation type

1. Define animation configuration enum (e.g., for a new gradient direction or wave effect) (Examples/iOS Example/Sources/Constants.swift)
2. Implement animation logic in the core framework by extending UIView+SkeletonView protocol methods (.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata)
3. Add example usage in a demo ViewController to showcase the new animation (Examples/iOS Example/Sources/ViewController.swift)
4. Update CHANGELOG.md with new feature and run SwiftLint checks (CHANGELOG.md)

Add skeleton support to a new UIView subclass

1. Create a new example view controller demonstrating the target view type (e.g., UIStackView, UIProgressView) (Examples/iOS Example/Sources/UITextViewByCodeViewController.swift)
2. Conform the view to SkeletonView protocol (Skeletonable) in the example code (Examples/iOS Example/Sources/ViewController.swift)
3. Call showSkeleton() and hideSkeleton() lifecycle methods in the view controller (Examples/iOS Example/Sources/ViewController.swift)
4. Submit PR with example; CI pipeline validates via .github/workflows/main.yml (.github/workflows/main.yml)

Contribute a bug fix or enhancement

1. Fork and review CONTRIBUTING.md for branch naming and commit conventions (CONTRIBUTING.md)
2. Create feature branch and implement changes in the Swift Package source files (.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata)
3. Run local validation: SwiftLint checks via .swiftlint.yml and unit tests (.swiftlint.yml)
4. Push and open PR; CI/CD workflows in .github/workflows/ auto-validate; update CHANGELOG.md (CHANGELOG.md)

• Swift & iOS/tvOS/macOS SDK — Native platform framework; enables direct UIView/CALayer manipulation for smooth skeleton animations without third-party rendering dependencies
• Swift Package Manager (SPM) — Modern Swift dependency management; provides cross-platform distribution (iOS, tvOS, macOS) and reduces friction vs. CocoaPods/Carthage
• CABasicAnimation & CAGradientLayer — Low-level Core Animation primitives; enable efficient, GPU-accelerated skeleton animations without blocking main thread
• SwiftLint & Danger CI — Enforces consistent code quality and Swift style; prevents technical debt accumulation in a popular open-source library

• Protocol-based Skeletonable pattern vs. base class inheritance

  • Why: Allows optional skeleton support; developers choose which views are skeletonable without framework overhead
  • Consequence: Requires explicit conformance but enables flexible opt-in skeleton loading on any UIView subclass

• CABasicAnimation over custom rendering loops

  • Why: Leverages GPU acceleration and iOS animation runloop; reduces CPU usage and battery drain vs. Timer-based approaches
  • Consequence: Less fine-grained control but much better performance on lower-end devices

• View hierarchy scanning at runtime vs. compile-time code generation

  • Why: Dynamic approach; simple API (one-line showSkeleton()) and works with storyboards and programmatic layouts
  • Consequence: Slight runtime overhead during skeleton setup, but dramatically easier developer experience

• Does not provide real-time data synchronization or reactive state management
• Does not handle network requests or API integration
• Does not support Android or cross-platform frameworks (iOS/tvOS/macOS only)
• Does not include comprehensive accessibility (a11y) features beyond standard UIView accessibility

SwiftPM workspace requires Xcode to open (.swiftpm/xcode/package.xcworkspace); command-line Swift build may have different behavior. Multiline text skeletons require specific UILabel/UITextView configuration per Assets/multiline_*.png examples. Animation frame rate and gradient direction can interact unexpectedly on older iOS versions; check .swift-version for minimum target. CocoaPods users must ensure Podfile platform matches minimum supported iOS version.

• CABasicAnimation & CAGradientLayer — Core mechanism for shimmer and sliding animations in SkeletonView; understanding layer-based animation is essential to customize or debug animation behavior.
• UIView hierarchy traversal via Mirror/Runtime reflection — SkeletonView recursively applies skeleton state to entire view trees; knowing how Swift reflection works is key to understanding why certain views may not get skeleton applied.
• Skeletonization (placeholder UI pattern) — Industry pattern (LinkedIn, Facebook, Slack) for perceived performance; SkeletonView is the iOS implementation — understanding the UX intent helps design better loading states.
• Swift Package Manager (SPM) vs CocoaPods dual distribution — SkeletonView supports both; understanding .swiftpm/ workspace layout and podspec differences is crucial for contributing or updating packaging.
• CADisplayLink for frame-rate synchronized animations — Best practice for smooth, synchronized shimmer across multiple views; SkeletonView likely uses this internally to avoid jank.
• GitHub Actions CI/CD workflows for iOS package release automation — SkeletonView uses release-drafter, pod_trunk, and version-bumping workflows; understanding this automation is essential for maintainers and contributors preparing releases.

• facebook/shimmer — Android/Java equivalent shimmer loading library; SkeletonView is the iOS spiritual successor with more UIView integration.
• airbnb/lottie-ios — Alternative for complex loading animations via JSON; SkeletonView is lighter-weight for standard skeleton patterns.
• RayWenderlich/swift-style-guide — Reference for Swift code conventions; SkeletonView enforces similar rules via .swiftlint.yml.
• pointfreeco/swift-composable-architecture — Architectural pattern for iOS state management that pairs well with SkeletonView's loading state lifecycle.
• realm/realm-swift — Common data source for async content loading that triggers SkeletonView display in real apps.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for SkeletonView core animation logic

The repo has extensive CI/CD workflows (main.yml, validations.yml, pod_lib_lint.yml) but the file structure shows no dedicated Tests directory listed. Given the complexity of skeleton animations (sliding in 6 directions, gradient animations, transitions with/without fade), there's likely insufficient unit test coverage for the animation engine. This would improve code quality and prevent regressions when contributors modify animation behavior.

• [ ] Create Tests/ directory structure mirroring Sources/ (if not present)
• [ ] Add unit tests for SkeletonAnimationBuilder covering all 6 sliding directions (top-to-bottom, bottom-to-top, left-to-right, right-to-left, topLeft-to-bottomRight, bottomRight-to-topLeft)
• [ ] Add tests for gradient animation configurations and solid color animations
• [ ] Add tests for transition fade behavior (SkeletonTransitionStyle)
• [ ] Integrate new tests into existing main.yml CI workflow to run on every PR

Add UICollectionView/UITableView skeletonization integration tests

The file structure shows Examples/CollectionView but no corresponding integration tests for DataSourceSkeletonizable protocol behavior. The README demonstrates both TableView and CollectionView skeleton examples, but there appear to be no dedicated test suites validating that row/cell counts are correctly applied during skeleton loading. This is critical functionality that should have test coverage.

• [ ] Create integration tests in Tests/DataSource/ for UITableViewDataSource skeleton behavior
• [ ] Add tests verifying SkeletonTableViewDataSource correctly returns skeleton row counts and cell configurations
• [ ] Add tests for UICollectionViewDataSource skeleton behavior with different layout configurations
• [ ] Add edge case tests for empty collections, single items, and large datasets
• [ ] Document test patterns in CONTRIBUTING.md for future contributors

Add platform-specific CI workflow for visionOS and tvOS support validation

The README badge shows SPM support across multiple platforms, and .swift-version exists indicating version management, but there's no dedicated workflow (like pod_lib_lint.yml and pod_trunk.yml for iOS) validating build compatibility for tvOS and visionOS. Given SkeletonView's visual nature, these platforms have unique rendering considerations.

• [ ] Create .github/workflows/tvos_validation.yml to build and lint SkeletonView against tvOS SDK
• [ ] Create .github/workflows/visionos_validation.yml to validate visionOS RealityKit rendering compatibility if applicable
• [ ] Update podspec (if exists) to include tvOS/visionOS deployment targets with appropriate minimum versions
• [ ] Add platform-specific integration tests in Tests/Platform/ for UIView subclass behavior on tvOS/visionOS
• [ ] Document platform-specific API differences in README if any exist

• Add unit tests for edge cases in view hierarchy traversal (does skeleton handle nested safe areas, hidden views, or zero-height containers correctly?) — likely needs test files added to match source structure.
• Document animation performance tuning for large collection views — README has features section but no performance guide; check if there are open performance issues or add CADisplayLink batching docs.
• Create Swift Playground example in .swiftpm/ showing basic skeleton setup (show/hide, color customization, animation types) — infrastructure exists (FUNDING badge mentions nef-playgrounds) but no visible playgrounds in file list.

SkeletonView is a UI library focused on skeleton screen loading animations with no apparent network or data processing risks. The project demonstrates good security practices with CI/CD pipelines and automated workflows. However, the static analysis is limited due to incomplete file content review. Primary concerns are the absence of analyzed dependency manifests and GitHub Actions workflow verification. No hardcoded secrets, injection risks, or exposed infrastructure configurations were detected in the provided file structure. The project appears well-maintained with established security review processes (Codebeat integration, SwiftLint, Danger), but full vulnerability assessment requires examination of Package.swift/Podfile and workflow definitions.

• Low · Missing Swift Version Lock File — .swift-version. The .swift-version file exists but its content is not provided for review. This file should explicitly specify the Swift version to ensure reproducible builds across environments. Fix: Ensure the .swift-version file contains a pinned Swift version (e.g., '5.5') and verify it matches the minimum deployment requirements.
• Low · SwiftLint Configuration Not Reviewed — .swiftlint.yml. The .swiftlint.yml file is present but its content was not provided. SwiftLint misconfigurations could allow code quality issues to pass undetected. Fix: Review the SwiftLint configuration to ensure security-relevant rules are enabled, such as rules for unused variables and proper error handling.
• Low · Incomplete Dependency Analysis — Package.swift / Podfile / Package.resolved. The Package.swift or Podfile dependency file content was not provided for analysis. This prevents comprehensive assessment of third-party dependency vulnerabilities. Fix: Provide dependency manifest files and regularly audit all transitive dependencies using tools like: 1) CocoaPods spec lint, 2) SPM dependency resolver, 3) OWASP Dependency-Check.
• Low · GitHub Actions Workflows Not Fully Reviewed — .github/workflows/. Multiple GitHub Actions workflow files exist (.github/workflows/*.yml) but their contents were not provided. Workflows can contain security misconfigurations, exposed secrets, or unsafe privilege escalation. Fix: Review all workflow files for: 1) Hardcoded credentials, 2) Excessive permissions, 3) Pinned action versions, 4) Secure secret handling.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.