## Decision and implementation — 2026-09-17 The contributor-facing workflow now lives in the existing [Editing the Handbook guide](https://handbook.gitlab.com/handbook/about/editing-handbook/). We decided to integrate agentic workflows with browser and local editing instead of maintaining a separate agentic-editing tutorial under the development documentation. [Public handbook !21162](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/21162) merged on September 17, 2026, at commit `12cfa1f3ba8963fc7267e7fc51bbd09f9a543bd1`. The MR contains the discussion and decisions behind the final structure. Shared environment setup and maintainer instructions remain canonical in Docsy GitLab, including [!354](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/merge_requests/354), released in [v0.4.6](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/releases/v0.4.6). ## Agreed structure and scope - **Start with the contributor's task.** Separate choosing how to make a change, checking an MR, and choosing an editing environment. Small corrections can use the single-file editor. Agents help with discovery, multi-file work, planning, and failed checks. - **Meet contributors in their tools.** Include GitLab Duo Agentic Chat and Developer Flow, Web IDE, local editors, GitLab Duo CLI, Claude Code, Claude Desktop Chat and Cowork, Glean, and the GitLab Duo Slack app. Keep tool-specific setup linked rather than maintaining exhaustive installation instructions for every client. - **Keep humans responsible.** Contributors provide the intent and source material, review the diff and unclear facts, validate the result, and follow the approval process. Agent access does not replace content ownership or permission to merge. - **Keep prompts short.** Use the repository's AGENTS.md and review instructions for shared conventions. Prompts describe the task, sources, and whether work should remain local or become an MR. - **Make lightweight local editing explicit.** Clone, edit, commit, push, and use CI/CD feedback. Hugo, Docker, and the preview toolchain are optional for this path. - **Offer previews when useful.** Document Docker Compose and GitLab Pages review apps, while linking to native Hugo/Makefile setup and manual Docker alternatives in the shared development docs. - **Consolidate practical edits.** Common tasks live in the main guide; detailed troubleshooting has its own page. The former practical-edits page redirects to the main guide, and old pipeline/link-error anchors are retained for existing MR comments. - **Use screenshots for this iteration.** Current screenshots show individual steps and are easier to replace than recordings when the UI changes. Remove outdated videos and compress image assets while preserving readability. - **Keep skills separate from this guide's acceptance.** The tutorial works without a new editing skill. Focused reusable maintenance and editing workflows remain follow-up work under #37. ## Completed in the implementation - [x] Integrate manual and agentic editing into the main contributor guide. - [x] Add practical prompts and screenshots for the documented tools and tasks. - [x] Explain local file access versus GitLab access through MCP, glab, or the GitLab tool's existing connection. - [x] Document optional Docker Compose previews and the MR's Deploy → View app workflow. - [x] Consolidate common tasks and separate troubleshooting. - [x] Preserve compatibility links and correct the public pipeline-bot and escalation references. - [x] Link shared setup, agent instructions, and skills contribution guidance to Docsy. - [x] Add maintainer CODEOWNERS review for the editing-guide subtree because agentic instructions need testing. - [x] Validate the latest changes with Markdownlint, Vale, script syntax checks, local preview, image-path checks, and the successful MR pipeline. The examples draw on hands-on FY27 usage. Validation of the guide does not establish that every client version, account configuration, and possible agent response has been tested. The original exhaustive client acceptance matrix below is superseded by the decisions above. ## Follow-up - [ ] Confirm the merged guide is available in the production deployment and gather contributor feedback. - [ ] Record unclear steps, unsuccessful workflows, and improvements in [#58 — Agent instructions and skills feedback](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/58). Ask in [handbook Slack](https://gitlab.enterprise.slack.com/archives/C81PT2ALD) for faster help. - [ ] Develop and test focused skills separately in #37. Prioritize recurring contributor problems and maintainer tasks rather than creating a skill for every documented tool. - [ ] Maintain shared instruction and script alignment through #52 and review-instruction improvements through #38. <details> <summary>Original proposal — retained for context, superseded by the decisions above</summary> ## Goal Create a practical development guide for editing the public and internal handbooks with agents. The guide should provide one shared workflow across the GitLab UI, IDEs, CLI tools, and approved MCP clients while keeping human authors responsible for correctness, confidentiality, approvals, and merge decisions. The canonical documentation will live in the `docsy-gitlab` project so both handbook projects can use and maintain it. Related work: - Agent instructions: #36 - Reusable maintenance skills: #37 - Agent-focused code review: #38 ## Plan ### Establish the shared baseline - [ ] Explain how repository-provided `AGENTS.md` instructions guide navigation, editing, validation, and MR preparation. - [ ] Document `CLAUDE.md` as a compatibility pointer rather than a second instruction source. - [ ] Explain the role of `.gitlab/duo/mr-review-instructions.yaml` for review-specific guidance. - [ ] Introduce optional `skills/` workflows without making skills a prerequisite. - [ ] Require repository-pinned tools, existing scripts, and current build instructions. ### Document one common workflow - [ ] Choose the correct handbook repository and confirm public versus internal content boundaries. - [ ] Read project instructions, `CODEOWNERS`, controlled-document metadata, and reusable includes. - [ ] Define the goal, scope, non-goals, and authorized actions. - [ ] Make and validate the smallest useful change. - [ ] Review the complete diff before creating an MR. - [ ] Use the project template, labels, review app, and approval workflow. - [ ] Keep reviewer requests and merge decisions human-controlled. ### Add task-focused examples - [ ] GitLab UI: address code review feedback. - [ ] GitLab UI: investigate and fix a failed pipeline. - [ ] GitLab UI: create an issue or MR from scoped requirements. - [ ] GitLab Duo CLI: inspect, edit, validate, and prepare an MR. - [ ] Visual Studio Code: work from repository context and review inline changes. - [ ] JetBrains IDEs: follow the same workflow with native GitLab integration where supported. - [ ] MCP clients: research handbook context, create issues and MRs, and support local editing workflows. ### Cover MCP configuration and safety - [ ] Explain what the GitLab MCP server exposes to approved clients. - [ ] Add verified setup examples for Claude Desktop, Claude Code, Glean, and other approved clients where documentation is available. - [ ] Document authentication, minimum scopes, read-only connection tests, and controlled write tests. - [ ] Warn against committing tokens or sending internal content to unapproved external services. ### Add reusable guidance - [ ] Provide prompts for research, editing, and review or pipeline feedback. - [ ] Add an agent-generated change review checklist. - [ ] Add troubleshooting for instruction discovery, permissions, MCP authentication, pinned tools, lint differences, and unrelated edits. - [ ] Link current product documentation and representative handbook issues and MRs. ## Proposed page structure 1. Agentic handbook editing 1. What this guide covers 1. Project-provided context 1. Before starting 1. A common editing workflow 1. Use agents from the GitLab UI 1. Use agents in an IDE or CLI 1. Connect external agents with MCP 1. Safe and effective prompts 1. Review agent-generated changes 1. Troubleshooting 1. Resources and examples ## Acceptance criteria - [ ] Add `content/docs/development/agentic-handbook-editing.md` with complete front matter and a usable navigation structure. - [ ] Link the guide from the handbook development landing page. - [ ] Include one verified example for the GitLab UI, CLI, VS Code, JetBrains, and MCP. - [ ] Keep shared workflow guidance in one place instead of duplicating it for every tool. - [ ] Verify product names, UI actions, integration support, and URLs against current documentation. - [ ] Validate the page with Markdownlint, Vale, Hugo, and internal-link checks. - [ ] Confirm the guidance applies to both public and internal handbook repositories. ## Non-goals - Maintaining exhaustive instructions for every AI client. - Replacing the existing Markdown, local development, or MR documentation. - Publishing internal tokens, confidential prompts, or client-specific secrets. - Automating approvals or merges. - Implementing the optional skills tracked in #37. </details>