From 12a1a49c787ba8fe5aa100586104b095b60977e3 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 6 Mar 2026 14:59:12 +0100 Subject: [PATCH 1/4] chore: add AGENTS.md file Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- AGENTS.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..97decee378 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,75 @@ +# AGENTS.md + +Instructions for AI agents working on the Docker documentation +repository. This site builds https://docs.docker.com/ using Hugo. + +## Project structure + +``` +content/ # Documentation source (Markdown + Hugo front matter) +├── manuals/ # Product docs (Engine, Desktop, Hub, etc.) +├── guides/ # Task-oriented guides +├── reference/ # API and CLI reference +└── includes/ # Reusable snippets +layouts/ # Hugo templates and shortcodes +data/ # YAML data files (CLI reference, etc.) +assets/ # CSS (Tailwind v4) and JS (Alpine.js) +static/ # Images, fonts +_vendor/ # Vendored Hugo modules (read-only) +``` + +The `/manuals` prefix is stripped from published URLs: +`content/manuals/desktop/` → `/desktop/` on the live site. + +## Writing guidelines + +Read and follow [STYLE.md](STYLE.md) and [COMPONENTS.md](COMPONENTS.md). +These contain all style rules, shortcode syntax, and front matter +requirements. + +## Vendored content (do not edit) + +Content in `_vendor/` and CLI reference pages generated from +`data/cli/` are vendored from upstream repos. Don't edit these +files — changes must go to the source repository: + +- docker/cli, docker/buildx, docker/compose, docker/model-runner → CLI reference YAML in `data/cli/` +- moby/buildkit → Dockerfile reference in `_vendor/` +- moby/moby → Engine API docs in `_vendor/` + +If a validation failure traces back to vendored content, note the +upstream repo that needs fixing but don't block on it. + +## Commands + +```sh +npx prettier --write # Format before committing +docker buildx bake validate # Run all validation checks +docker buildx bake lint # Markdown linting only +docker buildx bake vale # Style guide checks only +docker buildx bake test # HTML and link checking +``` + +## Verification loop + +1. Make changes +2. Format with prettier +3. Run `docker buildx bake lint vale` +4. Run a full build with `docker buildx bake` + +## Self-improvement + +After every correction or mistake, update this file with a rule to +prevent repeating it. End corrections with: "Now update AGENTS.md so +you don't make that mistake again." + +## Mistakes to avoid + +- Don't use hedge words: "simply", "easily", "just", "seamlessly" +- Don't use meta-commentary: "it's worth noting that...", "it's important to understand that..." +- Don't use "allows you to" or "enables you to" — use "lets you" or rephrase +- Don't use "we" — use "you" or "Docker" +- Don't use "click" — use "select" +- Don't bold product names or for emphasis — only bold UI elements +- Don't use time-relative language: "currently", "new", "recently", "now" +- Don't edit vendored content in `_vendor/` or `data/cli/` From d1e710fe38cdd9889af753a5f389e17bb11abfa7 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 6 Mar 2026 14:59:26 +0100 Subject: [PATCH 2/4] chore: add CLAUDE.md symlink to AGENTS.md Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) create mode 120000 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 453f796ea9ae9f9797fd98800c7a5372fda496c7 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 6 Mar 2026 14:59:48 +0100 Subject: [PATCH 3/4] chore: remove .claude from .gitignore Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 2e4a5afc99..7c45091443 100644 --- a/.gitignore +++ b/.gitignore @@ -17,4 +17,3 @@ cagent .cagent .pr-body.md .validation.log -.claude From 28a8a617b988f07f128077ec91662155fd616670 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 6 Mar 2026 14:59:57 +0100 Subject: [PATCH 4/4] chore: add skill to fix github issues Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .claude/skills/fix-issues/SKILL.md | 143 +++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 .claude/skills/fix-issues/SKILL.md diff --git a/.claude/skills/fix-issues/SKILL.md b/.claude/skills/fix-issues/SKILL.md new file mode 100644 index 0000000000..4354eb67bc --- /dev/null +++ b/.claude/skills/fix-issues/SKILL.md @@ -0,0 +1,143 @@ +--- +name: fix-issues +description: > + Fix one or more GitHub issues by creating branches, writing fixes, and opening PRs. + Use this skill whenever the user provides GitHub issue numbers and wants them fixed, + or says things like "fix issue 1234", "address these issues", "create PRs for issues + 1234 and 5678". Triggers on any request involving GitHub issue numbers paired with + fixing, addressing, resolving, or creating PRs. Also triggers for "fix #1234" shorthand. +--- + +# Fix Issues + +Given one or more GitHub issue numbers from the docker/docs repository, fix each +issue end-to-end: analyze, branch, fix, commit, push, and open a PR. + +## Workflow + +### 1. Fetch all issues in parallel + +Use `gh issue view --repo docker/docs --json title,body,labels` for each +issue number. Launch all fetches in parallel since they're independent. + +### 2. Fix each issue sequentially + +Process each issue one at a time in the main context. Do NOT use background +subagents for this — they can't get interactive Bash permission approval, which +blocks all git operations. Sequential processing in the main context is faster +than agents that stall on permissions. + +For each issue: + +#### a. Analyze + +Read the issue body to understand: +- Which file(s) need changes +- What the problem is +- What the fix should be + +#### b. Create a branch + +```bash +git checkout -b fix/issue-- main +``` + +Use a short kebab-case description derived from the issue title (3-5 words max). + +#### c. Read and fix + +- Read each affected file before editing +- Make the minimal change that addresses the issue +- Don't over-engineer or add unrequested improvements +- Follow the repository's STYLE.md and COMPONENTS.md guidelines + +#### d. Format + +Run prettier on every changed file: + +```bash +npx prettier --write +``` + +#### e. Self-review + +Re-read the changed file to verify: +- The fix addresses the issue correctly +- No unintended changes were introduced +- Formatting looks correct + +#### f. Commit + +Stage only the changed files (not `git add -A`), then commit: + +```bash +git add +git commit -m "$(cat <<'EOF' + + + + +Closes # + +Co-Authored-By: Claude Opus 4.6 +EOF +)" +``` + +#### g. Push and create PR + +```bash +git push -u origin fix/issue-- +``` + +Then create the PR: + +```bash +gh pr create --repo docker/docs \ + --title "" \ + --body "$(cat <<'EOF' +## Summary + +- <1-3 bullet points describing what changed and why> + +Closes # + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +#### h. Label and assign reviewers + +```bash +gh pr edit --repo docker/docs \ + --add-label "status/review" \ + --add-reviewer docker/docs-team +``` + +### 3. Switch back to main + +After all issues are processed: + +```bash +git checkout main +``` + +### 4. Report results + +Present a summary table: + +| Issue | PR | Change | +|-------|-----|--------| +| #N | #M | Brief description | + +## Important notes + +- Always work from `main` as the base for each branch +- Each issue gets its own branch and PR — don't combine issues +- If an issue references a file that doesn't exist, check for renames or + reorganization before giving up (files move around in this repo) +- Validation commands (`docker buildx bake lint vale`) are available but slow; + only run them if the user asks or the changes are complex enough to warrant it +- The `/manuals` prefix is removed from URLs in the live site — keep this in + mind when verifying link paths