docs-sync

name	docs-sync
description	Use this skill to update the centralized OpenZeppelin docs repo after a smart contracts library changes. Trigger after a contracts release, a merged PR in a contracts library, or any time a docs slice (library + version) needs to be brought back in line with the contracts repo. The skill takes two contract commits (BASE_COMMIT, HEAD_COMMIT) as the source of truth and produces docs edits that follow the Diátaxis framework. Use whenever the user says "sync docs for contracts-sui", "update docs after the contracts PR", "regenerate API reference for v1.x", or "docs-sync".
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
inputs	{"mode":{"type":"choice","prompt":"Run mode. interactive shows structured proposals at each gate and waits for approval; automatic infers from config and runs end-to-end without prompts.","options":["interactive","automatic"],"default":"interactive","required":false},"contracts_repo_path":{"type":"text","prompt":"Absolute filesystem path to the contracts repo (the source of truth). Must be a git repo, must NOT be the same as the docs repo.","required":true},"docs_repo_path":{"type":"text","prompt":"Absolute filesystem path to the docs repo (where edits will land). Leave blank to use the current working directory.","required":false},"base_commit":{"type":"text","prompt":"BASE_COMMIT — git SHA, tag, or ref in the contracts repo marking the START of the diff (typically the previous release tag).","required":true},"head_commit":{"type":"text","prompt":"HEAD_COMMIT — git SHA, tag, or ref in the contracts repo marking the END of the diff (typically the new release tag, or HEAD).","required":true},"library_id":{"type":"text","prompt":"LIBRARY_ID — the docs slice to update (e.g., contracts-sui). Must match a config file at skills/docs-sync/config/libraries/<library_id>.yml.","required":true},"docs_version":{"type":"text","prompt":"DOCS_VERSION — the version directory inside the slice to edit (e.g., 1.x).","required":true},"release_version":{"type":"text","prompt":"RELEASE_VERSION — the contracts release tag this sync targets (e.g., v1.2.0). Used for source-link version pins and release notes.","required":true},"docs_update_scope":{"type":"choice","prompt":"Scope of docs to update. full = everything the matrix requires; api-only = API reference + nav + source links only; guides-only = guides/tutorials/explanations + snippets only.","options":["full","api-only","guides-only"],"default":"full","required":false},"target_audience":{"type":"text","prompt":"TARGET_AUDIENCE override. Leave blank to use the value in the slice config.","required":false},"docs_tone":{"type":"text","prompt":"DOCS_TONE override. Leave blank to use the value in the slice config.","required":false}}

docs-sync

Use this skill when the contracts library has changed and the centralized docs repo needs to be brought back in sync. The skill lives inside the docs repo; the contracts repo is supplied at runtime.

When to use

• A contracts library has merged a PR or cut a release and the docs need updating.
• The user names a docs slice and two commits in the contracts repo.
• The user asks to "sync docs", "update API reference for <LIBRARY_ID>", or "document the changes between commit A and commit B".

Do not trigger this skill for:

• Pure docs cleanup unrelated to contracts changes (use a regular edit).
• Changes that have not yet landed in a commit on the contracts repo.

Inputs

All required inputs are declared in the frontmatter inputs schema and gathered by the harness before the skill body runs. The skill body must not prompt for inputs interactively; if a required input is missing or fails validation, return a clear error message that names the field and let the caller re-invoke.

The full input set is:

Input	Required	Notes
mode	no	interactive (default) or automatic
contracts_repo_path	yes	absolute path; must be a git repo
docs_repo_path	no	defaults to current working directory
base_commit	yes	git SHA / tag / ref in the contracts repo
head_commit	yes	git SHA / tag / ref in the contracts repo
library_id	yes	must have config/libraries/<library_id>.yml
docs_version	yes	e.g. 1.x
release_version	yes	e.g. v1.2.0
docs_update_scope	no	full (default), ,