What the Capgo release added
Retrospective added on 30 October 2026, covering the release of 11 October.
The Capgo Skills v1.2.1 release named focused workflows for Capacitor app and plugin upgrades, UIScene migration, iOS security hardening, app intents and resizability. The release described a collection of 55 skills. That total should not be read as 55 newly created workflows in October.
The useful distinction is between several kinds of mobile work. Upgrading an application dependency, changing a plugin and reviewing lifecycle behaviour are related, but they have different failure modes. A focused skill can make the relevant procedure easier to select.
This guide proposes a way to organise that work. It does not claim that a skill can migrate every application automatically, and it does not replace version-specific platform documentation or a review of the package being installed.
Identify the migration boundary first
Before changing files, write down the starting versions and the intended destination. Include the application framework, relevant native projects and the plugins that participate in the affected behaviour. A migration without a clear starting point is difficult to reproduce or review.
Separate requirements from preferences. A platform compatibility requirement may need a specific change. A desire to modernise unrelated code can wait. Combining both in the same migration makes failures harder to diagnose and increases the size of the review.
Define the unit of work. Is the task to upgrade the application, update a plugin maintained by the team, or adapt lifecycle handling? If more than one is necessary, make their dependencies explicit. Do not ask the agent to treat every mobile-related concern as one undifferentiated cleanup.
The skill authoring guide explains why clear scope helps a reusable workflow. The same principle applies when selecting a third-party skill: choose the procedure that matches the requested outcome, then verify its assumptions against the actual project.
Review application and plugin changes separately
An application migration should account for how the app uses its native integrations. Identify the features that depend on plugins and the conditions under which those features run. A dependency update can look simple in a manifest while affecting behaviour at a native boundary.
A plugin migration has another responsibility: preserving or intentionally changing the interface consumed by applications. Review inputs, outputs, errors and lifecycle assumptions. A plugin can compile while behaving differently for callers, so its acceptance checks should exercise the contract rather than only the build.
If the team owns both sides, resist changing them together without a recorded plan. A coordinated change may be appropriate, but it should explain which interface changed and why. Otherwise an application workaround can conceal a plugin regression that later affects another consumer.
For third-party plugins, verify the maintainer's compatibility guidance for the selected versions. Do not infer support from a recent commit or a high download count. Where compatibility is uncertain, record the uncertainty and test the affected behaviour before calling the migration complete.
Treat lifecycle behaviour as a user journey
Lifecycle changes deserve attention because they affect how the app behaves across launch, backgrounding, return and navigation. A successful initial launch is only one state. An application can appear healthy until the user returns from another app or opens a link.
Build a short journey around the features the app actually provides. For example, start the app, navigate to a meaningful screen, background it, return and open a supported link. Check whether the resulting state matches the product's expected behaviour.
This suggested review brief is intentionally generic:
Describe the app's expected launch and return behaviour.
Identify custom lifecycle and link-handling code before editing.
List the native integrations affected by the migration.
Run the relevant user journeys on the intended test environment.
Record unexpected state changes and unresolved compatibility questions.
Keep unrelated feature redesign outside the migration.
It is not a Capacitor configuration file or a replacement for official upgrade steps. Its purpose is to make the behavioural acceptance criteria explicit before the agent changes templates or dependencies.
Use official guidance to resolve version-specific claims
A skill can organise a procedure, but it can also contain assumptions tied to a particular release. Check important claims against the relevant platform documentation. That is especially important for minimum toolchain versions, required project changes and compatibility statements.
For the lifecycle topic, Capacitor's 8.5 upgrade guide provides useful primary context. Read its distinctions carefully rather than turning a documented migration into a blanket statement that every existing application will fail.
Keep the evidence attached to the claim. If the migration requires a particular change, link to the documentation that supports it in the review notes. If the change is a local project decision, describe it as such rather than attributing it to the vendor.
Avoid copying commands from a different version's tutorial without checking them. The safe command is the one documented for the selected environment, not the one that happens to be memorable. Where the required information is missing, pause that step and resolve it rather than inventing an upgrade instruction.
Establish a baseline before the first edit
A baseline tells you what already worked and what already failed. Build the existing application in the intended environment where practical, then run a small set of relevant journeys. Record known failures so they are not incorrectly blamed on the migration.
Keep the baseline narrow enough to be repeatable. It should cover the behaviours affected by the planned change, not every feature the application has ever shipped. A well-chosen baseline can be run again after each meaningful stage of the migration.
For a team, agree who will review native behaviour and who will review the web layer. The same person can do both, but the responsibilities should remain visible. A browser-only review may miss a native integration issue, while a successful native build may miss a broken application flow.
Do not claim device coverage that was not exercised. If the check used a simulator, record that. If a particular device or operating-system version remains untested, preserve the limitation. Accurate coverage notes are more useful than a broad green status.
Make changes in reviewable stages
Group changes by their purpose. Dependency updates, native project adjustments and application behaviour changes are easier to review when their relationship is clear. This does not require a separate commit for every line, but it does require an understandable sequence.
After each stage, run the check that can detect the relevant failure. A dependency resolution problem should be found before the team spends time reviewing visual behaviour. A lifecycle regression should be checked after the corresponding native changes, not deferred until a final demonstration.
Keep generated changes visible in the review. An agent may update files through tooling rather than manual edits, but those changes still affect the project. Inspect whether the generated output matches the intended versions and scope.
If the migration exposes an unrelated defect, record it separately unless fixing it is necessary to complete the authorised work. Expanding the task silently makes the acceptance criteria unstable and can turn a focused upgrade into an open-ended rewrite.
Review the skill package before execution
The release announcement is a starting point for discovery, not a substitute for inspecting the actual instructions and scripts. Read the selected skill's body and the resources it references. Confirm that the package contains what the workflow expects.
Review the applicable licence for the exact version before copying or redistributing it. A licence label on a later branch should not be treated as proof of the contents of an earlier archive. When provenance is unclear, separate discussion of the release from a recommendation to redistribute the package.
The skill security guide covers the broader review of scripts and external access. For a mobile project, pay particular attention to operations that touch signing material, account configuration or distribution services. Those are distinct from editing ordinary application code.
Use synthetic examples or non-production environments for initial exploration where possible. A skill that requests real credentials or exports should have a clear reason for needing them. Keep private inputs outside version control and avoid copying them into an issue merely to make a troubleshooting example convenient.
Troubleshoot the failing layer
If the project does not build, inspect the dependency and native configuration changes first. Compare the error with the selected version's requirements. Do not keep changing application logic when the failure occurs before that logic can run.
If the build succeeds but a native capability fails, isolate the plugin boundary. Check whether the application calls the expected interface and whether the native side returns the expected result. Record a minimal reproduction that excludes unrelated screens and services.
If navigation or return behaviour changes, review lifecycle and link-handling assumptions. Reproduce the exact sequence rather than describing the problem as “the app sometimes resets”. The sequence is often the most important part of the evidence.
If the agent repeatedly proposes incompatible changes, inspect the loaded skill version and its references. A stale instruction can be internally coherent while targeting the wrong release. Correct the source of the assumption instead of applying a growing list of exceptions in chat.
Example: a plugin works after launch but fails on return
Consider an app that passes a basic launch test and successfully invokes a native feature. After the user backgrounds the app and returns, the same feature stops responding. A build-only check would miss the problem, and repeating the initial launch would produce another misleading success.
Use the failing journey to narrow the investigation. Identify the relevant lifecycle transition and the plugin state before and after it. Compare that behaviour with the application's intended contract and the selected platform documentation. Keep the reproduction focused enough that a maintainer can repeat it without navigating unrelated features.
After a repair, repeat the return path rather than merely rebuilding. Record whether the check ran in a simulator or on the intended device class. That evidence gives the migration reviewer a specific reason to accept the change and a clear boundary around what remains untested.
Define completion beyond a successful build
A migration is complete when the required version change is in place and the affected behaviour has been verified to the agreed level. The build is one piece of that evidence. It should not erase unresolved user journeys or untested plugin interactions.
A concise handover should state the starting and target versions, significant changes, checks performed and remaining limitations. Include any follow-up that needs a real device, an account owner or a distribution environment unavailable during the migration.
Keep publication and distribution separate from local acceptance. Preparing a working app does not imply that it has been submitted to a store or released to users. If distribution is part of the task, verify that outcome explicitly rather than letting the word “done” cover several unperformed stages.
For further structure, see how to test an agent skill and browse the skill directory. Capgo's October release is worth noticing because it separates mobile work into recognisable procedures. The value comes from applying the right procedure to a clearly defined migration and checking the behaviour that users depend on.
