Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

docs-restructure

/docs-restructure

Przebudowuje dokumentację rozłożoną na kilka stron: dzieli zbyt długie strony, przenosi sekcje, wycofuje strony i usuwa podwójne opisy tego samego tematu.

Repozytorium
docs ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Przebudowuje dokumentację rozłożoną na kilka stron: dzieli zbyt długie strony, przenosi sekcje, wycofuje strony i usuwa podwójne opisy tego samego tematu.

Oryginalny opis (EN)

Restructure documentation that spans several pages. Covers splitting a page that has grown too long, moving sections between pages, retiring a page, and fixing a topic documented in two places at once. Use when asked to streamline, simplify, consolidate, or reorganize docs, or when a page review keeps producing edits without the page getting shorter.

Jak działa

  1. Step 1. Establish the page family
  2. Step 2. Build a duplication map before writing anything
  3. Step 3. Assign one home per topic
  4. Step 4. Cut, do not relocate
  5. Step 5. Mechanics
  6. Step 6. Verify
  7. Step 7. Report what moved
  8. Scope
  9. Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 154 linii, 1 049 słów
Podgląd SKILL.md
---
name: docs-restructure
description: Restructure documentation that spans several pages. Covers splitting a page that has grown too long, moving sections between pages, retiring a page, and fixing a topic documented in two places at once. Use when asked to streamline, simplify, consolidate, or reorganize docs, or when a page review keeps producing edits without the page getting shorter.
---

# Restructure docs across pages

The failure this skill prevents: an agent asked to "streamline this page" reorders
its sections, collapses them into accordions, retitles them, and tabulates them,
thirty times over, while the page gets longer. The page was never the problem.
Three of its sections already existed on sibling pages.

Single-page skills cannot see that. `add-docs-page` owns one page's lifecycle and
`docs-edit` owns one page's diff. This skill owns the question they cannot ask:
**is this content on the right page at all?**

`AGENTS.md` holds the navigation map, the style guide, and the frontmatter rules.
This skill covers the procedure around them and does not repeat them.

## Step 1. Establish the page family

A page almost never lives alone. Find its siblings before reading it closely:

```bash
ls src/langsmith/llm-gateway*.mdx          # a flat-file family
ls src/oss/deepagents/                     # a directory family
grep -n '"langsmith/llm-gateway' src/docs.json   # what the nav groups together
```

The nav grouping is the better signal when the two disagree: pages a reader
moves between are the pages whose content can be confused.

Then list every heading in the family, so you are working from the whole shape
rather than one file:

```bash
grep -n '^## ' src/langsmith/llm-gateway*.mdx
```

## Step 2. Build a duplication map before writing anything

This is the step that does the work. For each H2 in the page you were asked to
fix, search the rest of the family for the same content:

```bash
grep -rn 'LANGSMITH_GATEWAY' src/langsmith/ --include=*.mdx
grep -rn 'Use a regional gateway' src/ --include=*.mdx
```

Search for the distinctive noun, env var, or endpoint in the section, not for
its heading. Duplicated content is usually retitled, which is why heading
searches miss it.

Record for each section: **does this topic already live somewhere else, and
where?** Two copies that have drifted apart are the strongest finding available.
It means no page owns the topic, so both copies are edited independently and
readers get contradictions. In one real case the quickstart claimed TypeScript
support for three providers while the sibling page said "Python only."

Report the map before editing anything. "Three of these six sections duplicate
`llm-gateway-api-formats`" is the finding. The restructure is downstream of it.

## Step 3. Assign one home per topic

For each topic in the map, pick the single page that should own it:

- **Prefer a page that already exists.** A new page is warranted when the topic
  has no home and does not fit an existing one, not when it merely needs
  somewhere to go.
- **Prefer the page a reader would search for**, not the page the content
  happens to sit on.
- **Keep the most-linked URL.** Check before choosing, because inbound links
  decide which file survives a merge of two pages:

  ```bash
  grep -rn '(/langsmith/llm-gateway)' src/ --include=*.mdx | wc -l
  ```

  Folding content *into* the well-linked page and retiring the other one is
  usually cheaper than the reverse.

## Step 4. Cut, do not relocate

A section that duplicates a sibling gets **deleted** and replaced with one
sentence pointing at the owner. It does not get moved, collapsed into an
accordion, or shortened in place. An accordion still costs the reader the
decision of whether to open it.

