Przejdź do treści
Biblioteka skilli
Dokumenty i biuro · Konwersja i formaty

sdo-docx-operations

/sdo-docx-operations

Podaje zasady i skrypty bezpiecznej edycji plików .docx w officecli, np. przy zakładkach, polach SEQ i REF oraz celowaniu XPath.

Repozytorium
prompts ↗
Licencja
MIT
Ostatnia zmiana repozytorium
02.09.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
19
Skrypty
5
Komentarze HTML
0
Adresy URL w SKILL.md
4
Przestarzałość

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

Licencja

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

Co sprawdzić przed instalacją
  • 5 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/add_bookmarks.py, scripts/fix_enum_tabs.py, scripts/fix_heading_tabs.py, scripts/fix_note_tabs.py, scripts/officecli_xml_common.py

Co robi i kiedy

Podaje zasady i skrypty bezpiecznej edycji plików .docx w officecli, np. przy zakładkach, polach SEQ i REF oraz celowaniu XPath.

Oryginalny opis (EN)

Cross-platform operational guardrails and deterministic helper scripts for officecli OOXML edits on .docx files. Use when editing .docx with officecli raw-set, fixing tab run issues, inserting bookmarks or field codes (SEQ/REF), validating XPath targeting, or preventing destructive raw-set mistakes. Applies across all SDOs -- concrete style names provided by the per-SDO drafting skill.

Jak działa

  1. Workflow
  2. Script entry points
  3. JSON specs
  4. Idempotent updates — avoid hanging paragraphs
  5. Safety rules
  6. Python OOXML manipulation — namespace caveat
  7. References
  8. Cross-references
Sekcje z nagłówków SKILL.md, w oryginale · 131 linii, 743 słów
Podgląd SKILL.md
---
name: sdo-docx-operations
description: Cross-platform operational guardrails and deterministic helper scripts for officecli OOXML edits on .docx files. Use when editing .docx with officecli raw-set, fixing tab run issues, inserting bookmarks or field codes (SEQ/REF), validating XPath targeting, or preventing destructive raw-set mistakes. Applies across all SDOs -- concrete style names provided by the per-SDO drafting skill.
---

# SDO DOCX Operations -- officecli guardrails

Use this skill for reliable, repeatable officecli operations that require
XML-level edits on standards documents.

## Workflow

1. Open the document in resident mode before multi-step edits:
   `officecli open <doc>`
2. Run one mutation command at a time and check exit codes.
3. Use style/ordinal or explicit XPath targeting, not paraId targeting.
4. **Prefer `officecli batch` for template population, text updates, and paragraph additions.**
   Python zipfile/ElementTree scripts can strip namespace declarations from the
   root element (see "Python OOXML manipulation — namespace caveat" below).
   Reserve Python scripts for edits that officecli cannot express.
5. Validate with `officecli view`/`get`/`query` before and after mutation.
6. Close the document at the end: `officecli close <doc>`

## Script entry points

- `scripts/add_bookmarks.py` -- figure/table/reference bookmark insertion
  and reference run replacement.
- `scripts/fix_heading_tabs.py` -- heading number-tab-title run repair.
- `scripts/fix_enum_tabs.py` -- enumeration dash-tab-text run repair.
- `scripts/fix_note_tabs.py` -- NOTE number-tab-text run repair and
  sequence validation.
- `scripts/officecli_xml_common.py` -- shared helpers (run_officecli,
  raw_set, validate_doc, load_json_spec).

All scripts declare PEP 723 inline metadata and are run via `uv run`:

```bash
uv run scripts/add_bookmarks.py --doc <doc> --spec assets/specs/add_bookmarks.example.json
uv run scripts/fix_heading_tabs.py --doc <doc> --mapping assets/specs/fix_heading_tabs.example.json
uv run scripts/fix_enum_tabs.py --doc <doc> --items assets/specs/fix_enum_tabs.example.json
uv run scripts/fix_note_tabs.py --doc <doc> --notes assets/specs/fix_note_tabs.example.json
```

## JSON specs

- `assets/schemas/` -- JSON Schema contracts for each script input.
- `assets/specs/` -- example specs for reuse across projects.

## Idempotent updates — avoid hanging paragraphs

When a script inserts paragraphs (figures, tables) that are later refreshed by
re-running the same script, **hanging paragraphs** accumulate — old inserted
elements are left behind and new ones are added on each run.

**Rules:**

- Before inserting Figure-style image paragraphs: query and remove ALL existing
  `style=Figure` paragraphs (exact match, not contains).
  - Use `paragraph[style=Figure]` — **not** `paragraph[style~=Figure]`.
  - Captions (`style=Figure_No & title` / `FigureNotitle0`) are
    updated **in-place** via `set`; do NOT remove them — they serve as stable
    anchor paraIds for the insertion `--before` target.
- Before rebuilding a table section: remove all dynamic tables by iterating
  `remove /body/tbl[N]` in a `while True / except RuntimeError: break` loop
  rather than a fixed count. A fixed count fails on repeated runs once tables
  have already been removed.
- Before removing paragraphs by paraId: wrap each removal in try/except
  (or check existence first) so the script is safe to run multiple times.
  ParaIds that were already removed on a previous run must not abort the script.
- **Exact vs contains style match matters:**
  - `paragraph[style=Figure]` — exact match (image containers only)
  - `paragraph[style~=Figure_No]` — contains match (would also remove captions)

