Skip to content

Commit d707428

Browse files
leonidgrishenkovleonidgrishenkov
committed
feat(agents): add containers skill
1 parent 5e569e6 commit d707428

2 files changed

Lines changed: 367 additions & 0 deletions

File tree

‎agents/.agents/skills/containers/REFERENCE.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
# Container CLI Reference
2+
3+
## container run
4+
5+
Run a container from an image.
6+
7+
```bash
8+
container run [options] <image> [args...]
9+
```
10+
11+
| Flag | Description |
12+
| ------------------------------------------- | ----------------------------------------- |
13+
| `-d, --detach` | Run in background |
14+
| `--name <name>` | Assign a name (also used as container ID) |
15+
| `-e, --env <key=val>` | Set environment variable |
16+
| `--env-file <path>` | Load env vars from file |
17+
| `-p <host>:<container>` | Publish a port |
18+
| `-v <host>:<container>` | Bind mount (shortcut) |
19+
| `--mount type=bind,source=...,target=...` | Bind mount (explicit) |
20+
| `--mount type=volume,source=...,target=...` | Volume mount |
21+
| `--network <name>` | Attach to a network |
22+
| `-w, --workdir <dir>` | Set working directory |
23+
| `--entrypoint <cmd>` | Override entrypoint |
24+
| `-i, --interactive` | Keep stdin open |
25+
| `-t, --tty` | Allocate a TTY |
26+
| `--init` | Run init as PID 1 |
27+
| `-c, --cpus <n>` | CPU limit |
28+
| `-m, --memory <size>` | Memory limit (e.g. `512M`, `1G`) |
29+
| `--dns <ip>` | Custom DNS server |
30+
| `-l, --label <key=val>` | Add a label |
31+
| `--rm` | Remove container when it exits |
32+
| `-a, --arch <arch>` | Target architecture (default: `arm64`) |
33+
34+
### Examples
35+
36+
```bash
37+
# Interactive shell
38+
container run -it --rm alpine sh
39+
40+
# Background web server with port mapping
41+
container run -d --name web -p 8080:80 nginx
42+
43+
# With env vars and volume
44+
container run -d --name app \
45+
-e DATABASE_URL=postgres://localhost/db \
46+
--mount type=volume,source=appdata,target=/data \
47+
myapp:latest
48+
49+
# With resource limits
50+
container run -d -c 2 -m 1G --name worker myapp:latest
51+
```
52+
53+
## container build
54+
55+
Build an image from a Dockerfile.
56+
57+
```bash
58+
container build [options] [context-dir]
59+
```
60+
61+
| Flag | Description |
62+
| ----------------------- | ------------------------- |
63+
| `-t, --tag <name>` | Tag the image |
64+
| `-f, --file <path>` | Path to Dockerfile |
65+
| `--build-arg <key=val>` | Set build-time variable |
66+
| `--target <stage>` | Target build stage |
67+
| `--no-cache` | Disable layer cache |
68+
| `--platform <os/arch>` | Target platform |
69+
| `--secret <id=key,...>` | Build-time secret |
70+
| `-q, --quiet` | Suppress output |
71+
| `--pull` | Always pull base images |
72+
| `--progress <type>` | `auto`, `plain`, or `tty` |
73+
74+
### Examples
75+
76+
```bash
77+
container build -t myapp:latest .
78+
container build -t myapp:latest -f deploy/Dockerfile .
79+
container build -t myapp:latest --build-arg NODE_ENV=production --target runtime .
80+
```
81+
82+
## container image
83+
84+
Manage local images.
85+
86+
```bash
87+
container image ls # list images
88+
container image pull <image> # pull from registry
89+
container image push <image> # push to registry
90+
container image inspect <image> # inspect image details
91+
container image tag <src> <dst> # tag an image
92+
container image save -o <file.tar> <image> # export to tar
93+
container image load <file.tar> # import from tar
94+
container image rm <image> # delete image
95+
container image prune # remove unused images
96+
```
97+
98+
## container (container management)
99+
100+
```bash
101+
container ls # list running containers
102+
container inspect <id> # detailed container info
103+
container logs [-f] [-n lines] <id> # fetch logs (-f to follow)
104+
container exec [-it] <id> <cmd> # run command in container
105+
container stop <id> # stop container
106+
container start <id> # start a stopped container
107+
container kill <id> # force kill
108+
container rm <id> # remove container
109+
container prune # remove all stopped containers
110+
container stats # resource usage
111+
container cp <id>:<path> <local> # copy from container
112+
container cp <local> <id>:<path> # copy to container
113+
container export -o <file.tar> <id> # export filesystem
114+
```
115+
116+
## container volume
117+
118+
```bash
119+
container volume create <name>
120+
container volume ls
121+
container volume inspect <name>
122+
container volume rm <name>
123+
container volume prune # remove unused volumes
124+
```
125+
126+
## container network
127+
128+
```bash
129+
container network create <name>
130+
container network ls
131+
container network inspect <name>
132+
container network rm <name>
133+
container network prune # remove unused networks
134+
```
135+
136+
## container machine
137+
138+
Manage the VM that runs containers.
139+
140+
```bash
141+
container machine ls
142+
container machine start
143+
container machine stop
144+
```
145+
146+
## container registry
147+
148+
```bash
149+
container registry login <registry>
150+
container registry logout <registry>
151+
```
152+
153+
---
154+
155+
# container-compose Reference
156+
157+
Reads standard Docker Compose YAML files.
158+
159+
```bash
160+
container-compose [options] <command>
161+
```
162+
163+
| Flag | Description |
164+
| ------------------- | ----------------- |
165+
| `-f, --file <path>` | Compose file path |
166+
167+
### Commands
168+
169+
```bash
170+
container-compose up [-d] [--build] # start services
171+
container-compose down # stop and remove services
172+
container-compose build [--no-cache] # build images only
173+
container-compose version # show version
174+
```
175+
176+
### Examples
177+
178+
```bash
179+
# Start all services detached
180+
container-compose up -d
181+
182+
# Rebuild and start
183+
container-compose up -d --build
184+
185+
# Use a specific compose file
186+
container-compose -f docker-compose.dev.yml up -d
187+
188+
# Stop everything
189+
container-compose down
190+
```
191+
192+
### Compose file notes
193+
194+
- Standard Docker Compose syntax is supported (services, volumes, networks, ports, env, etc.).
195+
- `build:` directive works — it delegates to `container build`.
196+
- `volumes:` and `networks:` sections are supported.
197+
198+
---
199+
200+
# crane Reference
201+
202+
`crane` operates directly on OCI registries — no daemon required.
203+
204+
## Image discovery
205+
206+
```bash
207+
crane catalog <registry> # list repos (e.g. crane catalog docker.io/library)
208+
crane ls <repo> # list tags (e.g. crane ls docker.io/library/nginx)
209+
crane ls <repo> -O # list tags, omit sha256-digest tags
210+
```
211+
212+
## Image inspection
213+
214+
```bash
215+
crane digest <image> # get image digest
216+
crane digest <image> --full-ref # full ref by digest
217+
crane manifest <image> # print manifest JSON
218+
crane manifest <image> | jq # pretty-print
219+
crane config <image> # image config (env, entrypoint, cmd, labels)
220+
crane config <image> | jq '.config.Env' # just environment variables
221+
```
222+
223+
## Image transfer
224+
225+
```bash
226+
crane copy <src> <dst> # copy image between registries
227+
crane copy <src> <dst> -a # copy all tags
228+
crane tag <image> <new-tag> # add a tag remotely
229+
crane delete <image> # delete image from registry
230+
```
231+
232+
## Local operations
233+
234+
```bash
235+
crane pull <image> <output.tar> # pull image to local tarball
236+
crane push <input.tar> <image> # push local tarball to registry
237+
crane export <image> <output.tar> # export filesystem as tarball
238+
```
239+
240+
## Image modification
241+
242+
```bash
243+
crane mutate <image> --annotation key=val # add annotation
244+
crane append <image> --new_base <new> -t <out> # rebase onto new base
245+
crane flatten <image> -t <output.tar> # flatten layers
246+
crane validate --tarball <file.tar> # validate image tarball
247+
```
248+
249+
## Registry auth
250+
251+
```bash
252+
crane auth login <registry> -u <user> -p <pass>
253+
crane auth logout <registry>
254+
```
255+
256+
### Examples
257+
258+
```bash
259+
# Find available nginx tags
260+
crane ls docker.io/library/nginx
261+
262+
# Check what env vars the image exposes
263+
crane config docker.io/library/nginx:alpine | jq '.config.Env'
264+
265+
# Pin an image by digest
266+
crane digest docker.io/library/node:20-slim
267+
# → sha256:abc123...
268+
# Use: docker.io/library/node@sha256:abc123...
269+
270+
# Mirror an image to a private registry
271+
crane copy docker.io/library/nginx:latest registry.example.com/nginx:latest
272+
```

