Using Skills

Skills can be used from Python code, the REST API, or the dashboard GUI. All three methods ultimately execute the same underlying Action and Workflow classes.

From Python

Load a Skill

from marketing_system.skills.tiktok import load
skill = load()

print(skill.name)              # 'tiktok'
print(skill.app_package)       # 'com.zhiliaoapp.musically'
print(len(skill.elements))     # 41
print(skill.list_actions())    # ['open_app', 'navigate_to_profile', ...]
print(skill.list_workflows())  # ['upload_video', 'crawl_hashtag', ...]

Run an Action

from marketing_system.bots.common.adb import Device

dev = Device()
action = skill.get_action("tap_search", dev)
result = action.run()

print(result.success)       # True/False
print(result.duration_ms)   # execution time
print(result.error)         # error message if failed
print(result.data)          # action-specific return data

Actions follow the pre/execute/post pattern:

1. precondition() verifies the device is in the right state
2. execute() performs the ADB operation (retried up to 2 times)
3. postcondition() verifies the action succeeded

Run a Workflow

wf = skill.get_workflow("engage_fyp", dev, duration=60)
result = wf.run()

print(result.success)
print(result.data)  # {'completed_steps': 5}

Workflows execute each action step in sequence. If any step fails, the workflow stops and reports the failure.

From the REST API

List Skills

curl -s http://localhost:5055/api/skills | python3 -m json.tool

Get Skill Detail

curl -s http://localhost:5055/api/skills/tiktok | python3 -m json.tool

Returns full metadata, action list with descriptions, workflow list, and element definitions.

List Actions and Workflows

curl -s http://localhost:5055/api/skills/tiktok/actions | python3 -m json.tool
curl -s http://localhost:5055/api/skills/tiktok/workflows | python3 -m json.tool

Run a Workflow

curl -X POST http://localhost:5055/api/skills/tiktok/run \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "engage_fyp",
    "params": {"duration": 60},
    "device": "L9AIB7603188953"
  }'

This enqueues a skill_workflow job in the scheduler queue. The response includes the job queue ID for monitoring.

Run a Single Action

curl -X POST http://localhost:5055/api/skills/tiktok/run-action \
  -H "Content-Type: application/json" \
  -d '{
    "action": "tap_search",
    "params": {},
    "device": "L9AIB7603188953"
  }'

Export a Skill as ZIP

curl http://localhost:5055/api/skills/export/tiktok -o tiktok_skill.zip
unzip -l tiktok_skill.zip

The ZIP contains the full skill directory: skill.yaml, elements.yaml, actions, and workflows.

Import a Skill

curl -X POST http://localhost:5055/api/skills/import \
  -F "file=@whatsapp_skill.zip"

Uploads and installs the skill into the skills/ directory.

From the Dashboard

Skill Hub Tab

Navigate to the Skill Hub tab in the dashboard at http://localhost:5055:

1. Card Grid — one card per skill showing name, version, app package, and action/workflow counts
2. Detail View — click a card to expand and see all actions, workflows, and elements
3. Run Controls — select a device, pick a workflow or action, set parameters, and click Run
4. Export — download any skill as a ZIP file
5. Status — after running, the UI shows the job queue ID and links to the Scheduler tab

Device Selection

All execution requires selecting a target device. The dropdown lists all connected phones (both physical and emulators). The selection persists in localStorage.

Execution Flow

Whether you use Python, API, or dashboard, skill execution follows the same path:

User triggers run
    |
    v
POST /api/skills/<name>/run
    |
    v
enqueue_job(type='skill_workflow')
    |
    v
Scheduler picks up job (within 30s)
    |
    v
Spawns: python3 skills/_run_skill.py --skill tiktok --workflow engage_fyp ...
    |
    v
_run_skill.py loads skill, instantiates workflow with Device, calls run()
    |
    v
Result written to job log, status updated in DB

CLI Execution

Skills can also be run directly via the subprocess runner:

python3 -m marketing_system.skills._run_skill \
  --skill tiktok \
  --workflow engage_fyp \
  --device L9AIB7603188953 \
  --params '{"duration": 60}'

This is what the scheduler calls internally.

Next Steps

• Creating Skills — build your own skill
• Elements — understand UI locator chains
• Publishing Skills — share your skill with others