form-filling

Form Filling Skill

Description

Automatically fill web forms with provided data. This skill handles various form field types and can optionally submit the form after filling.

Dependencies

• web-scraping - Required for detecting form fields and structure

Parameters

Parameter	Type	Required	Default	Description
url	String	Yes	-	The URL of the page containing the form
formData	Map<String, String>	Yes	-	Key-value pairs representing field names and values
submit	Boolean	No	false	Whether to submit the form after filling

Return Value

Returns a SkillResult with the following data structure:

{
  "url": "string",
  "filledFields": ["field1", "field2"],
  "submitted": boolean,
  "message": "status message"
}

Usage Examples

Basic Form Filling

val result = registry.execute(
    skillId = "form-filling",
    context = context,
    params = mapOf(
        "url" to "https://example.com/contact",
        "formData" to mapOf(
            "name" to "John Doe",
            "email" to "[email protected]",
            "message" to "Hello!"
        )
    )
)

Form Filling with Submission

val result = registry.execute(
    skillId = "form-filling",
    context = context,
    params = mapOf(
        "url" to "https://example.com/signup",
        "formData" to mapOf(
            "username" to "johndoe",
            "password" to "securepass123",
            "email" to "[email protected]"
        ),
        "submit" to true
    )
)

Tool Call Specification

ToolSpec(
    domain = "skill.form",
    method = "fill",
    arguments = [
        "url: String",
        "formData: Map<String, String>",
        "submit: Boolean = false"
    ],
    returnType = "SkillResult",
    description = "Fill a web form with the provided data"
)

Error Handling

The skill returns a failure result in the following cases:

• Missing required parameter url
• Missing required parameter formData
• Empty formData map
• Form fields not found on the page

Lifecycle Hooks

onBeforeExecute

Validates that formData is not empty before execution.

validate

Checks if the required dependency skill (web-scraping) is available in the registry.

Implementation Notes

• Headless mode is the default for AI agents: Always open browsers in headless mode unless the user explicitly requests a visible browser window (e.g., "show me the browser", "open visibly", "headed"). Headless mode is faster, uses fewer resources, and avoids unnecessary GUI windows. If user participation in the page interaction is required — e.g., logging in or entering a verification code (CAPTCHA) — open a headed browser so the user can see and act on the page. Also open headed as a one-shot escalation when the site blocks the headless browser as a bot (CAPTCHA/challenge/interstitial page, "unusual traffic", or an empty body where content was expected): close, then open --headed <url> with the same session and retry once, telling the user that anti-bot protection forced the switch. If the headed retry is blocked too, stop and report instead of looping.
• Supports various input types: text, email, password, textarea, select, checkbox, radio
• Automatically handles form field detection and mapping
• Respects CSRF tokens and hidden fields
• Can handle multi-page forms through shared context
• Thread-safe execution

Security Considerations

• Never log sensitive form data (passwords, credit cards, etc.)
• Validate form URLs to prevent CSRF attacks
• Use HTTPS URLs for sensitive forms
• Clear sensitive data from memory after use

See Also

• Web Scraping Skill
• Data Validation Skill