filex

Use FileX

FileX is disabled by default. Choose this skill when the task needs content from an existing document or media source. FileX does not need to run for unrelated tasks or to create new documents or media.

When the caller explicitly selects this skill, the selection is an execution requirement rather than a suggestion. Complete the FileX workflow before using a generic parser or claiming the task is finished. In a managed artifact-producing runtime, create the canonical bundle under FILEX_ARTIFACTS_ROOT and require a successful wrapper result. If FileX cannot parse the supplied source, report the FileX failure; do not silently fall back to another parser or synthesize evidence. An unselected baseline run must not invoke FileX merely because the built-in skill is installed.

Use the bundled wrapper for FileX inspect, parse, and status. It validates workspace paths, resolves supported URL sources, keeps credentials out of command-line arguments, preserves FileX JSON fields, and returns output_path for synchronous parsing.

Use the AWorld runtime contract

Invoke FileX through the bundled AWorld wrapper from any working directory:

python3 /skills/filex/scripts/filex.py --help

Do not change into /app/mcp_servers/filesystem_server, call ./bin/filex, or use /root/fs_workspace. Those paths belong to a different MCP filesystem-server image. In a managed AWorld sandbox, FILEX_WORKSPACE_ROOT is commonly /workspace; standalone AWorld images may use $HOME/workspace. Use the runtime-provided value and the task's supplied path instead of deriving a path from the current directory. /skills/filex is read-only and is never an output location.

The wrapper accepts local --input files under FILEX_WORKSPACE_ROOT and HTTP(S) --url sources. Keep the skill focused on those ordinary AWorld source flows rather than deployment-specific object-store workflows.

Follow the parsing workflow

1. Identify the source and confirm that a local file already resides under FILEX_WORKSPACE_ROOT; otherwise use a trusted HTTP(S) URL or ask the caller to stage it. Do not make an unnecessary base64 copy of a mounted file.
2. Let FileX infer the file type when the suffix and content are reliable. Use --file-type only to resolve ambiguity.
3. Let the configured provider handle ordinary files. Select an explicit provider only when the task needs a known capability such as scanned-page OCR, real layout geometry, or text-layer-first VLM fallback.
4. Keep a simple provider choice in --provider. Put provider-private settings and structured values in a protected workspace JSON file and use --env-file; never combine those two options.
5. Run the parse synchronously in the foreground with enough terminal-tool time. For evaluation or durable handoff, request an artifact bundle and an explicit layout format.
6. Use the JSON result, returned paths, page coverage, and warnings to decide whether further inspection would help the task. Keep established facts in task state and revisit them when the source, artifacts, or requirements change.
7. On failure, preserve the wrapper's JSON error, provider/model identity, task id, and any checkpoint. Retry only after the first process has ended and the failure is understood.