‎agents/.agents/skills/containers/SKILL.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
name: containers
3+
description:
4+
Run and manage containers, build images on macOS. Use when the user asks about containers, Dockerfiles, compose files,
5+
container images, registries, or containerized services.
6+
---
7+
8+
# Container
9+
10+
## Key Rules
11+
12+
1. **Prefer `container` over `docker`.** On macOS, use Apple's native [container](https://github.com/apple/container)
13+
CLI instead of Docker engine. It runs containers via Virtualization.framework — no Linux VM overhead.
14+
2. **Prefer `container-compose` over `docker-compose`.** It reads standard Docker Compose files but uses the native
15+
`container` runtime.
16+
3. **Use `crane` for image search and registry operations.** It talks directly to OCI registries without needing a
17+
daemon.
18+
19+
You can use regular `docker` commands when user explicitly asks for it or if there are some issues with `container` CLI.
20+
`docker` or `docker compose` commands are appropriate choice when using remote docker engine via docker context.
21+
22+
## Quick Command Map
23+
24+
| Docker equivalent | Use instead |
25+
| ------------------- | ---------------------------- |
26+
| `docker run` | `container run` |
27+
| `docker build` | `container build` |
28+
| `docker ps` | `container ls` |
29+
| `docker logs` | `container logs` |
30+
| `docker exec` | `container exec` |
31+
| `docker pull/push` | `container image pull/push` |
32+
| `docker compose up` | `container-compose up` |
33+
| `docker search` | `crane catalog` / `crane ls` |
34+
35+
## Common Workflows
36+
37+
### Run a container
38+
39+
```bash
40+
container run -d --name myapp -p 8080:80 nginx
41+
container run -it --rm alpine sh
42+
```
43+
44+
### Build an image
45+
46+
```bash
47+
container build -t myapp:latest .
48+
container build -t myapp:latest -f Dockerfile.prod --no-cache .
49+
```
50+
51+
### Compose services
52+
53+
```bash
54+
container-compose up -d
55+
container-compose down
56+
container-compose -f docker-compose.dev.yml up -d --build
57+
```
58+
59+
### Search / inspect images with crane
60+
61+
```bash
62+
crane catalog docker.io/library # list repos in a registry
63+
crane ls docker.io/library/nginx # list tags for a repo
64+
crane digest nginx:latest # get image digest
65+
crane manifest nginx:latest # inspect manifest
66+
crane config nginx:latest # view image config (env, entrypoint, etc.)
67+
```
68+
69+
### Manage running containers
70+
71+
```bash
72+
container ls # list running containers
73+
container logs -f myapp # follow logs
74+
container exec -it myapp sh # shell into container
75+
container stop myapp # stop
76+
container delete myapp # remove
77+
container prune # remove all stopped containers
78+
```
79+
80+
### Volumes & networks
81+
82+
```bash
83+
container volume create data
84+
container volume ls
85+
container network create mynet
86+
container run --network mynet --name web nginx
87+
```
88+
89+
## Notes
90+
91+
- `container` only supports **Linux** containers (runs via a lightweight VM on macOS).
92+
- Port mapping uses `-p host:container` just like Docker.
93+
- For bind mounts use `--mount type=bind,source=/host/path,target=/container/path`.
94+
- `--init` adds a PID 1 init process — useful for proper signal handling.
95+
- For detailed command reference, see [REFERENCE.md](REFERENCE.md).

0 commit comments

Comments
 (0)