Skip to content

Commit eca01cd

Browse files
ansibuddyansibuddy
committed
chore: sync agent skills from team-devtools
Source: ansible/team-devtools@977709d
1 parent 29f7432 commit eca01cd

32 files changed

Lines changed: 9565 additions & 0 deletions

‎.agents/skills/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,25 @@ Agent skills for development and maintenance workflow automation in Ansible Devt
2828
|-------|---------|-----------|
2929
| `tox` | tox environment reference (lint, test, docs, pkg) | `[environment-name]` |
3030

31+
### Ansible Developer Tools
32+
33+
| Skill | Purpose | Arguments |
34+
|-------|---------|-----------|
35+
| `ansible-creator` | Scaffold collections, playbooks, EEs, plugins | `[subcommand]` |
36+
| `ansible-lint` | Ansible playbook/role/collection linting reference | `[options]` |
37+
| `ade` | Development environment setup with ansible-dev-environment | `[subcommand]` |
38+
3139
## Skill Structure
3240

3341
```text
3442
skills/
3543
├── README.md ← You are here
44+
├── ade/
45+
│ └── SKILL.md
46+
├── ansible-creator/
47+
│ └── SKILL.md
48+
├── ansible-lint/
49+
│ └── SKILL.md
3650
├── diagnose-ci/
3751
│ └── SKILL.md
3852
├── fix-bot-prs/

‎.agents/skills/ade/SKILL.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
name: ade
3+
description: >
4+
Reference for ansible-dev-environment (ade), a pip-like installer for
5+
Ansible collections with isolated virtual environments. Use ade to set up
6+
development environments that install both Python and collection
7+
dependencies, with proper symlinks for editable collection development.
8+
argument-hint: "[subcommand]"
9+
user-invocable: true
10+
metadata:
11+
author: Ansible DevTools Team
12+
version: 1.0.0
13+
---
14+
15+
# ade — Ansible Development Environment Manager
16+
17+
## Usage
18+
19+
```text
20+
/ade # Show full subcommand reference
21+
/ade install # How to set up a dev environment
22+
/ade uninstall # How to tear down
23+
```
24+
25+
ade (ansible-dev-environment) is a pip-like installer for Ansible collections
26+
that creates isolated virtual environments. It reads `galaxy.yml` to determine
27+
collection metadata and installs both Python and Ansible collection
28+
dependencies.
29+
30+
## Hard Rules
31+
32+
1. **Always use `--venv <path>`** to isolate the environment. Never install into the system Python.
33+
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.
34+
3. **Use `-e` (editable install) for development.** This symlinks the collection into site-packages so changes are reflected immediately.
35+
4. **Activate the venv after install.** ade creates the environment but does not activate it — run `source <venv>/bin/activate` after install.
36+
37+
## Subcommand Reference
38+
39+
| Command | What it does | Example |
40+
|---------|-------------|---------|
41+
| `ade install -e .[test] --venv .venv` | Editable install with test extras | Set up a collection for development and testing |
42+
| `ade install -e .[dev,test] --venv .venv` | Editable install with multiple extras | Include both dev and test dependencies |
43+
| `ade install -e . --venv .venv` | Editable install without extras | Minimal development setup |
44+
| `ade uninstall <namespace>.<name> --venv .venv` | Remove collection from venv | `ade uninstall ansible.scm --venv .venv` |
45+
46+
## Key Behaviors
47+
48+
| Behavior | Detail |
49+
|----------|--------|
50+
| Uses `uv` when available | Falls back to pip if uv is not installed. Set `SKIP_UV=1` to force pip. |
51+
| Editable installs (`-e`) | Symlinks the collection into site-packages for live development |
52+
| Collection dependencies | Reads `galaxy.yml` `dependencies` and installs from Galaxy |
53+
| Python dependencies | Processes `requirements.txt` and `test-requirements.txt` |
54+
| Requires ansible-core | Must be pre-installed in the target venv or system |
55+
56+
## Common Agent Workflows
57+
58+
### "I need to set up a collection for local development"
59+
60+
```bash
61+
git clone <collection_repo>
62+
cd <collection_repo>
63+
ade install -e .[test] --venv .venv
64+
source .venv/bin/activate
65+
```
66+
67+
### "I need to tear down and rebuild the environment"
68+
69+
```bash
70+
rm -rf .venv
71+
ade install -e .[test] --venv .venv
72+
source .venv/bin/activate
73+
```
74+
75+
### "I cloned a collection repo and want to run tests"
76+
77+
```bash
78+
ade install -e .[test] --venv .venv
79+
source .venv/bin/activate
80+
tox -e py # see the /tox skill
81+
```
82+
83+
### "ade is using pip but I want it to use uv"
84+
85+
Ensure `uv` is installed and available on `PATH`. ade will use it
86+
automatically. To force pip instead, set `SKIP_UV=1`:
87+
88+
```bash
89+
SKIP_UV=1 ade install -e .[test] --venv .venv
90+
```
91+
92+
## Installation
93+
94+
```bash
95+
pip3 install ansible-dev-tools # recommended: includes all devtools
96+
pip3 install ansible-dev-environment # standalone
97+
```
98+
99+
## Configuration
100+
101+
ade reads `galaxy.yml` at the collection root for metadata, dependencies,
102+
and extras. There is no separate ade configuration file. Ensure `galaxy.yml`
103+
is present and valid before running ade commands.

‎.agents/skills/ansible-creator/SKILL.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
name: ansible-creator
3+
description: >
4+
Reference for scaffolding Ansible content with ansible-creator.
5+
Use ansible-creator to initialize new collections, playbook projects,
6+
and execution environments, or to add plugins and resources to existing
7+
projects. This skill is the canonical lookup table for which subcommand
8+
and flags to use.
9+
argument-hint: "[subcommand]"
10+
user-invocable: true
11+
metadata:
12+
author: Ansible DevTools Team
13+
version: 1.0.0
14+
---
15+
16+
# ansible-creator — Ansible Content Scaffolding Tool
17+
18+
## Usage
19+
20+
```text
21+
/ansible-creator # Show full subcommand reference
22+
/ansible-creator init # How to scaffold new projects
23+
/ansible-creator add # How to add plugins/resources
24+
```
25+
26+
ansible-creator scaffolds Ansible content projects. Use `init` to create new
27+
projects from scratch and `add` to extend existing ones with plugins or
28+
resources.
29+
30+
## Hard Rules
31+
32+
1. **Always use `namespace.name` format** for `init collection` and `init playbook`.
33+
2. **Never scaffold into a non-empty directory** without `-o/--overwrite` — the command will fail.
34+
3. **After scaffolding, run `tox -e lint`** to verify the generated content passes quality gates. See the `/tox` skill.
35+
4. **`add plugin` requires the collection root** — the path must point to the directory containing `galaxy.yml`.
36+
37+
## Subcommand Reference
38+
39+
### Initialize projects
40+
41+
| Command | What it creates | Example |
42+
|---------|----------------|---------|
43+
| `ansible-creator init collection <ns>.<name> <path>` | Full collection skeleton (plugins, roles, tests, docs, galaxy.yml) | `ansible-creator init collection myorg.network ~/collections/ansible_collections` |
44+
| `ansible-creator init playbook <ns>.<name> <path>` | Playbook project structure | `ansible-creator init playbook myorg.deploy ~/projects/deploy` |
45+
| `ansible-creator init execution_env <path>` | Execution environment definition files | `ansible-creator init execution_env ~/ee-project` |
46+
47+
### Add to existing projects
48+
49+
#### Resources
50+
51+
| Command | What it adds |
52+
|---------|-------------|
53+
| `ansible-creator add resource devcontainer <path>` | Dev container configuration |
54+
| `ansible-creator add resource devfile <path>` | Devfile for cloud IDEs |
55+
| `ansible-creator add resource execution-environment <path>` | Sample EE YAML template |
56+
| `ansible-creator add resource play-argspec <path>` | Playbook argument specification examples |
57+
| `ansible-creator add resource role <path>` | New role skeleton |
58+
59+
#### Plugins
60+
61+
| Command | What it adds | Example |
62+
|---------|-------------|---------|
63+
| `ansible-creator add plugin action <name> <coll-path>` | Action plugin | `ansible-creator add plugin action my_action .` |
64+
| `ansible-creator add plugin filter <name> <coll-path>` | Filter plugin | `ansible-creator add plugin filter my_filter .` |
65+
| `ansible-creator add plugin lookup <name> <coll-path>` | Lookup plugin | `ansible-creator add plugin lookup my_lookup .` |
66+
| `ansible-creator add plugin module <name> <coll-path>` | Module plugin | `ansible-creator add plugin module my_module .` |
67+
| `ansible-creator add plugin test <name> <coll-path>` | Test plugin | `ansible-creator add plugin test my_test .` |
68+
69+
## Common Flags
70+
71+
| Flag | Purpose |
72+
|------|---------|
73+
| `-o` / `--overwrite` | Overwrite existing files |
74+
| `-no` / `--no-overwrite` | Fail if destination exists (default) |
75+
| `--json` | Output in JSON format |
76+
| `-v` | Increase verbosity (up to `-vvv`) |
77+
| `--log-file <path>` | Write log to file |
78+
| `--na` / `--no-ansi` | Disable colored output |
79+
| `--ll` / `--log-level` | Set logging level (debug, info, warning, error, critical) |
80+
81+
## Common Agent Workflows
82+
83+
### "I need to start a new Ansible collection"
84+
85+
```bash
86+
ansible-creator init collection myorg.mynetwork ~/collections/ansible_collections
87+
cd ~/collections/ansible_collections/myorg/mynetwork
88+
tox -e lint
89+
```
90+
91+
### "I need to add a module plugin to an existing collection"
92+
93+
```bash
94+
cd /path/to/collection # must contain galaxy.yml
95+
ansible-creator add plugin module my_new_module .
96+
```
97+
98+
### "I need to scaffold an execution environment"
99+
100+
```bash
101+
ansible-creator init execution_env ~/ee-project
102+
```
103+
104+
### "The target directory already has files"
105+
106+
Use `--overwrite` to replace existing files, or choose a clean path:
107+
108+
```bash
109+
ansible-creator init collection myorg.mynetwork ~/collections/ansible_collections --overwrite
110+
```
111+
112+
## Installation
113+
114+
```bash
115+
pip3 install ansible-dev-tools # recommended: includes all devtools
116+
pip3 install ansible-creator # standalone
117+
```
118+
119+
## Configuration
120+
121+
ansible-creator does not use a configuration file. All options are passed as
122+
CLI flags. Scaffolded projects may include their own `pyproject.toml`,
123+
`galaxy.yml`, and `tox.ini` for downstream configuration.

0 commit comments

Comments
 (0)