adb-skill-generator

---

Quick Reference (30 seconds)

Rapid adb- skill creation from production-tested templates*

What It Does: Automates creation of new adb-* skills by generating skill directory structure, SKILL.md metadata, script templates, and example workflows. Speeds up new skill development from hours to minutes.

Core Capabilities:

• 🚀 Scaffold Skills: Generate complete skill directory structure
• 📝 Template Scripts: Create launcher, checker, automator, tester scripts
• 📋 SKILL.md Generation: Auto-generate metadata with proper frontmatter
• 📊 Workflow Examples: Optional TOON workflow templates
• ✅ Best Practices: Built-in ecosystem patterns and conventions

When to Use:

• Creating new app automation skills
• Rapid prototyping of automation workflows
• Onboarding new skill developers
• Standardizing skill structure across ecosystem

---

Scripts

adb-skill-generator.py

Generate new adb-* skill from templates.

# Minimal skill (1 launcher script)
uv run .claude/skills/adb-skill-generator/adb-skill-generator.py \
    --skill-name banking \
    --description "Banking app automation via Play Integrity bypass"

# Full skill (3 scripts + workflow)
uv run .claude/skills/adb-skill-generator/adb-skill-generator.py \
    --skill-name fitness \
    --description "Fitness app testing" \
    --script-count 3 \
    --with-workflow

# With category specification
uv run .claude/skills/adb-skill-generator/adb-skill-generator.py \
    --skill-name streaming \
    --description "Streaming app automation" \
    --category adb-app-automation

# List available templates
uv run .claude/skills/adb-skill-generator/adb-skill-generator.py \
    --list-templates

# JSON output
uv run .claude/skills/adb-skill-generator/adb-skill-generator.py \
    --skill-name myapp \
    --description "My app automation" \
    --json

Parameters:

• --skill-name (required): Name of skill (with or without adb- prefix)
• --description (required): Brief description of skill purpose
• --script-count (optional, default: 1): Number of scripts (1-4)
• --with-workflow (optional): Generate example TOON workflow
• --category (optional): Skill category (default: adb-app-automation)
• --list-templates: Show available templates
• --json: JSON output instead of human-readable
• --verbose: Detailed operation logging

Exit Codes:

• 0: Success (skill created)
• 1: Warning (partial creation)
• 2: Error (skill creation failed)
• 3: Critical (invalid parameters)

Generated Structure:

.claude/skills/adb-{skillname}/
├── SKILL.md                           # Metadata + documentation
├── scripts/
│   ├── adb-{skillname}-launch.py      # Launcher script
│   ├── adb-{skillname}-check.py       # Checker script (if count >= 2)
│   ├── adb-{skillname}-test.py        # Tester script (if count >= 3)
│   └── adb-{skillname}-validate.py    # Validator script (if count >= 4)
├── workflows/
│   ├── {skillname}-basic.toon         # Basic workflow example
│   └── {skillname}-advanced.toon      # Advanced workflow example (if requested)
├── templates/                          # (Empty - for user templates)
└── analysis/                          # (Empty - for analysis results)

---

Quick Examples

Example 1: Minimal Skill Generation

uv run adb-skill-generator.py \
    --skill-name twitter \
    --description "Twitter app automation for testing"

Creates:

• adb-twitter/SKILL.md
• adb-twitter/scripts/adb-twitter-launch.py (launcher)
• adb-twitter/workflows/twitter-basic.toon (basic example)
• Directory structure ready for customization

Example 2: Complete Skill with Workflow

uv run adb-skill-generator.py \
    --skill-name instagram \
    --description "Instagram app automation and testing" \
    --script-count 3 \
    --with-workflow

Creates:

• adb-instagram/SKILL.md
• adb-instagram/scripts/adb-instagram-launch.py (launcher)
• adb-instagram/scripts/adb-instagram-check.py (checker)
• adb-instagram/scripts/adb-instagram-test.py (tester)
• adb-instagram/workflows/instagram-basic.toon
• adb-instagram/workflows/instagram-advanced.toon

Example 3: JSON Output for CI/CD Integration

uv run adb-skill-generator.py \
    --skill-name facebook \
    --description "Facebook app automation" \
    --json

Output:

{
  "skill_name": "adb-facebook",
  "success": true,
  "skill_path": "/path/to/.claude/skills/adb-facebook",
  "scripts_created": 1,
  "skill_md_created": true,
  "workflow_created": false,
  "duration": 0.45,
  "messages": [
    "✅ Created skill directory: ...",
    "✅ Created scripts/ subdirectory",
    "✅ Created SKILL.md ...",
    "✅ Created script: adb-facebook-launch.py"
  ],
  "exit_code": 0
}

---

Script Template Structure

All generated scripts follow the proven 9-section IndieDevDan template:

1. Docstring          - Comprehensive description with examples
2. Imports            - Required libraries
3. Constants          - Configuration values
4. Project root       - Auto-detection logic
5. Data models        - Result dataclasses
6. Helpers            - Utility functions (device selection, etc.)
7. Core logic         - Primary automation implementation
8. Formatters         - Human + JSON output formatting
9. CLI interface      - Click command-line interface
10. Entry point       - Main execution guard

