[DOCS] Add a skill for the spec sync and regeneration pipeline

[chandrasekharan-zipstack]

What

Adds .claude/skills/spec-upgrade/SKILL.md — the ordered sequence for picking up a new backend spec, for a future maintainer or agent with no prior context.

Nothing notifies this repo when specs/docstudio-oss.json moves in the backend, and the upgrade that follows is ordered:

1. copy the spec byte-for-byte from the backend commit
2. move SPEC_SOURCE in tools/gen_sdk.sh in the same commit — without it, a stale copy and a current one both report clean
3. ./tools/gen_sdk.sh
4. review with git add -N first, so a newly generated file counts
5. expose anything new through client.py, never the generated tree
6. pytest, leaving the tests/baseline/ parity reference where it is

Plus the two rules a newcomer gets wrong: the generated tree is never hand-edited, and __version__ is the last released version that main.yml bumps at dispatch — not something a PR moves.

Why

The pipeline is real and undocumented in-repo. It points at the existing scripts and gates rather than restating them, and carries no version numbers, dates or codenames, so it should not go stale.

Notes

Docs only — no code, no CI changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CSm32dsxD56PkKENgav3Mn

[greptile-apps]

Greptile Summary

Adds an in-repository skill documenting the ordered OpenAPI specification synchronization and SDK regeneration process.

• Documents the authoritative spec, generator, handwritten facade, drift checks, tests, and release workflow.
• Requires both a diff summary and full generated diff so maintainers can inspect API-level changes.
• Covers major, minor, and patch release decisions while preserving the workflow-managed version.

Confidence Score: 5/5

The documentation-only PR appears safe to merge, with both previous findings fully addressed and no new actionable issues identified.

The updated instructions now expose the complete generated diff and document the supported major-version path for breaking API changes. Both previous threads are resolved, and the current guidance is consistent with the repository’s release workflow.

Important Files Changed

Filename	Overview
.claude/skills/spec-upgrade/SKILL.md	Documents the complete spec-upgrade pipeline; the latest changes fully address both previous review findings.

_{Reviews (2): Last reviewed commit: "docs: show the full generated diff, and ..." | Re-trigger Greptile}