How to use the AdGuard Home CLI agent skill

What is an agent skill and what does this one let the agent do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to use a tool. This skill is built around the cli-anything-adguardhome command-line interface, which talks to the AdGuard Home REST API.

Once installed, the agent can run the CLI to check server protection status and version, list, add, enable, disable and remove filter lists, and force-refresh them. It can also manage DNS rewrites, client devices, query logs and statistics, parental control, safe browsing and safe search, blocked services, and DHCP status, leases and static leases.

Install the skill with a ZIP file or the Claude apps

Download the skill ZIP from this page and unzip it into one of two locations. For a personal skill available in all your projects, unzip it into ~/.claude/skills/. For a skill limited to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

The skill's SKILL.md file is the entry point the agent reads, so it should sit directly inside the skill folder after unzipping.

Install the CLI and AdGuard Home

The skill needs the command-line tool itself. The source installs it as a pip package, and it requires Python 3.10 or newer. AdGuard Home must already be installed and running, because the tool only controls an existing server and does not replace it.

If you still need AdGuard Home, the source gives an install script command. Review the script before running it on your machine.

• Python 3.10 or newer
• A running AdGuard Home instance reachable over its REST API
• The cli-anything-adguardhome pip package
• Admin connection settings (host and credentials) configured in the CLI

Connect the CLI and test the connection

Before anything else, the skill tells the agent to test the connection. The config group shows the current connection settings, can save them to a config file, and tests the connection to AdGuard Home. Run the test first so you know the host and credentials work.

You can also run the tool yourself to confirm it works. Asking for help or checking server status are safe, read-only starting points.

• config show displays the current connection configuration
• config save stores connection settings in a config file
• config test checks the connection

Trigger the skill with natural requests

You do not need to type commands. Ask in plain language about AdGuard Home, DNS filtering, blocklists, DHCP or query logs, and the agent should pick up the skill from its description. Be specific about the device, domain or list you mean, and say when you only want to look rather than change things.

The skill asks the agent to use JSON output and to check return codes, so the agent can read results reliably.

• "Check whether AdGuard Home protection is on and which version is running."
• "Add the list at this URL as a filter and refresh the filters."
• "Create a local DNS name myserver.local pointing to 192.168.1.50."
• "Show the top query stats from the last session, read-only."
• "Add my PC at 192.168.1.100 as a client named My PC."

Examples of common commands

The source shows these examples. Each one maps to a request you could make in natural language. Use --json when an agent is reading the output, and omit it when you want a readable table.

Output modes: the default is human-readable with tables and colors, and the --json flag returns structured JSON.

• Filters: filter list, filter add with a URL and name, filter refresh
• DNS rewrites: rewrite add with a domain and answer, rewrite list
• Clients: clients add with name and IP, clients list
• Statistics: stats show, or --json stats show for agents

Safety: scripts, network access and changes

This skill runs scripts and uses the network. It talks to your AdGuard Home server over its REST API, so it needs your admin host and credentials. Store those carefully and only point the tool at a server you control.

Changes can affect everyone on the network. Changing DNS, DHCP or blocking rules without review can break connectivity for every device. Ask the agent to show current state first, and review any add, remove, restart, clear or reset action before it runs. The source's own guidance is to test the connection first and to use absolute paths for file operations.

This skill is not a per-device ad blocker. It manages the network-wide server.

• Check return codes: 0 means success, non-zero means an error
• Parse stderr for error messages when a command fails
• Use absolute paths for all file operations
• Keep a backup of your AdGuard Home configuration before large changes

Tips for reliable results

Start with read-only commands such as server status, filter list and rewrite list so you see the current setup before changing it. Ask the agent to report the output before it makes a change.

Use the REPL mode if you prefer an interactive session with tab-completion and history. For more detail, the source points to README.md and TEST.md in the package.

• Run the connection test before any other command
• Prefer --json when the agent reads results
• Check the README.md in the package for full documentation