📘 Skill Creation Guide
How to author a Ghost Skill Hub skill, from scratch or from a recorded trace. Written for both people and LLM agents: read it once, then follow the flow in section 8. Field-level reference: docs/skill-schema-v2.md. Scoring source of truth: skillhub/scoring/v1.json.
1. What you are building
Section titled “1. What you are building”A skill is a folder skillhub/<github-login>/<slug>/ that automates one app. It holds named actions (what an agent calls, e.g. calculate), each a list of deterministic steps ending in an end_state_validator that proves the action worked. Replay costs zero LLM tokens. Agents call it by name: MCP run_skill(name="<author>/<slug>", action, params) or ghost skill run <ref> <action>.
- Hard skill: no LLM and no human at replay.
- Soft skill:
SOFT.mdreference notes the agent reads withget_skill_noteswhen replay does not fit. - Gate: a checkpoint or ask suspends a run; a human captcha is a gate, not a soft skill. The schema’s legacy
skill_class: softvalue marks gated execution. Seedocs/skill-taxonomy-soft-vs-hard.md.
Toolkit shape
Section titled “Toolkit shape”Author an app toolkit with one entry action, 3–6 focused primitives, and one read-state action that returns visible structured data. Add actions beyond that range only when the app needs distinct operations; this is an authoring rule, not a schema-enforced action limit. Entry opens or resets the demo app; primitives perform one operation; read-state observes without opening unrelated apps or changing user data. Reuse the toolkit across prompts instead of embedding one benchmark task in a single long action.
Include a Toolkit table in README with each action’s role, parameters, returned data and side effects. Document honest limits and the tested app/device scope. Record every action three times after the final definition-file edit; editing README, SOFT.md, helpers.py or skill.yaml changes the content digest. Prior runs remain historical evidence and do not verify the new files.
For Android Python helpers, share the engine APIs instead of copying parsers or launching a separate ADB process:
from gitd.skills.engine.nodes import parse, by, centre
nodes = parse(device.dump_xml())rows = by(nodes, "id", "com.example:id/row")# centre(rows[0]) returns coordinates; it does not tap.png = device.screencap_png() # PNG bytes, transport errors and package policy checkedThe node helpers preserve document order and raw XML attribute entities, reject invalid/off-screen bounds, and use exact selectors. Decode display text explicitly when needed. The screenshot API is Android-specific. Adopting either API in an existing recorded skill requires fresh content-bound runs after its final edits.
Folder contents:
skill.yaml required, the skillREADME.md required for Runs tierSOFT.md one section per action; the narrative adapt mode reads when the UI driftshelpers.py optional python_action targets, flat filevalidators.py optional custom_python validatorsicon.webp optional, 96 px, <= 16 KB (tools/fetch_app_icons.py fetches Play/F-Droid icons)demos/<action>.webm|mp4|gif + demos/<action>.spec.yaml optional, one clip per actionruns/ your signed self-runs (ghost skill run --record)verifications/ other people's signed runs, added by their PRsSKILL.md GENERATED by the registry builder, do not edit2. skill.yaml top level
Section titled “2. skill.yaml top level”name: calculator # = folder slugversion: 1.0.1 # SemVer; bump on every change to an existing skillauthor: ghost # = GitHub login = folder namedescription: "One line: what it automates"skill_class: hard # hard | softlicense: MIT # SPDX id, requiredgenerated_with: "Claude Opus 5.5 via Claude Code, hand-explored on an emulator" # required; say how it was madestatus: active # active | blocked | deprecated | draftside_effects: [none] # sends_message, posts_content, makes_payment, modifies_account, deletes_data, nonedestructive: false # true requires a confirm gate (checkpoint/ask) or a dry-run paramtos_risk: low # low | medium | highlocale: [en-US] # BCP-47 list you tested indata_access: [] # contacts, sms, camera, mic, location, notifications, clipboard, files, storageicon: icon.webp # optional; defaults to icon.webp when presentdemo: demos/convert_units.webm # optional default clip; else first action clipfingerprint: os: android # android | ios os_version: ">=14" hardware: "*" # do not wildcard what you did not test unless it is truly generic app_package: org.fossify.math app_version: ">=1.4.0" screen_wxh: 1080x2400 # optional density: 420 # optional locale: en-US # optional theme: "*" # optional: light | dark | *os_popup_policy: {allow_permissions: [], deny_permissions: [], ignore: []} # Layer 1 overridespopup_detectors: [] # Layer 2subroutines: []actions: []Reserved, set by the registry, never by you: trust, quality, schema.
3. An action
Section titled “3. An action”- name: convert_units # snake_case, agent-facing description: "Convert a value between two units" ref_prompt: "Convert 100 Fahrenheit to Celsius" demo_params: {category: Temperature, value: "100", from_unit: Fahrenheit, to_unit: Celsius} params: - {name: category, type: enum, values: [Length, Temperature], required: true} - {name: value, type: str, required: true, description: "number"} pre_hooks: [] # optional steps before steps: on_popup: {} # Layer 3 (section 5) steps: [...] end_state_validator: {all_of: [...]} # required; 3+ leaf checks earn points test_case: ref_prompt_variants: ["how many kilometers is 26.2 miles", "convert 70 kg to pounds"] expected_success: trueParam types: str, int, float, bool, path, enum (with values), list[str]. Interpolate with {param} and {context.<key>} in any step string or validator. demo_params are the defaults ghost skill demo uses when no --param is given: pick values that show the action well and touch nothing private.
CLI --param values are converted by the parameter declaration in both ghost skill run and ghost skill test: --param value=005 stays "005" for type: str and becomes 5 for type: int. Boolean-looking text and JSON-looking text also stay literal strings when declared str; bool and list[str] declarations parse them accordingly. Typed API values and YAML defaults declared str are normalized to strings.
4. Steps
Section titled “4. Steps”Write steps as {action: <name>, ...}. The structural steps (if_visible, retry, subroutine, checkpoint, ask, python_action) use their name as the key.
26 step kinds: the 20 primitives below (18 device, wait and read steps plus python_action and checkpoint) and the 6 control-flow steps in the next table.
| Step | Use when |
|---|---|
tap_element {id|desc|text|xpath} | Default way to tap. Locator chain id, desc, text, xpath |
tap {x, y} | Only for landmarks with no stable attribute; add a comment why |
type_text {text, clear_first?} | Type into the focused field |
long_press {x, y | id|desc|text, duration_ms} | Context menus, drag starts; a locator long-presses the node’s centre |
swipe {x1, y1, x2, y2, duration_ms?} | Scrolling, pagers |
press_key {key} | BACK, HOME, ENTER and other keyevents |
launch_app {package, activity?} | Start the app (usually first step of a subroutine) |
launch_intent {intent_action, package?, mime_type?, extras?} | Share intents and deep links; skips whole UI flows |
open_url {url, browser?} | Web flows |
screenshot {save_as?} | Evidence for debugging, stored with the run |
dump_xml {save_as?} | Snapshot the a11y tree for a helper |
dismiss_popups | Extra Layer 2 sweep at a known popup moment |
wait_for_text {text, timeout_s?} | Wait until text shows (prefer over sleep) |
wait_for_element {id|desc|xpath, timeout_s?} | Wait until an element exists |
sleep {duration_s} | Last resort; animations with nothing to wait for |
read_text {id|desc|text, store_as, attr?, index?, all?, parse?} | Read a node into {context.<store_as>} and the result; all: true collects every match, parse: number converts |
tap_nth {id|desc|text, index} | Tap the nth match of a locator (negative counts from the end) |
compare {left, right, mode?, tolerance?} | Fail unless the values agree (equals, contains, number, regex); the YAML way to check a read value |
python_action: "helpers:fn" | Anything YAML cannot express; (device, params, context) returning dict or ActionResult |
checkpoint: {...} | A gate the bot must not clear itself (section 6) |
Control flow and composition:
| Step | Use when |
|---|---|
if_visible: {selector, then, else?} | Optional screens: dialogs, onboarding, a screen left open by a previous run |
retry: {steps, max, backoff_s} | Flaky landings, cold starts |
subroutine: <name> | Shared preamble across actions (e.g. open_calculator); define under subroutines:, not agent-callable |
run_skill {name: <author>/<slug>, action, params} | Reuse another skill’s action (e.g. a login skill) |
ask: {...} | Collect one typed answer from a human or an agent (section 6) |
for_each: {over, as, map?, skip?, strict?, steps} | Repeat steps per character or list item; inner steps use {{context.<as>}} and {{context.<as>_mapped}} (double braces survive the outer pass) |
python_action targets resolve by file path relative to the skill dir (helpers:fn is helpers.py). Dotted gitd.* paths are rejected. Helpers may call device.dump_xml(), device.tap(), device.adb(...), write results to context.result.
Return a plain payload dict, such as {"count": 5}, to merge its fields into context.result. ActionResult(success=True, data=payload) and {"success": True, "data": payload} are also supported. Dict keys success, error and data identify a result envelope: if your payload uses those names, put it under data. A result with success=False fails the step.
Security tiers (docs/skillhub/security.md; enforced except APK sources and automatic Tier 3 rejection) decide what CI runs unattended: a YAML-only hard skill for an allowlisted app runs on the emulator automatically (Tier 1); any submitter Python, or an app not on the allowlist, waits until a maintainer has read it and added approved:<full sha> (Tier 2); network calls from skill code, secrets, arbitrary APK URLs and obfuscated code are rejected (Tier 3). Prefer YAML when it can express the flow.
5. Validators and popups
Section titled “5. Validators and popups”7 validator kinds, composable with all_of, any_of, not (a bare list means all_of):
| Kind | Use when |
|---|---|
text_visible {text, exact?} | The terminal screen shows a known string (supports {param}) |
element_present {id|desc|text} | A specific element proves the screen |
url_contains {substring} | Browser or WebView flows |
pixel_at {x, y, rgb, tolerance?} | Toggle state with no a11y signal |
ocr_text_present {text, region?} | Text drawn on canvas, not in the a11y tree |
screen_hash {ref_hash, similarity_min?} | Visually fixed screens |
custom_python {function: "validators:fn"} | Parsing or comparing values; (device, context) -> bool |
4 popup layers, outermost first:
- OS catalog (engine): permission dialogs denied, battery and update nags dismissed. Override per skill with
os_popup_policy. popup_detectors:{detect: "text", button: "Not now", label: "..."}for this app’s nags. First match wins. Runs only before steps that read the a11y tree.on_popupper action: when a popup is part of the flow,{"<label>": {method: accept|dismiss|prompt_user|custom_python, steps: [...]}}.- Unknown-popup safety net (implicit): a failed step after a new modal appears triggers a BACK cascade and one retry, then
UnknownPopupErrorwith a screenshot. Add a Layer 2 detector for what it caught.
python_action code is not swept; handle popups inside the helper or split the risky screen change into a YAML step.
6. Checkpoint and ask
Section titled “6. Checkpoint and ask”checkpoint: pause for something a bot must not do (captcha, SMS or email code, login).
- checkpoint: reason: captcha # captcha | sms | email | login | llm_decision | generic prompt: "Solve the captcha on the phone, then resume" success: {kind: url_contains, substring: "/inbox"} timeout_s: 600 # 0 = wait foreverIt resumes on a human resume or when success: passes, raises CheckpointTimeoutError or CheckpointAbortedError, and is never retried by Layer 4. Dry runs resolve it immediately.
ask: collect one typed answer mid-run and store it in {context.<store_as>}.
- ask: who: parent_agent # human | parent_agent | sub_agent prompt: "Which contact did the user mean?" attach: [screenshot, a11y, {params: [query]}] schema: {type: enum, values: [first, second]} # str | int | enum | json store_as: selection timeout_s: 0 fallback: fail # or {value: first}human: answered through the checkpoint channel (dashboard or MCP).parent_agent: the run returnsstatus: needs_inputwith aresume_token, the prompt, attachments and schema. The calling agent answers with MCPrun_skill_resume(token, answer)(answer is JSON text) orghost skill resume <token> --answer '<json>'. Invalid answers keep the token; a valid one consumes it and continues on the same device.sub_agent: a bounded Claude Code call (tools off, at most three turns), falling back when unavailable.
Answers are validated strictly against schema. Any ask without fallback: {value: ...} makes the run gated (the legacy schema calls this skill_class: soft), and agent asks mark the run as spending tokens at replay. Traces and signed artifacts record ask metadata, never screenshots.
7. Quality ladder (from skillhub/scoring/v1.json)
Section titled “7. Quality ladder (from skillhub/scoring/v1.json)”Score is 0 to 100. A tier needs its points floor and its hard gates.
| Tier | Points | Hard gates |
|---|---|---|
| Draft | 0 | validates, static scan clean |
| Runs | 10 | README + one signed self-run |
| Proven | 35 | your own passing current run on every action + at least one demo + 3 validator units on every action (reachable on your own evidence) |
| Hardened | 60 | one independent run by another account on a fingerprint you have not recorded on, 2+ OEM or Android-major combos, bench on 2+ models, 10+ community runs with Wilson LB >= 0.80, failure-modes doc, re-verified within 90 days |
| Reference | 90 | Hardened 60+ days, curator review, no open P1 over 14 days, author Contributor+ |
What earns points:
| Category (cap) | Items |
|---|---|
| Docs (20) | manifest 3, README 3, “Known failure modes” section 4, any demo 4, a demo for every action 3, a before/after pair (demos/before-after.webm + demos/before-after.json) 3 |
| Self-evidence (30) | first self-run 4, validator units 2 each up to 8 (per action: the weakest action counts; custom_python or a text check that uses a {param} = 2 units, a bare presence check = 1), bench on one model 4, self-reliability up to 10 (Wilson lower bound over all your own verified runs, pass or fail, once every action has 3+ of them), your own passing runs on a second device for every action 4 |
| Independent (30) | first independent run 12, second device class 8, third 4, bench on a second model 4, third model 2 |
| Community usage (10) | round(10 x Wilson lower bound, z 1.96) over the last 90 days once 10+ runs exist |
| Maintenance (10) | re-verified within 30 days 6, each bug report answered within 7 days 2 (up to 4) |
Freshness multiplier on independent and community usage: 1.0 within 90 days, 0.8 to 180 days (label “Stale”), 0.5 after. A failing run on a newer app version freezes the tier within 24 h. New tiers show “provisional” for 7 days. Downloads and likes are worth 0.
8. Author flow
Section titled “8. Author flow”# 0. Get the v2 CLI. The PyPI release (1.5.x) has no `ghost skill scaffold`; until 1.6.0 ships:git clone https://github.com/ghost-in-the-droid/android-agent && cd android-agent && pip install -e .ghost skill doctor # "FAIL adb devices" is expected until a phone or emulator is attached; the rest must be OKghost skill scaffold <you>/<slug> --app <package> --actions a,b [--skill-class soft]# ... explore the app, write steps, helpers, SOFT.md, README.md; replace EVERY "TODO" the scaffold left# (validate does not check prose; lint flags leftover TODOs; submit refuses them) ...ghost skill validate skillhub/<you>/<slug> # schema, imports, demos layoutghost skill lint skillhub/<you>/<slug> # unused params, TODOs, SOFT.md sections, coord tapsghost skill analyze skillhub/<you>/<slug> # AST security scan; exit 2 on highghost skill test skillhub/<you>/<slug> --live --device <serial> [--action a] [--param k=v]ghost skill run skillhub/<you>/<slug> <action> --param k=v --device <serial> --record [--live-trace]ghost skill demo skillhub/<you>/<slug> a --mode hard --device <serial> --render-host <host> [--param k=v] [--dry]ghost skill submit skillhub/<you>/<slug> # prints PR title, branch, files, bodyghost skill submit skillhub/<you>/<slug> --push # forks, pushes skill/<you>-<slug>, opens the PRrun --recordwritesruns/<fingerprint-hash>-<ts>.json, signed with~/.ghost/run-signing-key. iOS needs--fingerprint <file.json>.- The registry counts a run only if its signature verifies against
skillhub/SIGNERSfor your author name: runghost skill keys --principal <you>and add the printed line toskillhub/SIGNERSin your first PR (CI checks the key is on your GitHub account). Fake-device runs (--device fake:...) are flaggedsimulation: trueand never count. demois the supported hub video recorder. Use--mode softfor a real live Claude Code session followingSOFT.md; it requires authentication and never falls back to replay. Use--spec spec.yamland the card flags to customize every card.--trim-idlecuts the final composite only. Seedocs/DEMO_RECORDING.md.demorecordsdemos/<action>.webm(+.spec.yaml) per action, usingdemo_params. Encoding runs on--render-hostover ssh, never locally;--dryprints the plan. Clips: 30 s or less, 3 MB hard limit.- Someone else then runs
ghost skill verify <you>/<slug>@<version> --device <serial> [--push]: independent runs earn independent points and are the first gate of Hardened.
Starting from an existing flow instead of scaffold:
ghost skill import --maestro flow.yaml [--out skillhub/<you>/<slug>]ghost skill import --automate flow.flo [--out ...]ghost skill import --androidworld <android_world checkout> # draft skills, one action per taskghost skill migrate <v1-skill-dir> [--author <login>] [--dry-run]Unmapped source steps become commented TODO steps and lint warnings, never silent drops.
From an agent trace: map each tool call 1:1 to a step (tap_element for a11y taps, type_text, press_key, launch_app), replace waits on fixed time with wait_for_*, lift repeated preambles into a subroutine, turn what the agent checked at the end into the end_state_validator, and record every dialog the agent dismissed as a popup_detectors entry. Set generated_with to the model and harness.
9. Do and don’t
Section titled “9. Do and don’t”Do
- Prefer locators:
desc>id>text> coordinates. A coordinate tap needs a comment saying why and on which resolution. - Wait on state (
wait_for_text,wait_for_element,if_visible) instead ofsleep. - End hashtag or tag input with a trailing space so the app closes its suggestion panel before the next tap (see the TikTok excerpt).
- Make actions idempotent: launch or back out to a known screen first.
- Write 3+ validator leaves that check the outcome, not just “screen changed”.
- Declare
side_effects,destructive,data_access,tos_riskhonestly; destructive actions get a confirm gate. - Use an SPDX
licenseand a truthfulgenerated_with. - Keep
demo_paramsand examples generic: placeholder handles, sample files, public data.
Don’t
- Never call
dump_xmlor a11y-reading steps while video autoplays: uiautomator never idles. Blind-tap to a static screen first, then read. - No real accounts, phone numbers, emails, device serials or tokens in examples,
SOFT.md, runs or demos. - No engagement farming, mass messaging, scraping other people’s data, captcha solvers or impersonation.
- No
os.system,shell=True,eval, network calls, obfuscation, secrets, or writes outside the skill dir in helpers (Tier 3 reject). - Don’t edit
SKILL.md,skillhub/registry.jsonorskillhub/registry/; they are generated. - Don’t verify your own skill; it never counts as independent.
10. Worked excerpt: calculator (simple hard skill)
Section titled “10. Worked excerpt: calculator (simple hard skill)”A subroutine brings the app to a known screen whatever state it was left in; actions reuse it.
subroutines: - name: open_calculator steps: - {action: launch_app, package: org.fossify.math} - {action: sleep, duration_s: 1.5} - if_visible: selector: {id: "org.fossify.math:id/alertTitle"} then: - {action: press_key, key: BACK} - {action: wait_for_element, id: "org.fossify.math:id/btn_equals", timeout_s: 10}
actions: - name: get_history ref_prompt: "Show my recent calculations" params: [] steps: - subroutine: open_calculator - {action: tap_element, desc: "History"} - {action: wait_for_text, text: "History", timeout_s: 5} - python_action: "helpers:get_history" - if_visible: selector: {text: "OK"} then: - {action: tap_element, text: "OK"} end_state_validator: all_of: - {kind: element_present, id: "org.fossify.math:id/btn_equals"} - {kind: custom_python, function: "helpers:history_read"}11. Worked excerpt: tiktok (hard app, autoplay and hashtags)
Section titled “11. Worked excerpt: tiktok (hard app, autoplay and hashtags)”The home feed autoplays, so the subroutine blind-taps the Profile tab with a retry and only reads the screen once the static profile page is up:
- name: nav_to_profile_tab steps: - {action: launch_app, package: com.zhiliaoapp.musically} # Home feed autoplays: uiautomator cannot idle. Blind-tap Profile (stable on # 1080x2400), then dump AFTER landing on the static profile page. - {action: sleep, duration_s: 3} - retry: max: 3 backoff_s: 3 steps: - {action: tap, x: 972, y: 2214}The hashtag helper ends its input with a trailing space so the suggestion panel closes and the next BACK only hides the keyboard:
hashtag_str = " ".join(f"#{t.lstrip('#')}" for t in tags)[1:] + " "device.adb("shell", "input", "text", input_text_arg(hashtag_str))Validators check the result, with params interpolated:
end_state_validator: all_of: - {kind: text_visible, text: "@{handle}"} - {kind: custom_python, function: "validators:active_handle_matches"}