New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Ag2 Shell Tool

by ag2ai in ag2ai/build-with-ag2

Give an AG2 beta Agent the ability to run shell commands. An agent skill from ag2ai/build-with-ag2.

Apache-2.0Auto-check: notesDevelopment

Install Ag2 Shell Tool

skills CLI
$ npx skills add ag2ai/build-with-ag2 --skill ag2-shell-tool -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ag2ai/build-with-ag2 ag2-shell-tool --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ag2ai/build-with-ag2.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/ag2-shell-tool .claude/skills/ag2-shell-tool && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ag2-shell-tool
GitHub stars
252
Token cost
~2k tokens
SKILL.md length
628 words
Files
1
Skills in repo
16
Repo updated
First seen
Licence
Apache-2.0

At a glance

Give an AG2 beta Agent the ability to run shell commands. An agent skill from ag2ai/build-with-ag2.

  • Works in 4 steps: allowed — if set, the command must match… → blocked — if set, the command must not… → ignore — literal path tokens in the… → …
  • The user wants the Agent to execute commands
  • SKILL.md covers When to use, 60-second recipe —…, Sandboxing… and Stateful multi-turn workspaces, plus 4 more sections
  • Calls git

What it does

Ag2 Shell Tool is an agent skill from ag2ai/build-with-ag2. Give an AG2 beta Agent the ability to run shell commands. Covers LocalShellTool (client-side subprocess, works with any provider) and the provider-native ShellTool (Anthropic / OpenAI execution). Use when the user wants the Agent to execute commands, build/test code, manage files, or operate on a workspace. Always pair with sandboxing — allowed, blocked, ignore, or readonly.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. It works with OpenAI and Git. The repository describes itself as: Sample code and application showcases to get you going with AG2 (formally AutoGen). The licence is Apache-2.0.

When your agent uses it

  • The user wants the Agent to execute commands
  • Build/test code
  • Operate on a workspace

Example prompts

  • “/ag2-shell-tool”

Requirements

  • Python 3

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. allowed — if set, the command must match at least one prefix.
  2. blocked — if set, the command must not match any prefix.
  3. ignore — literal path tokens in the command are checked against gitignore-style patterns; matches return "Access denied: ".
  4. Execute via subprocess.run.

What it can do on your machine

Read from SKILL.md and the folder at commit 29eeac3. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ag2 Shell Tool loads about 2k tokens when it runs. Until then it costs about 102 tokens; SKILL.md has 628 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~102
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:68
    ignore=["**/.env", "*.key", "secrets/**"],

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ag2ai/build-with-ag2 at commit 29eeac3, republished under its Apache-2.0 licence (© ag2ai). 628 words, ~2,017 tokens.

