Skip to content

Commit 8eeed60

Browse files
dvdksndvdksn
authored
Merge pull request #24291 from dvdksn/add-agent-instructions
add agent instructions
2 parents cd91171 + 28a8a61 commit 8eeed60

File tree

4 files changed

+219
-1
lines changed

4 files changed

+219
-1
lines changed

‎.claude/skills/fix-issues/SKILL.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
name: fix-issues
3+
description: >
4+
Fix one or more GitHub issues by creating branches, writing fixes, and opening PRs.
5+
Use this skill whenever the user provides GitHub issue numbers and wants them fixed,
6+
or says things like "fix issue 1234", "address these issues", "create PRs for issues
7+
1234 and 5678". Triggers on any request involving GitHub issue numbers paired with
8+
fixing, addressing, resolving, or creating PRs. Also triggers for "fix #1234" shorthand.
9+
---
10+
11+
# Fix Issues
12+
13+
Given one or more GitHub issue numbers from the docker/docs repository, fix each
14+
issue end-to-end: analyze, branch, fix, commit, push, and open a PR.
15+
16+
## Workflow
17+
18+
### 1. Fetch all issues in parallel
19+
20+
Use `gh issue view <number> --repo docker/docs --json title,body,labels` for each
21+
issue number. Launch all fetches in parallel since they're independent.
22+
23+
### 2. Fix each issue sequentially
24+
25+
Process each issue one at a time in the main context. Do NOT use background
26+
subagents for this — they can't get interactive Bash permission approval, which
27+
blocks all git operations. Sequential processing in the main context is faster
28+
than agents that stall on permissions.
29+
30+
For each issue:
31+
32+
#### a. Analyze
33+
34+
Read the issue body to understand:
35+
- Which file(s) need changes
36+
- What the problem is
37+
- What the fix should be
38+
39+
#### b. Create a branch
40+
41+
```bash
42+
git checkout -b fix/issue-<number>-<short-description> main
43+
```
44+
45+
Use a short kebab-case description derived from the issue title (3-5 words max).
46+
47+
#### c. Read and fix
48+
49+
- Read each affected file before editing
50+
- Make the minimal change that addresses the issue
51+
- Don't over-engineer or add unrequested improvements
52+
- Follow the repository's STYLE.md and COMPONENTS.md guidelines
53+
54+
#### d. Format
55+
56+
Run prettier on every changed file:
57+
58+
```bash
59+
npx prettier --write <file>
60+
```
61+
62+
#### e. Self-review
63+
64+
Re-read the changed file to verify:
65+
- The fix addresses the issue correctly
66+
- No unintended changes were introduced
67+
- Formatting looks correct
68+
69+
#### f. Commit
70+
71+
Stage only the changed files (not `git add -A`), then commit:
72+
73+
```bash
74+
git add <specific-files>
75+
git commit -m "$(cat <<'EOF'
76+
<Short summary of fix>
77+
78+
<Brief explanation of why>
79+
80+
Closes #<issue-number>
81+
82+
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
83+
EOF
84+
)"
85+
```
86+
87+
#### g. Push and create PR
88+
89+
```bash
90+
git push -u origin fix/issue-<number>-<short-description>
91+
```
92+
93+
Then create the PR:
94+
95+
```bash
96+
gh pr create --repo docker/docs \
97+
--title "<Short summary matching commit>" \
98+
--body "$(cat <<'EOF'
99+
## Summary
100+
101+
- <1-3 bullet points describing what changed and why>
102+
103+
Closes #<issue-number>
104+
105+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
106+
EOF
107+
)"
108+
```
109+
110+
#### h. Label and assign reviewers
111+
112+
```bash
113+
gh pr edit <pr-number> --repo docker/docs \
114+
--add-label "status/review" \
115+
--add-reviewer docker/docs-team
116+
```
117+
118+
### 3. Switch back to main
119+
120+
After all issues are processed:
121+
122+
```bash
123+
git checkout main
124+
```
125+
126+
### 4. Report results
127+
128+
Present a summary table:
129+
130+
| Issue | PR | Change |
131+
|-------|-----|--------|
132+
| #N | #M | Brief description |
133+
134+
## Important notes
135+
136+
- Always work from `main` as the base for each branch
137+
- Each issue gets its own branch and PR — don't combine issues
138+
- If an issue references a file that doesn't exist, check for renames or
139+
reorganization before giving up (files move around in this repo)
140+
- Validation commands (`docker buildx bake lint vale`) are available but slow;
141+
only run them if the user asks or the changes are complex enough to warrant it
142+
- The `/manuals` prefix is removed from URLs in the live site — keep this in
143+
mind when verifying link paths

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,3 @@ cagent
1717
.cagent
1818
.pr-body.md
1919
.validation.log
20-
.claude

