android / android/skills

[Feature] Add background-work skill for execution-model routing (UIDT vs FGS vs WorkManager vs alarms)

Open
#167 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
7.3k
Forks
476
Avg merge
8h 59m
Merged PRs (30d)
7

Description

[background-work.zip](https://github.com/user-attachments/files/31597277/background-work.zip)

> [!NOTE]
> Feature requests are accepted only if the proposed skill fills a verified gap in state-of-the-art LLMs. Evaluations below used a **fast** model (Cursor Composer 2.5 Fast) and a **thinking** model (Cursor Grok 4.6). Gemini 3 Flash / Gemini 3.1 Pro were not available in this environment; please re-run the same prompts on those models if needed.

### What is the gap in the LLM's knowledge?

`android/skills` has no background-work category. Current models **already know** WorkManager, foreground services, and AlarmManager exist. The remaining, repeatable gap is **which execution model to pick**, not “does `enqueueUniquePeriodicWork` exist.”

Two traps showed up without the skill (no web, no docs, isolated sessions):

| Constraint | Fast (Composer 2.5) without skill | Thinking (Grok 4.6) without skill |
| --- | --- | --- |
| User taps “upload 2GB video”; must continue after leaving the Activity | **FGS first** (missed UIDT) | UIDT on that prompt, but **FGS** for the same 2GB upload when asked in a separate session as a contrast |
| Daily work **around** 03:00, deferrable | **AlarmManager** | WorkManager |
| User-facing exact 08:00 reminder | AlarmManager | AlarmManager |
| System-initiated deferrable log upload | WorkManager | WorkManager |

So the models do not stably split:

- user-initiated long **transfer** vs system-initiated **deferrable** work
- exact **user-facing** clock vs “around 03:00 is fine”

They **do** already split navigation FGS vs a 30-minute report, Bound IPC vs daily sync, and “I have `FOREGROUND_SERVICE` therefore I can start from the background.” Those are not the gap.

With the skill attached (same prompts, still no web):

```text
Baseline Skill-on
user initiated long transfer Fast: FGS UIDT (API 34+)
Grok: UIDT / FGS (inconsistent) UIDT (both sessions)
system initiated deferrable WorkManager WorkManager
exact user-facing time AlarmManager AlarmManager
non-exact daily Fast: AlarmManager (fail) WorkManager
Grok: WorkManager WorkManager
```

Fast rubric (24 items × 0–5 = 120): **86 → 97**. The score move is concentrated on those traps (user 2GB upload, inexact 03:00, plus refusing an impossible guarantee instead of emitting an alarm skeleton). Grok baseline was already **96 / 120**; the skill’s increment there is **counterfactual consistency** (same 2GB user upload is UIDT in an isolated contrast session), not teaching UIDT from scratch.

Official docs this matches:

- [User-initiated data transfer jobs](https://developer.android.com/develop/background-work/background-tasks/uidt) — evaluate UIDT before FGS for user-started long transfers (API 34+)
- [AlarmManager](https://developer.android.com/develop/background-work/services/alarms) — exact alarms are not a general job API
- [WorkManager](https://developer.android.com/develop/background-work/background-tasks) — deferrable, persistent work

### Proposed Skill

Path: `background-work/` (same layout as `profilers/android-profiler`: `SKILL.md` routes, `workflows/` procedures, `references/` facts).

Scope: **execution-model selection** for work that may outlive the current UI — WorkManager, UIDT, AlarmManager as trigger, Bound vs Started, FGS only when the type and visibility fit. **Not** a WorkManager tutorial, not “how to write a Service.”

Full tree (skill product only; local eval harness is not included): [background-work gist](https://gist.github.com/endlessYoung/7276ef2c905418690ce0beeb11f6a3a8) (`SKILL.md`, `workflows/`, `references/`).

`SKILL.md` routing:

~~~~markdown
| User intent | Workflow |
| --- | --- |
| Which mechanism / execution model / decision tree | workflows/select-execution-model.md |
| Implement WorkManager after it is selected | workflows/workmanager.md |
| Implement or validate a foreground service | workflows/foreground-service.md |
| Exact or inexact alarms as a **trigger** | workflows/alarm.md |
| User-initiated long data transfer | workflows/user-initiated-data-transfer.md |
| Started vs Bound vs both; background `Service` warning path | workflows/service.md |
~~~~

Default: if they have a real requirement and no mechanism yet, run **select-execution-model** to the end, then run the workflow it names.

### Additional Context

- Repo currently has `camera`, `identity`, `system`, `profilers`, and other categories, but **no `background-work/`** tree.
- README says public PRs are not accepted, so this is an issue-only proposal rather than a PR.
- The skill is intentionally a **router**, not a dump of every background API. The eval question is “does attaching it stop the two stable mis-routes,” not “can the model recite JobScheduler.”
- Eval used Cursor Composer 2.5 Fast (full 24 / 24 both arms) and Cursor Grok 4.6 (full 24 baseline; skill-on rerun on the headline pairs only). Happy to re-run the same prompts on Gemini 3 Flash / 3.1 Pro if maintainers want that matrix.

[background-work.zip](https://github.com/user-attachments/files/31597260/background-work.zip)

Contributor guide

Open the contributing guide

Research direction

Start by comparing the attached background-work.zip with the existing profilers/android-profiler layout and inspect the proposed SKILL.md routing table. Verify that the workflows cover WorkManager, UIDT, AlarmManager, foreground services, and service binding, with references for the stated execution-model choices. Done means the new background-work/ tree consistently routes the listed intents and preserves the documented scope.

Written by the indexing model from the issue text.

Assessment

Tech stack
android
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.