Skip to content

📘 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.

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.md reference notes the agent reads with get_skill_notes when 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: soft value marks gated execution. See docs/skill-taxonomy-soft-vs-hard.md.

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 checked

The 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 skill
README.md required for Runs tier
SOFT.md one section per action; the narrative adapt mode reads when the UI drifts
helpers.py optional python_action targets, flat file
validators.py optional custom_python validators
icon.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 action
runs/ your signed self-runs (ghost skill run --record)
verifications/ other people's signed runs, added by their PRs
SKILL.md GENERATED by the registry builder, do not edit
name: calculator # = folder slug
version: 1.0.1 # SemVer; bump on every change to an existing skill
author: ghost # = GitHub login = folder name
description: "One line: what it automates"
skill_class: hard # hard | soft
license: MIT # SPDX id, required
generated_with: "Claude Opus 5.5 via Claude Code, hand-explored on an emulator" # required; say how it was made
status: active # active | blocked | deprecated | draft
side_effects: [none] # sends_message, posts_content, makes_payment, modifies_account, deletes_data, none
destructive: false # true requires a confirm gate (checkpoint/ask) or a dry-run param
tos_risk: low # low | medium | high
locale: [en-US] # BCP-47 list you tested in
data_access: [] # contacts, sms, camera, mic, location, notifications, clipboard, files, storage
icon: icon.webp # optional; defaults to icon.webp when present
demo: demos/convert_units.webm # optional default clip; else first action clip
fingerprint:
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 overrides
popup_detectors: [] # Layer 2
subroutines: []
actions: []

Reserved, set by the registry, never by you: trust, quality, schema.

- 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: true

Param 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.

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.

StepUse 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_popupsExtra 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:

StepUse 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.

7 validator kinds, composable with all_of, any_of, not (a bare list means all_of):

KindUse 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:

  1. OS catalog (engine): permission dialogs denied, battery and update nags dismissed. Override per skill with os_popup_policy.
  2. 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.
  3. on_popup per action: when a popup is part of the flow, {"<label>": {method: accept|dismiss|prompt_user|custom_python, steps: [...]}}.
  4. Unknown-popup safety net (implicit): a failed step after a new modal appears triggers a BACK cascade and one retry, then UnknownPopupError with 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.

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 forever

It 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 returns status: needs_input with a resume_token, the prompt, attachments and schema. The calling agent answers with MCP run_skill_resume(token, answer) (answer is JSON text) or ghost 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.

TierPointsHard gates
Draft0validates, static scan clean
Runs10README + one signed self-run
Proven35your own passing current run on every action + at least one demo + 3 validator units on every action (reachable on your own evidence)
Hardened60one 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
Reference90Hardened 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.

Terminal window
# 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 OK
ghost 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 layout
ghost skill lint skillhub/<you>/<slug> # unused params, TODOs, SOFT.md sections, coord taps
ghost skill analyze skillhub/<you>/<slug> # AST security scan; exit 2 on high
ghost 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, body
ghost skill submit skillhub/<you>/<slug> --push # forks, pushes skill/<you>-<slug>, opens the PR
  • run --record writes runs/<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/SIGNERS for your author name: run ghost skill keys --principal <you> and add the printed line to skillhub/SIGNERS in your first PR (CI checks the key is on your GitHub account). Fake-device runs (--device fake:...) are flagged simulation: true and never count.
  • demo is the supported hub video recorder. Use --mode soft for a real live Claude Code session following SOFT.md; it requires authentication and never falls back to replay. Use --spec spec.yaml and the card flags to customize every card. --trim-idle cuts the final composite only. See docs/DEMO_RECORDING.md.
  • demo records demos/<action>.webm (+ .spec.yaml) per action, using demo_params. Encoding runs on --render-host over ssh, never locally; --dry prints 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:

Terminal window
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 task
ghost 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.

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 of sleep.
  • 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_risk honestly; destructive actions get a confirm gate.
  • Use an SPDX license and a truthful generated_with.
  • Keep demo_params and examples generic: placeholder handles, sample files, public data.

Don’t

  • Never call dump_xml or 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.json or skillhub/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"}