SKILL.md
What this tool is for
settings-permissions edits the platform's permission store directly - the iOS simulator's TCC database, or Android's package-manager permission flags. It replaces the manual Settings → Privacy dance during test setup: pre-authorize a service so the app never has to ask, deny it up front to test the refusal path, or reset it so the first-run dialog appears again on the next launch.
It is a test-setup / out-of-band tool, not a general permissions toggle. The default way to change a permission is still through the app - this tool is the exception for the cases the app can't reach.
When to use it - and when NOT to
Decide with this order. The first matching row wins.
| Situation | Do this | Why |
|---|---|---|
| The app has an in-app control for the permission (a toggle in its own settings screen) | Tap it in the app (describe → gesture-tap) - do NOT use this tool |
It's real user behavior and exercises the flow you're testing. See argent-device-interact. |
| The app is about to ask (or just asked) and the system permission dialog is on screen | Tap the dialog (Allow / Don't Allow / Allow While Using App) - do NOT use this tool |
The app-triggered prompt is the natural path; answering it is what a user does. describe exposes the dialog buttons; fall back to screenshot only if it doesn't. |
| You need the permission already granted/denied before the app runs, so no dialog interrupts the flow | Use this tool (grant / deny) before launch-app |
The app can't pre-set its own permission; a real user would do it in Settings. This is the core use case. (deny suppresses the prompt on iOS only - see Gotchas.) |
| The user already denied it and you need it on again | Use this tool (grant) |
iOS never re-shows a dialog once denied - the only in-device path is the Settings app. This tool is the shortcut. |
| You need the first-run dialog to appear again (test the prompt itself, or reset dirty state) | Use this tool (reset) |
Returns the permission to "not yet asked" so the app prompts on next use. |
| The permission is not one this tool supports on the target platform (see the support table) | Do NOT use this tool | It will return an "unsupported" error. Use the app dialog if the app triggers one, or navigate the real Settings app. |
| The setting isn't one of the 11 runtime permissions below (e.g. Wi-Fi, cellular data, dark mode, VPN, Focus) | Do NOT use this tool | Out of scope - drive the Settings app or the app's own UI instead. |