CAAnimation issues manifest as missing completion handlers, wrong timing, or jank under specific conditions. Core principle 90% of CAAnimation problems are CATransaction timing, layer state, or frame rate assumptions, not Core Animation bugs.
Fetches axiom-uikit-animation-debugging from charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-uikit-animation-debugging
Restart Cursor to activate axiom-uikit-animation-debugging. Access via /axiom-uikit-animation-debugging in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
CAAnimation issues manifest as missing completion handlers, wrong timing, or jank under specific conditions. Core principle 90% of CAAnimation problems are CATransaction timing, layer state, or frame rate assumptions, not Core Animation bugs.
Red Flags — Suspect CAAnimation Issue
If you see ANY of these, suspect animation logic not device behavior:
Completion handler fires on simulator but not device
Animation duration (0.5s) doesn't match visual duration (1.2s)
Spring animation looks correct on iPhone 15 Pro but janky on older devices
Gesture + animation together causes stuttering (fine separately)
[weak self] in completion handler and you're not sure why
❌ FORBIDDEN Hardcoding duration/values to "match what actually happens"
This ships device-specific bugs to users on different hardware
Do not rationalize this as a "temporary fix" or "good enough"
Critical distinction Simulator often hides timing issues (60Hz only, no throttling). Real devices expose them (variable frame rate, CPU throttling, background pressure). MANDATORY: Test on real device (oldest supported model) before shipping.
Mandatory First Steps
ALWAYS run these FIRST (before changing code):
// 1. Check if completion is firing at allanimation.completion ={[weakself] finished inprint("🔥 COMPLETION FIRED: finished=\(finished)")guardletself=selfelse{print("🔥 SELF WAS NIL")return}// original code}// 2. Check actual duration vs declaredlet startTime =Date()let anim =CABasicAnimation(keyPath:"position.x")anim.duration =0.5// Declaredlayer.add(anim, forKey:"test")DispatchQueue.main.asyncAfter(deadline:.now()+0.51){print("Elapsed: \(Date().timeIntervalSince(startTime))")// Actual}// 3. Check what animations are activeiflet keys = layer.animationKeys(){print("Active animations: \(keys)")for key in keys {iflet anim = layer.animation(forKey: key){print("\(key): duration=\(anim.duration), removed=\(anim.isRemovedOnCompletion)")}}}// 4. Check layer stateprint("Layer speed: \(layer.speed)")// != 1.0 means timing is scaledprint("Layer timeOffset: \(layer.timeOffset)")// != 0 means animation is offset
What this tells you
Completion print appears → Handler fires, issue is in callback code
Completion print missing → Handler not firing, check CATransaction/layer state
Elapsed time == declared → Duration is correct, visual jank is from frames
Elapsed time != declared → CATransaction wrapping is changing duration
layer.speed != 1.0 → Something is slowing animation
Active animations list is long → Multiple animations competing
MANDATORY INTERPRETATION
Before changing ANY code, you must identify which ONE diagnostic is the root cause:
If completion fires but elapsed time != declared duration → Apply Pattern 2 (CATransaction)
If completion doesn't fire AND isRemovedOnCompletion is true → Apply Pattern 3
If completion fires but visual is janky → MUST profile with Instruments first
You cannot guess "it's probably frames" - prove it with data
Profile > Core Animation instrument shows frame drops with certainty
If you skip Instruments, you're guessing
If diagnostics are contradictory or unclear
STOP. Do NOT proceed to patterns yet
Add more print statements to narrow the cause
Ask: "The diagnostics show X and Y but Z doesn't match. What am I missing?"
Profile with Instruments > Core Animation if unsure
Decision Tree
CAAnimation problem?
├─ Completion handler never fires?
│ ├─ On simulator only?
│ │ └─ Simulator timing is different (60Hz). Test on real device.
│ ├─ On real device only?
│ │ ├─ Check: isRemovedOnCompletion and fillMode
│ │ ├─ Check: CATransaction wrapping
│ │ └─ Check: app goes to background during animation
│ └─ On both simulator and device?
│ ├─ Check: completion handler is set BEFORE adding animation
│ └─ Check: [weak self] is actually captured (not nil before completion)
│
├─ Duration mismatch (declared != visual)?
│ ├─ Is layer.speed != 1.0?
│ │ └─ Something scaled animation duration. Find and fix.
│ ├─ Is animation wrapped in CATransaction?
│ │ └─ CATransaction.setAnimationDuration() overrides animation.duration
│ └─ Is visual duration LONGER than declared?
│ └─ Simulator (60Hz) vs device frame rate (120Hz). Recalculate for real hardware.
│
├─ Spring physics wrong on device?
│ ├─ Are values hardcoded for one device?
│ │ └─ Use device performance class, not model
│ ├─ Are damping/stiffness values swapped with mass/stiffness?
│ │ └─ Check CASpringAnimation parameter meanings
│ └─ Does it work on simulator but not device?
│ └─ Simulator uses 60Hz. Device may use 120Hz. Recalculate.
│
└─ Gesture + animation jank?
├─ Are animations competing (same keyPath)?
│ └─ Remove old animation before adding new
├─ Is gesture updating layer while animation runs?
│ └─ Use CADisplayLink for synchronized updates
└─ Is gesture blocking the main thread?
└─ Profile with Instruments > Core Animation
Common Patterns
Pattern Selection Rules (MANDATORY)
Apply ONE pattern at a time, in this order
Always start with Pattern 1 (Completion Handler Basics)
If completion NEVER fires → Pattern 1
Verify completion is set BEFORE add() with print statement (line 33)
Only proceed to Pattern 2 if completion FIRES but timing is wrong
Then Pattern 2 (CATransaction duration mismatch)
Only if completion fires but elapsed time != declared duration
Check logs from Mandatory First Steps (line 40-47)
Then Pattern 3 (isRemovedOnCompletion)
Only if animation completes but visual state reverts
Patterns 4-7 Apply based on specific symptom (see Decision Tree line 91+)
FORBIDDEN
❌ Applying multiple patterns at once ("let me try Pattern 2 AND Pattern 4 together")
❌ Skipping Pattern 1 because "I already know it's not that"
❌ Combining patterns without understanding why each is needed
❌ Trying patterns randomly and hoping one works
Pattern 1: Completion Handler Basics
❌ WRONG (Handler set AFTER adding animation)
layer.add(animation, forKey:"myAnimation")animation.completion ={ finished in// ❌ Too late!print("Done")}
CATransaction.begin()CATransaction.setAnimationDuration(2.0)// ❌ Overrides all animations!let anim =CABasicAnimation(keyPath:"position")anim.duration =0.5// This is ignoredlayer.add(anim, forKey:nil)CATransaction.commit()// Animation takes 2.0 seconds, not 0.5
✅ CORRECT (Set duration on animation, not transaction)
let anim =CABasicAnimation(keyPath:"position")anim.duration =0.5layer.add(anim, forKey:nil)// No CATransaction wrapping
Why CATransaction.setAnimationDuration() affects ALL animations in the transaction block. Use it only if you want to change all animations uniformly.
Pattern 3: isRemovedOnCompletion & fillMode
❌ WRONG (Animation disappears after completion)
let anim =CABasicAnimation(keyPath:"opacity")anim.fromValue =1.0anim.toValue =0.0anim.duration =0.5layer.add(anim, forKey:nil)
Implementation Guide
Prerequisites
›Claude Desktop or compatible AI client with skill support
›Clear understanding of task or problem to solve
›Willingness to iterate and refine outputs
Time Estimate
15-45 minutes depending on use case complexity
Steps
1Install skill using provided installation command
2Test with simple use case relevant to your work
3Evaluate output quality and relevance
4Iterate on prompts to improve results
5Integrate into regular workflow if valuable
Common Pitfalls
⚠Expecting perfect results without iteration
⚠Not providing enough context in prompts
⚠Using skill for tasks outside its intended scope
⚠Accepting outputs without review and validation
Best Practices
✓ Do
+Start with clear, specific prompts
+Provide relevant context and constraints
+Review and refine all outputs before using
+Iterate to improve output quality
+Document successful prompt patterns
✗ Don't
−Don't use without understanding skill limitations
−Don't skip validation of outputs
−Don't share sensitive information in prompts
−Don't expect skill to replace human judgment
💡 Pro Tips
★Be specific about desired format and style
★Ask for multiple options to choose from
★Request explanations to understand reasoning
★Combine AI efficiency with human expertise
When to Use This
✓ Use when
Use when skill capabilities match your task, clear ROI on time saved, and you can validate outputs. Best for repetitive tasks, learning, and quality improvement.
✗ Avoid when
Avoid when task requires deep expertise you can't validate, involves sensitive decisions, or when learning process is more valuable than speed of completion.
Learning Path
1Familiarize yourself with skill capabilities and limitations
2Start with low-risk, non-critical tasks
3Progress to more complex and valuable use cases
4Build expertise through regular use and experimentation