‎AGENTS.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# AGENTS.md
2+
3+
Instructions for AI agents working on the Docker documentation
4+
repository. This site builds https://docs.docker.com/ using Hugo.
5+
6+
## Project structure
7+
8+
```
9+
content/ # Documentation source (Markdown + Hugo front matter)
10+
├── manuals/ # Product docs (Engine, Desktop, Hub, etc.)
11+
├── guides/ # Task-oriented guides
12+
├── reference/ # API and CLI reference
13+
└── includes/ # Reusable snippets
14+
layouts/ # Hugo templates and shortcodes
15+
data/ # YAML data files (CLI reference, etc.)
16+
assets/ # CSS (Tailwind v4) and JS (Alpine.js)
17+
static/ # Images, fonts
18+
_vendor/ # Vendored Hugo modules (read-only)
19+
```
20+
21+
The `/manuals` prefix is stripped from published URLs:
22+
`content/manuals/desktop/` → `/desktop/` on the live site.
23+
24+
## Writing guidelines
25+
26+
Read and follow [STYLE.md](STYLE.md) and [COMPONENTS.md](COMPONENTS.md).
27+
These contain all style rules, shortcode syntax, and front matter
28+
requirements.
29+
30+
## Vendored content (do not edit)
31+
32+
Content in `_vendor/` and CLI reference pages generated from
33+
`data/cli/` are vendored from upstream repos. Don't edit these
34+
files — changes must go to the source repository:
35+
36+
- docker/cli, docker/buildx, docker/compose, docker/model-runner → CLI reference YAML in `data/cli/`
37+
- moby/buildkit → Dockerfile reference in `_vendor/`
38+
- moby/moby → Engine API docs in `_vendor/`
39+
40+
If a validation failure traces back to vendored content, note the
41+
upstream repo that needs fixing but don't block on it.
42+
43+
## Commands
44+
45+
```sh
46+
npx prettier --write <file> # Format before committing
47+
docker buildx bake validate # Run all validation checks
48+
docker buildx bake lint # Markdown linting only
49+
docker buildx bake vale # Style guide checks only
50+
docker buildx bake test # HTML and link checking
51+
```
52+
53+
## Verification loop
54+
55+
1. Make changes
56+
2. Format with prettier
57+
3. Run `docker buildx bake lint vale`
58+
4. Run a full build with `docker buildx bake`
59+
60+
## Self-improvement
61+
62+
After every correction or mistake, update this file with a rule to
63+
prevent repeating it. End corrections with: "Now update AGENTS.md so
64+
you don't make that mistake again."
65+
66+
## Mistakes to avoid
67+
68+
- Don't use hedge words: "simply", "easily", "just", "seamlessly"
69+
- Don't use meta-commentary: "it's worth noting that...", "it's important to understand that..."
70+
- Don't use "allows you to" or "enables you to" — use "lets you" or rephrase
71+
- Don't use "we" — use "you" or "Docker"
72+
- Don't use "click" — use "select"
73+
- Don't bold product names or for emphasis — only bold UI elements
74+
- Don't use time-relative language: "currently", "new", "recently", "now"
75+
- Don't edit vendored content in `_vendor/` or `data/cli/`

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)