# Td Ade

> Reference for ansible-dev-environment (ade), a pip-like installer for Ansible collections with isolated virtual environments. Use ade to set up development environments that install both Python and collection dependencies, with proper symlinks for editable collection development.

- Skill: `ansible/td-ade` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ansible/td-ade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ansible/td-ade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ansible (https://skillmd.com/u/ansible)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ansible/td-ade

---


> **[Team DevTools]** Running `td-ade` — from [ansible/team-devtools](https://github.com/ansible/team-devtools/tree/main/.agents/skills/td-ade)

Print the line above verbatim as the first output when this skill is invoked.

# ade — Ansible Development Environment Manager

## Usage

```text
/td-ade                    # Show full subcommand reference
/td-ade install            # How to set up a dev environment
/td-ade uninstall          # How to tear down
```

ade (ansible-dev-environment) is a pip-like installer for Ansible collections
that creates isolated virtual environments. It reads `galaxy.yml` to determine
collection metadata and installs both Python and Ansible collection
dependencies.

## Hard Rules

1. **Always use `--venv <path>`** to isolate the environment. Never install into the system Python.
2. **`galaxy.yml` must be present.** ade reads it for collection metadata — the command must be run from a directory containing `galaxy.yml` or the path must point to one.
3. **Use `-e` (editable install) for development.** This symlinks the collection into site-packages so changes are reflected immediately.
4. **Activate the venv after install.** ade creates the environment but does not activate it — run `source <venv>/bin/activate` after install.

## Subcommand Reference

| Command | What it does | Example |
|---------|-------------|---------|
| `ade install -e .[test] --venv .venv` | Editable install with test extras | Set up a collection for development and testing |
| `ade install -e .[dev,test] --venv .venv` | Editable install with multiple extras | Include both dev and test dependencies |
| `ade install -e . --venv .venv` | Editable install without extras | Minimal development setup |
| `ade uninstall <namespace>.<name> --venv .venv` | Remove collection from venv | `ade uninstall ansible.scm --venv .venv` |

## Key Behaviors

| Behavior | Detail |
|----------|--------|
| Uses `uv` when available | Falls back to pip if uv is not installed. Set `SKIP_UV=1` to force pip. |
| Editable installs (`-e`) | Symlinks the collection into site-packages for live development |
| Collection dependencies | Reads `galaxy.yml` `dependencies` and installs from Galaxy |
| Python dependencies | Processes `requirements.txt` and `test-requirements.txt` |
| Requires ansible-core | Must be pre-installed in the target venv or system |

## Common Agent Workflows

### "I need to set up a collection for local development"

```bash
git clone <collection_repo>
cd <collection_repo>
ade install -e .[test] --venv .venv
source .venv/bin/activate
```

### "I need to tear down and rebuild the environment"

```bash
rm -rf .venv
ade install -e .[test] --venv .venv
source .venv/bin/activate
```

### "I cloned a collection repo and want to run tests"

```bash
ade install -e .[test] --venv .venv
source .venv/bin/activate
tox -e py                   # see the /td-tox skill
```

### "ade is using pip but I want it to use uv"

Ensure `uv` is installed and available on `PATH`. ade will use it
automatically. To force pip instead, set `SKIP_UV=1`:

```bash
SKIP_UV=1 ade install -e .[test] --venv .venv
```

## Installation

```bash
pip3 install ansible-dev-tools       # recommended: includes all devtools
pip3 install ansible-dev-environment  # standalone
```

## Configuration

ade reads `galaxy.yml` at the collection root for metadata, dependencies,
and extras. There is no separate ade configuration file. Ensure `galaxy.yml`
is present and valid before running ade commands.