Merge pull request #24291 from dvdksn/add-agent-instructions

add agent instructions

.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 <number> --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-<number>-<short-description> 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 <file>
+```
+
+#### 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 <specific-files>
+git commit -m "$(cat <<'EOF'
+<Short summary of fix>
+
+<Brief explanation of why>
+
+Closes #<issue-number>
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+```
+
+#### g. Push and create PR
+
+```bash
+git push -u origin fix/issue-<number>-<short-description>
+```
+
+Then create the PR:
+
+```bash
+gh pr create --repo docker/docs \
+  --title "<Short summary matching commit>" \
+  --body "$(cat <<'EOF'
+## Summary
+
+- <1-3 bullet points describing what changed and why>
+
+Closes #<issue-number>
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+#### h. Label and assign reviewers
+
+```bash
+gh pr edit <pr-number> --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

.gitignore

@@ -17,4 +17,3 @@ cagent
 .cagent
 .pr-body.md
 .validation.log
-.claude

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 <file>        # 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/`

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md