Content that has no home yet moves. Content that has one is already written.

When you delete a section whose facts differ from the sibling's, the difference
is a bug in one of them. Resolve it against the source before deleting, or you
silently pick a winner. See `docs-edit` for the verification procedure.

## Step 5. Mechanics

Retiring, renaming, or creating a page means navigation entries, redirects, and
inbound links. `add-docs-page` covers all of it, including the anchor-stability
and snippet traps. Follow it rather than improvising here.

Two additional things a restructure breaks that a single-page edit does not:

- **Section anchors other pages link to.** Moving a section moves its anchor.
  Grep for `#the-anchor` across `src/` before the move and repoint every hit. A
  `<Step>` or `<Accordion>` can carry an explicit `id` to preserve a landing
  spot that is no longer a heading.
- **Cross-page pointers that now point at the wrong page.** After moving a
  topic, the sibling pages that used to reference its old location need
  repointing, not just the page you edited.

## Step 6. Verify

```bash
make lint_prose FILES="<changed files>"
make build
make broken-links-with-anchors
python3 scripts/check_removed_pages_redirects.py --base-ref origin/main src/docs.json
```

Read `broken-links-with-anchors` by skipping to the `⎿` lines; those are the
only real failures. Compare the count against the same command on `origin/main`
so a pre-existing baseline is not read as a regression.

Then review the prose with the `docs-review` skill, scoped to the files this
pass changed.

## Step 7. Report what moved

State, per page, what was **deleted**, what **moved**, and what was **added**,
with before and after line counts. A restructure that cannot show a page getting
shorter has not restructured anything, and the line counts are what show the
reviewer whether it did.

Name what you deleted rather than only what you wrote. A reviewer who asked for
a shorter page needs to see the cuts to agree with them.

## Scope

Stay inside the page family named in the request. A restructure surfaces
adjacent problems: stale model IDs, legacy version numbers, and the same
duplication one directory over. Report them, and **ask before widening the
sweep.** Fixing sixteen instances across a page family is a reasonable follow-on
inside one pull request. Fixing six hundred across the corpus is a separate pull
request and probably a tracked issue, because some instances are deliberate and
some live in generated files.

## Checklist

- [ ] Page family established from `src/docs.json`, not guessed from filenames.
- [ ] Duplication map built and reported before any edit.
- [ ] One owner chosen per topic; most-linked URL identified before merging pages.
- [ ] Duplicated sections deleted and replaced with a pointer, not relocated.
- [ ] Conflicting facts between copies resolved against source, not by picking one.
- [ ] Redirects, nav entries, inbound links, and section anchors all updated.
- [ ] Verification commands run, `⎿` count compared against `origin/main`.
- [ ] Report gives per-page before and after line counts.
- [ ] Anything outside the page family reported, not swept, unless asked.

Wersje

W bazie nie ma innych skilli o nazwie docs-restructure.

Migawka bazy z 13.11.2026 · wersja paczki 9955668df210 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90edit-the-docs
    Przebudowuje, porządkuje i poprawia istniejące strony dokumentacji Supabase w apps/docs: klarowność, tekst łączący, grupowanie sekcji, zwięzłość i podział zmian na kilka PR-ów.
  • 100docs-writing
    Pisze, przepisuje i sprawdza dokumentację według typów Diátaxis oraz szkicuje stronę funkcji lub diagram, ale nie dokumentuje decyzji architektonicznych.
  • 100docs-page-style
    Określa styl i strukturę stron dokumentacji uploads.sh w MDX na DocsLayout i pomaga je pisać, skracać, przebudowywać i recenzować tak, by były czytelne.
  • 100authoring-docs
    Pisze i skraca strony serwisu dokumentacji w MDX, w tym porządki w starych stronach i nowe integracje.
  • 100docs-organizer
    Porządkuje foldery dokumentacji projektu: czyści, konsoliduje i restrukturyzuje dokumenty, gdy ktoś prosi o uporządkowanie katalogu docs.
  • 100dsh-doc-site-sync
    Publikuje, aktualizuje, przenosi i usuwa strony dokumentacji DeepSeek Harness, edytuje mapowania w website/docs.ts i nawigację oraz diagnozuje brakujące strony VitePress.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.