Guide · Agent skill

How to use the MacroCLI GUI Macros agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The MacroCLI GUI Macros skill teaches an AI agent to run repeatable desktop and file workflows through a command-line tool instead of clicking through a graphical interface. It is aimed at developers and teams who already have MacroCLI installed and want agents to call named, parameterized macros. After this guide you will know how to install the skill, trigger it with plain requests, and use the dry-run, JSON and success-checking habits the skill recommends.

MacroCLI GUI MacrosHKUDS/CLI-Anything · Apache-2.0 Download the skill

Quick start

1Install MacroCLI. Install Python 3.10+ and the required packages, then run pip install -e . from the macrocli/agent-harness folder.
2Add the skill folder. Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for shared use.
3List macros. Run macro list with --json to see which macros are available.
4Inspect parameters. Run macro info with the macro name and --json to see its parameters and steps.
5Dry-run first. Run the macro with --dry-run and your --param values to simulate it without side effects.
6Execute and check success. Run the macro for real with --json, then read the success field and, if false, the error field.

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to use a tool. This skill covers the MacroCLI command-line tool. MacroCLI turns GUI workflows into parameterized macros, which are named workflows that accept inputs such as file paths or key names.

Agents do not touch the GUI directly. They call macros through the CLI, and the MacroCLI runtime chooses a backend for each step: a native command, a file transformation, accessibility or keyboard control, or replay of precompiled GUI actions.

Lists available macros and their parameters
Inspects a macro's schema, including parameters, steps and conditions
Runs a macro, optionally as a dry run first
Reports which backends are available in the current environment

Install the MacroCLI package and the skill

The skill does nothing without the MacroCLI package. The source installs it from the agent-harness folder of the macrocli project with pip in editable mode. Requirements are Python 3.10+, PyYAML, click and prompt-toolkit.

To add the skill itself, download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to share it with that project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Requirements: Python 3.10+, PyYAML, click, prompt-toolkit
Install MacroCLI from macrocli/agent-harness before using the skill
Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your project
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

cd macrocli/agent-harness
pip install -e .

Trigger the skill with natural requests

You do not need special syntax. The skill is meant to activate when you ask the agent to define, list, inspect or execute GUI macros through MacroCLI. Name the macro or the outcome you want, and mention MacroCLI if you want to be certain the skill is used.

The agent is expected to follow the quick-start sequence in the skill: list macros, inspect the one you need, dry-run it, then execute it.

"List the MacroCLI macros available on this machine."
"Show me the parameters for the export_file macro."
"Dry-run transform_json with file /tmp/config.json, key theme, value dark."
"Run export_file and write the result to /tmp/result.txt."

Run the core commands yourself

The skill's quick start uses five commands. Each one supports --json so the output is machine-readable. The macro group handles listing, inspection and execution, and the backends command shows what is available in your environment.

Parameters are passed with --param key=value, and you repeat the flag for each parameter. The --dry-run global flag simulates steps without side effects.

macro list: list all available macros
macro info <name>: show parameters, steps and conditions
macro run <name> --param k=v: execute a macro
macro dry-run <name> --param k=v: simulate without side effects
backends: show native_api, file_transform, semantic_ui, gui_macro and recovery and whether each is available
session status, session history, session save, session list: manage session statistics and run history

cli-anything-macrocli macro list --json
cli-anything-macrocli macro info export_file --json
cli-anything-macrocli --dry-run macro run export_file --param output=/tmp/test.txt --json
cli-anything-macrocli macro run export_file --param output=/tmp/result.txt --json
cli-anything-macrocli backends --json

Read the JSON output and handle failures

When --json is set, the output includes a success field, the macro name, an output object, an error string and telemetry such as duration, steps run and whether it was a dry run. The skill tells the agent to check success rather than rely on exit code alone.

On failure, success is false, the error field explains the reason, and the exit code is 1.

Check the success field before trusting a result
Read the error field when success is false
Telemetry reports steps_total, steps_run, backends_used and dry_run

{
  "success": true,
  "macro_name": "export_file",
  "output": {
    "exported_file": "/tmp/result.txt"
  },
  "error": "",
  "telemetry": {
    "duration_ms": 312,
    "steps_total": 2,
    "steps_run": 2,
    "backends_used": ["native_api"],
    "dry_run": false
  }
}

Safety notes before running macros

The skill runs scripts and the macros it calls can change real files and drive real GUI actions. The native_api backend runs subprocess or shell commands, so a macro can execute arbitrary commands. Do not run macros unattended on machines holding important data unless you have reviewed the macro definitions.

The source says reversibility depends on each macro's agent_hints, which are not verified by the skill. Do not rely on rollback unless you have checked those hints for the specific macro. The skill does not use the network, according to its metadata.

Always dry-run side-effectful macros first
Use absolute paths for all file parameters
Review each macro's agent_hints (danger_level, side_effects, reversible) before running it
Do not assume a macro can be undone

Write your own macros

Macros are YAML files in cli_anything/macrocli/macro_definitions/. You can scaffold one with the define command, which writes a starting file to the path you give. A minimal macro has a name, version, description, parameters, preconditions, steps, postconditions, outputs and agent_hints.

Each step names a backend such as native_api or file_transform. Postconditions such as file_exists let the runtime confirm the outcome.

Scaffold with macro define <name> --output <path>
Steps set backend, action, params, timeout_ms and on_failure (fail, skip or continue)
Parameters use ${name} placeholders in steps and postconditions

cli-anything-macrocli macro define my_macro --output \
    cli_anything/macrocli/macro_definitions/examples/my_macro.yaml

What people use it for

Re-exporting a file to a chosen location with a named macro and parameters
Transforming a JSON config value such as a theme setting with transform_json
Checking which backends such as native_api or file_transform are available on a machine before planning a workflow
Keeping macro definitions in YAML so teammates can review them before agents run them

Frequently asked questions

How do I install the MacroCLI agent skill?

Install the MacroCLI package from the macrocli/agent-harness folder with pip install -e . Then download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.

What are the requirements for this skill?

The source lists Python 3.10+, PyYAML, click and prompt-toolkit, plus the MacroCLI package installed via pip install -e . from macrocli/agent-harness. The skill does nothing without the package.

Is the MacroCLI GUI Macros skill free?

The source gives the licence as Apache-2.0 for the HKUDS/CLI-Anything repository. It does not state pricing, so check the repository for licence terms before using it.

Does the skill run scripts or use the network?

The skill's metadata says it runs scripts and does not use the network. Macros can run shell commands through native_api, so review macro definitions before running them.

Why does my macro return success false?

When success is false, the JSON error field gives the reason and the exit code is 1. Start by checking the error text, confirm your parameters with macro info, and use absolute paths for file inputs.

How is this different from just clicking through the interface?

Instead of clicking through a GUI, the agent runs named macros with parameters through a stable CLI. The runtime picks how each step runs, and the agent can dry-run and check JSON results before trusting an outcome.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers and teams who already use MacroCLI and want agents to run defined macros with dry-run previews and structured JSON results. It is a poor fit if you have not installed the MacroCLI package, or if you need guaranteed rollback or unattended runs on machines with important data, since reversibility depends on each macro's unverified agent_hints.

Download the skill