## Safety rules

- Never use `raw-set --action replace` with an empty XML payload.
- Always keep bookmark names and IDs unique.
- Always preserve non-breaking spaces and explicit tab runs where required.
- Keep scripts platform-independent and executable via `uv run`.
- Always use `uv run python`, never bare `python`.

## Python OOXML manipulation — namespace caveat

When using Python `zipfile` + `ElementTree` to manipulate OOXML directly,
`ET.register_namespace()` must be called for **every** namespace prefix used
in the document — otherwise `ET.tostring()` strips undeclared prefixes from
the root element, causing OpenXML schema validation errors and potentially
breaking the document in Word.

**Safer alternative:** Prefer `officecli batch` for template population,
text updates, and paragraph additions. `officecli batch` preserves all
namespace declarations automatically and handles the OOXML schema correctly.
Reserve Python zipfile/ElementTree for cases where officecli cannot express
the required edit (e.g., inserting hyperlink relationships in `.rels` files).

```python
# Required namespace registrations for even a simple docx:
ET.register_namespace(
    "w", "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
)
ET.register_namespace(
    "r", "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
)
ET.register_namespace("w14", "http://schemas.microsoft.com/office/word/2010/wordml")
ET.register_namespace("w15", "http://schemas.microsoft.com/office/word/2012/wordml")
# ... and potentially 20+ more (wp14, w16, w16se, w16cid, w16sdtdh, etc.)
```

If even one namespace is missing, the document's root element loses those
declarations on serialization and the file fails validation.

- Use `extract_paragraphs()` from `references/raw-xml-manipulation.md`
  — never the naive `<w:p ...>.*?</w:p>` regex (breaks on self-closing `<w:p/>`).
- When extracting `<w:rPr>`, use balanced `<w:rPr>` token matching
  — never `find('<w:rPr', ...)` which also matches `<w:rPrChange>`.
- Validate replacement XML with `validate_para_xml()` before batching.
- Check for `' REF REF_' in pxml` before tag-scanning to avoid
  double-replacement after a paragraph is already fixed.

## References

- [references/tool-usage.md](references/tool-usage.md)
- [references/constraints.md](references/constraints.md)
- [references/xpath-patterns.md](references/xpath-patterns.md)
- [references/field-code-patterns.md](references/field-code-patterns.md)
- [references/tracked-changes.md](references/tracked-changes.md)
- [references/raw-xml-manipulation.md](references/raw-xml-manipulation.md)

## Cross-references

- `sdo-docx-formatting` -- formatting rules that these operations implement
- `3gpp-drafting` / `etsi-drafting` / `itut-drafting` -- concrete style names
  required for XPath targeting (e.g. `Heading1`, `B1`, `NO`, `TF`)
- `docx-svg` -- SVG image insertion when officecli is not available
Pliki w paczce (19)
  • SKILL.md 7 KB
  • assets/schemas/add_bookmarks.schema.json 2 KB
  • assets/schemas/fix_heading_tabs.schema.json 1 KB
  • assets/schemas/heading_style_map.schema.json 1 KB
  • assets/specs/add_bookmarks.example.json 1 KB
  • assets/specs/fix_enum_tabs.example.json 1 KB
  • assets/specs/fix_heading_tabs.example.json 1 KB
  • assets/specs/fix_note_tabs.example.json 1 KB
  • references/constraints.md 8 KB
  • references/field-code-patterns.md 3 KB
  • references/raw-xml-manipulation.md 14 KB
  • references/tool-usage.md 1 KB
  • references/tracked-changes.md 9 KB
  • references/xpath-patterns.md 1 KB
  • scripts/add_bookmarks.py 3 KB
  • scripts/fix_enum_tabs.py 2 KB
  • scripts/fix_heading_tabs.py 2 KB
  • scripts/fix_note_tabs.py 2 KB
  • scripts/officecli_xml_common.py 2 KB

Wersje

W bazie nie ma innych skilli o nazwie sdo-docx-operations.

Migawka bazy z 13.11.2026 · wersja paczki 5902bb4fe5d8 (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

  • 903gpp-drafting
    Przygotowuje i waliduje dokumenty TDoc 3GPP w formacie DOCX: metadane, szablony, procedurę poprawek i mapowanie nazw stylów.
  • 95itut-drafting
    Przygotowuje dokumenty wkładowe ITU-T w plikach .docx: strukturę szablonu, pola nagłówka, mapowanie stylów i zasady równań.
  • 100officecli
    Korzysta z silnika OfficeCLI do dokładnej inspekcji, walidacji, edycji copy-on-write, scalania szablonów i renderowania wizualnego istniejących plików docx, xlsx i pptx.
  • 100officecli
    Tworzy, analizuje, sprawdza i modyfikuje dokumenty Office (.docx, .xlsx, .pptx) przez narzędzie officecli, w tym formatowanie, wykresy i renderowanie do kontroli.
  • 100docx
    Obsługuje pełny cykl życia dokumentów Word: tworzy nowe (docx-js), edytuje istniejące przez OOXML, recenzuje ze śledzeniem zmian, parsuje treść i zachowuje wierność formatowania.
  • 100ooxml-edit
    Proponuje i wprowadza zmiany w warstwie wiedzy agentowej plików .docx, .pptx i .xlsx, np. reguły edycji i źródła, bez ruszania treści.

Uwagi i zgłoszenia

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