Benefits:

• Consistent structure across all skills
• Easy to understand and maintain
• Proven patterns from production skills
• Familiar to all developers

---

Workflow Template Structure

Generated workflows follow TOON format:

name: {skillname}-basic
description: Basic automation for {skillname}

parameters:
  device: "127.0.0.1:5555"
  timeout: 30

phases:
  - id: phase-1
    name: "Launch app"
    steps:
      - id: launch
        action: {skillname}-launch
        params:
          device: "{{ device }}"

recovery:
  - on_error: launch
    action: retry
    then: continue

Features:

• Parameter templating with {{ variable }}
• Phase-based organization
• Error recovery rules
• Executable with adb-run-workflow

---

Integration with Ecosystem

Step 1: Generate Skill

uv run adb-skill-generator.py \
    --skill-name myapp \
    --description "My app automation"

Step 2: Implement Core Scripts

Edit generated scripts to add actual automation logic:

• scripts/adb-myapp-launch.py - App launch logic
• scripts/adb-myapp-check.py - State checking logic
• scripts/adb-myapp-test.py - Functional testing

Step 3: Create Advanced Workflows

Build TOON workflows using generated scripts:

uv run adb-run-workflow.py \
    --workflow .claude/skills/adb-myapp/workflows/myapp-advanced.toon \
    --verbose

Step 4: Share or Distribute

Generated skill is immediately usable by others:

uv run .claude/skills/adb-myapp/scripts/adb-myapp-launch.py --device 127.0.0.1:5555

---

Design Philosophy

The generator embodies ADB ecosystem design principles:

1. Convention over Configuration

• Default settings work for 90% of use cases
• Simple naming patterns (adb-{skillname})
• Consistent file organization

2. Rapid Development

• Scaffold complex structure in seconds
• Focus on implementation, not boilerplate
• Templates from production-tested code

3. Quality by Default

• Generated code follows best practices
• Includes error handling, timeouts, retries
• Proper exit codes and logging

4. Extensibility

• Generated code is production-ready but customizable
• Clear sections for user implementation
• Supports skill composition and integration

---

Related Skills

This generator uses and integrates with:

• adb-screen-detection: For OCR-based element finding
• adb-navigation-base: For gesture automation (tap, swipe, wait)
• adb-workflow-orchestrator: For complex multi-step orchestration

All generated skills can depend on these foundation skills automatically.

---

Common Customization Patterns

Pattern 1: Custom Package Name

# In generated script, change:
APP_PACKAGE = "kr.co.flo.karrot"  # Replace with your app package

Pattern 2: Custom UI Elements

# In launcher script, change:
result = launch_app_with_verification(
    device_id,
    wait_text="Custom Login Screen"  # Your app's specific screen
)

Pattern 3: Custom Timeout

# In any script, change:
VERIFICATION_TIMEOUT = 45  # Slower apps need more time

---

Troubleshooting

Q: Script generation failed

# Ensure valid skill name (alphanumeric + hyphens)
uv run adb-skill-generator.py --skill-name valid-name --description "..."

Q: How to see what will be generated?

# Use --verbose flag
uv run adb-skill-generator.py \
    --skill-name myapp \
    --description "..." \
    --verbose

Q: Can I use generated scripts immediately?

# Yes, scripts are immediately usable but may need customization
uv run .claude/skills/adb-myapp/scripts/adb-myapp-launch.py --device 127.0.0.1:5555

---

Workflows

This skill includes TOON-based workflow definitions for automation.

What is TOON?

TOON (Task-Oriented Orchestration Notation) is a structured workflow definition language that pairs with Markdown documentation. Each workflow consists of:

• [name].toon - Orchestration logic and execution steps
• [name].md - Complete documentation and usage guide

This TOON+MD pairing approach is inspired by the BMAD METHOD pattern, adapted to use TOON instead of YAML for better orchestration support.

Available Workflows

Workflow files are located in workflow/ directory:

Example Workflows (adb-skill-generator):

• workflow/skill-generation.toon - Complete skill generation workflow
• workflow/template-validation.toon - Validate and test generated skill templates

Running a Workflow

Execute any workflow using the ADB workflow orchestrator:

uv run .claude/skills/adb-workflow-orchestrator/scripts/adb-run-workflow.py \
  --workflow .claude/skills/adb-skill-generator/workflow/skill-generation.toon \
  --param skill_name="myapp"

Workflow Documentation

Each workflow includes comprehensive documentation in the corresponding .md file:

• Purpose and use case
• Prerequisites and requirements
• Available parameters
• Execution phases and steps
• Success criteria
• Error handling and recovery
• Example commands

See the workflow/ directory for complete TOON file definitions and documentation.

Creating New Workflows

To create custom workflows for this skill:

1. Create a new .toon file in the workflow/ directory
2. Define phases, steps, and parameters using TOON v4.0 syntax
3. Create corresponding .md file with comprehensive documentation
4. Test with the workflow orchestrator

For more information, refer to the TOON specification and the workflow orchestrator documentation.

---

Version: 1.0.0 (Production Ready) Last Updated: 2025-12-02 Category: Meta-Automation (Tier 3)