Download SKILL.mdSave it as .claude/skills/ag2-shell-tool/SKILL.md (or your agent's skills folder).
name
ag2-shell-tool
description
Give an AG2 beta `Agent` the ability to run shell commands. Covers `LocalShellTool` (client-side `subprocess`, works with any provider) and the provider-native `ShellTool` (Anthropic / OpenAI execution). Use when the user wants the Agent to execute commands, build/test code, manage files, or operate on a workspace. Always pair with sandboxing — `allowed`, `blocked`, `ignore`, or `readonly`.
license
Apache-2.0

Shell tools

When to use

Two distinct tools, both named "shell" — pick deliberately:

NeedUseWhy
Works with any model provider; full control over what runs and whereLocalShellToolClient-side subprocess. You own the sandbox.
Provider-managed sandbox (container, network policy) on Anthropic / OpenAIShellToolServer-side execution. No local subprocess.

LocalShellTool is the workhorse. Reach for it unless you specifically need provider-managed isolation and you're on Anthropic or OpenAI.

60-second recipe — LocalShellTool

python
from autogen.beta import Agent
from autogen.beta.config import AnthropicConfig
from autogen.beta.tools import LocalShellTool

agent = Agent(
    "coder",
    "You write and run Python code.",
    config=AnthropicConfig(model="claude-sonnet-4-6"),
    tools=[LocalShellTool()],
)

reply = await agent.ask("Write a hello world script and run it.")
print(await reply.content())

LocalShellTool is provider-agnostic — swap AnthropicConfig for OpenAIConfig(model="gpt-4.1"), GeminiConfig(model="gemini-2.5-pro"), etc. Make sure you've installed the matching ag2[<provider>] extra and set the matching env var (see ag2-quickstart → Prerequisites).

With no arguments, LocalShellTool creates a temporary working directory (prefixed ag2_shell_) and cleans it up when the process exits. Pass a path to use a specific directory:

python
from pathlib import Path
LocalShellTool("/tmp/my_project")
LocalShellTool(Path("/tmp/my_project"))

When a path is given, the directory is created if it does not exist and is not deleted on exit. Inspect the resolved working directory via tool.workdir.

Sandboxing (LocalShellEnvironment)

For anything beyond a throwaway demo, use LocalShellEnvironment and lock down what the agent can do. Filtering is applied in this order on every call:

  1. allowed — if set, the command must match at least one prefix.
  2. blocked — if set, the command must not match any prefix.
  3. ignore — literal path tokens in the command are checked against gitignore-style patterns; matches return "Access denied: <path>".
  4. Execute via subprocess.run.
python
from autogen.beta.tools import LocalShellTool
from autogen.beta.tools.shell import LocalShellEnvironment

sh = LocalShellTool(
    LocalShellEnvironment(
        path="/tmp/my_project",
        allowed=["python", "uv run", "git"],
        blocked=["rm -rf", "curl", "wget"],
        ignore=["**/.env", "*.key", "secrets/**"],
        timeout=30,
        max_output=50_000,
    )
)
Read-only mode

For inspection-only access (cat, head, tail, ls, grep, find, git log, git diff, git status, …):

python
from autogen.beta.tools import LocalShellTool
from autogen.beta.tools.shell import LocalShellEnvironment

sh = LocalShellTool(LocalShellEnvironment(path="/my/codebase", readonly=True))

Pass an explicit allowed=[...] to override the built-in read-only allowlist.

LocalShellEnvironment parameter reference
ParameterDefaultDescription
pathNoneWorking dir. None → temp dir, deleted on exit
cleanupNoneNone → auto (True when path=None, False otherwise). Deletes path on process exit
allowedNoneWhitelist of command prefixes. None → all commands allowed
blockedNoneBlacklist of command prefixes
ignoreNoneGitignore-style path patterns; matches block the command
readonlyFalseWhen True and allowed unset, restricts to a built-in read-only list
envNoneExtra env vars merged into each command
timeout60Per-command timeout in seconds (returns "Command timed out after Ns [exit code: 124]")
max_output100_000Max characters returned (truncated output is suffixed [truncated: …])

Stateful multi-turn workspaces

Files persist in workdir across ask() calls, so the agent can build on prior work:

python
from autogen.beta.tools import LocalShellTool
from autogen.beta.tools.shell import LocalShellEnvironment

sh = LocalShellTool(LocalShellEnvironment(path="/tmp/counter_demo"))
agent = Agent("coder", "You manage files.", config=config, tools=[sh])

reply1 = await agent.ask("Create counter.txt with value 0")
reply2 = await reply1.ask("Increment the counter by 1")
reply3 = await reply2.ask("Read the counter and tell me the value")
Show full SKILL.md (258 more words)Show less

Provider-native ShellTool (Anthropic / OpenAI)

python
from autogen.beta.tools import ShellTool

agent = Agent("devops", config=AnthropicConfig(model="claude-sonnet-4-6"), tools=[ShellTool()])

OpenAI lets you configure the execution environment:

python
from autogen.beta.config import OpenAIResponsesConfig
from autogen.beta.tools import ShellTool
from autogen.beta.tools.builtin.shell import ContainerAutoEnvironment, NetworkPolicy

agent = Agent(
    "devops",
    config=OpenAIResponsesConfig(model="gpt-4.1"),
    tools=[
        ShellTool(
            environment=ContainerAutoEnvironment(
                network_policy=NetworkPolicy(allowed_domains=["pypi.org"]),
            ),
        ),
    ],
)

Environment options:

EnvironmentDescription
ContainerAutoEnvironmentProvider-managed container with optional network policy
ContainerReferenceEnvironmentReference an existing container by ID

ShellTool is not supported on Gemini — the request will raise UnsupportedToolError.

LocalShellTool vs ShellTool

LocalShellToolShellTool
ExecutionClient-side subprocessProvider-side container
Provider supportAny providerAnthropic, OpenAI
Environment controlFull (allowed, blocked, ignore, readonly, …)Limited (provider-dependent)
Local FS accessYes (you choose what's exposed)No
Network controlVia blocked / allowed patternsOpenAI: NetworkPolicy
Importfrom autogen.beta.tools import LocalShellTool (env: from autogen.beta.tools.shell import LocalShellEnvironment)from autogen.beta.tools import ShellTool

Going deeper

  • website/docs/beta/tools/local_shell.mdx — full LocalShellTool reference, command-filtering semantics.
  • website/docs/beta/tools/builtin_tools.mdx#shell — provider-native ShellTool setup and environment configs.
  • For human-approval gating before each shell call, layer approval_required() middleware (see ag2-hitl).

Common pitfalls

  • Forgetting sandboxing in production — LocalShellTool() with no environment runs anything anywhere with a 60s timeout. Set allowed, blocked, or readonly for any non-trivial use.
  • ignore only checks literal paths in the command string — variable substitution, command substitution (`cat secrets.key`), and dynamic glob expansion are not inspected. Layer in blocked=["cat", "less"] if you also want to block readers.
  • Trying to use ShellTool on Gemini — unsupported, will raise. Use LocalShellTool instead.
  • Using a hardcoded path that another process is also touching — multiple agents sharing /tmp/my_project will race. Use tempfile.mkdtemp(prefix="...") for parallel runs.
  • Expecting ShellTool to access local files — it doesn't; it runs in the provider's container. Use LocalShellTool for anything on your filesystem.
  • Trusting the LLM with shell access — even sandboxed, write prompts that scope what's allowed and consider pairing with approval_required() for destructive operations.

© ag2ai, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/ag2-shell-tool of ag2ai/build-with-ag2.

Open the folder on GitHubat commit 29eeac3

Compare with similar skills

Ag2 Shell Tool next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ag2 Shell Tool compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ag2 Shell Tool this skillag2ai/build-with-ag2252—~2kAutomated safety check: NotesApache-2.0
Open Code Review CLIalibaba/open-code-review44k—~3.1kAutomated safety check: PassApache-2.0
Codexskills-directory/skill-codex1.5k3 repos~1.8kAutomated safety check: PassMIT
Changeset Validationopenai/openai-agents-js3.9k—~607Automated safety check: PassMIT
Openai Security Ownership Maptrailofbits/skills-curated5125 repos~2.2kAutomated safety check: NotesCC-BY-SA-4.0
Pulse Releasequnqin24/Pulse516—~1.3kAutomated safety check: PassApache-2.0

Similar skills

  • Open Code Review CLI

    alibaba/open-code-review

    Runs the ocr command-line tool to review Git changes, a commit or a branch comparison with an AI model, returning line-level comments and optionally applying fixes.

    44k GitHub stars~3.1k tokensUpdated 3 days ago
    DevelopmentAuto-check passed

  • Codex

    skills-directory/skill-codex

    A skill your agent uses when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing

    1.5k GitHub starsUsed in 3 repos~1.8k tokens
    DevelopmentAuto-check passed

  • Changeset Validation

    openai/openai-agents-js

    Official

    Validate changesets in openai-agents-js using LLM judgment against git diffs (including uncommitted local changes).

    3.9k GitHub stars~607 tokensUpdated today
    DevelopmentAuto-check passed

  • Openai Security Ownership Map

    trailofbits/skills-curated

    Official

    Analyze git repositories to build a security ownership topology (people-to-file), compute bus factor and sensitive-code ownership, and export CSV/JSON for graph databases and visualization.

    512 GitHub starsUsed in 5 repos~2.2k tokens
    DevelopmentAuto-check: notes

  • Pulse Release

    qunqin24/Pulse

    Release a new Pulse version end to end — checks, bilingual CHANGELOG entry, VERSION, tag, the release workflow, syncing main, and the issue replies that go with it.

    516 GitHub stars~1.3k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Pypi Release

    alchemiststudiosDOTai/tunacode

    This skill should be used when releasing tunacode-cli to PyPI.

    125 GitHub stars~2.2k tokensUpdated 3 days ago
    DevelopmentAuto-check passed

More from ag2ai/build-with-ag2

All 16 skills in this repo

  • Ag2 Add Custom Tool

    ag2ai/build-with-ag2

    Add a custom Python tool to an AG2 beta Agent using the @tool decorator.

    252 GitHub stars~1.9k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Middleware

    ag2ai/build-with-ag2

    Intercept the AG2 beta agent loop with BaseMiddleware — wrap full turns (onturn), each LLM call (onllmcall), each tool execution (ontoolexecution), or each human-input request (onhumaninput).

    252 GitHub stars~1.9k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Use Builtin Tools

    ag2ai/build-with-ag2

    Wire AG2 beta's shipped tools into an Agent — both provider-native server-side tools (web search, web fetch, code execution, MCP, image generation, memory) and locally-executed common toolkits…

    252 GitHub stars~1.3k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Knowledge And Memory

    ag2ai/build-with-ag2

    Persist agent state across runs, shape what the LLM sees per turn, and cap history to fit a context window.

    252 GitHub stars~2.9k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Observers And Alerts

    ag2ai/build-with-ag2

    Monitor an AG2 beta agent's stream — log events, detect repeated tool calls, track token spend, build trigger-driven observers, route observer alerts to the model, and halt on FATAL conditions.

    252 GitHub stars~2.5k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Quickstart

    ag2ai/build-with-ag2

    Build a minimal AG2 beta Agent end to end — pick a model provider, set a prompt, call agent.ask(), then continue the conversation with reply.ask() (multi-turn).

    252 GitHub stars~1.7k tokensUpdated 1 mo ago
    Auto-check: notes

Works with

Categories

Questions about Ag2 Shell Tool

What does Ag2 Shell Tool do?

Give an AG2 beta Agent the ability to run shell commands. An agent skill from ag2ai/build-with-ag2. Ag2 Shell Tool is an agent skill from ag2ai/build-with-ag2. Give an AG2 beta Agent the ability to run shell commands.

When should I use Ag2 Shell Tool?

Ag2 Shell Tool fits situations like: the user wants the Agent to execute commands; build/test code; operate on a workspace.

How do I install Ag2 Shell Tool in Claude Code?

Run `npx skills add ag2ai/build-with-ag2 --skill ag2-shell-tool -a claude-code`. Or copy the skill folder (.agents/skills/ag2-shell-tool in ag2ai/build-with-ag2) into .claude/skills/ag2-shell-tool in your project. Claude Code loads it when a task matches its description.

How do I install Ag2 Shell Tool in Codex?

Run `npx skills add ag2ai/build-with-ag2 --skill ag2-shell-tool -a codex`. Or copy the skill folder (.agents/skills/ag2-shell-tool in ag2ai/build-with-ag2) into .agents/skills/ag2-shell-tool in your project. Codex loads it when a task matches its description.

Can I use Ag2 Shell Tool in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ag2ai/build-with-ag2 --skill ag2-shell-tool -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ag2-shell-tool, .gemini/skills/ag2-shell-tool, .github/skills/ag2-shell-tool and .opencode/skills/ag2-shell-tool in your project.

What does Ag2 Shell Tool need to run?

Going by SKILL.md and its folder, Ag2 Shell Tool needs the command-line tools its instructions call (git). Our summary lists: Python 3.

Does Ag2 Shell Tool access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Ag2 Shell Tool safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Ag2 Shell Tool use?

Ag2 Shell Tool is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ag2 Shell Tool use?

About 2k tokens (SKILL.md is roughly 8.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Ag2 Shell Tool?

Skills that share tags, products or a category with Ag2 Shell Tool: Open Code Review CLI (alibaba/open-code-review, 44k stars), Codex (skills-directory/skill-codex, 1.5k stars), Changeset Validation (openai/openai-agents-js, 3.9k stars) and Openai Security Ownership Map (trailofbits/skills-curated, 512 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ag2 Shell Tool?

ag2ai (a GitHub organization) maintains it in ag2ai/build-with-ag2, which has 252 GitHub stars. The repository holds 16 skills in this directory. The repository was last updated on September 6, 2026.

Source: ag2ai/build-with-ag2 on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.