Communitygithub.com

hantkunpeng/compétences

Une collection de compétences personnalisées pour les agents IA, dédiée à Google Antigravity et à l'écosystème ouvert des compétences d'agents.

Qu'est-ce que compétences ?

Cette compétence spécialisée fournit des connaissances approfondies et une automatisation pour la création, l'édition et l'analyse de fichiers DOCX. Elle couvre la lecture de contenu avec `markitdown`, l'accès brut aux fichiers XML via le décompression, et l'acceptation des modifications suivies. Pour la création, elle détaille l'utilisation de la bibliothèque `docx-js` en JavaScript, y compris la configuration de la mise en page, les styles, les listes, les tableaux (avec gestion critique des largeurs), les images, les hyperliens, les notes de bas de page, les colonnes multiples, les tables des matières, et les en-têtes/pieds de page. Elle impose des règles précises comme l'utilisation des tailles de page explicitement en DXA et le recours aux taquets de tabulation plutôt qu'aux tableaux pour les séparateurs. Pour l'édition, elle décrit un processus en trois étapes (décompresser, modifier le XML, recompresser) avec des conventions strictes : utiliser "Claude" comme auteur par défaut pour les modifications et commentaires, l'outil Edit pour les remplacements directs, et les entités XML pour les guillemets typographiques. La compétence s'adresse aux développeurs et agents IA travaillant sur des documents professionnels nécessitant un contrôle fin du format DOCX. Elle est conçue pour être utilisée avec des agents comme Claude Code ou tout autre agent supportant un écosystème de compétences, en s'appuyant sur des scripts Python (`scripts/office/`) et des modules Node.js (`docx-js`). En résumé, cette compétence transforme la manipulation des DOCX en une tâche reproductible, fiable et conforme aux normes, en évitant les pièges courants liés aux formats de fichiers. Elle est particulièrement utile pour automatiser la génération de rapports, contrats, ou documents académiques complexes.

Compatible avec✓Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add hankunpeng/skills

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Création, édition et analyse de fichiers DOCX

Aperçu

Un fichier .docx est une archive ZIP contenant des fichiers XML.

Référence rapide

TâcheApproche
Lire/analyser le contenumarkitdown ou décompresser pour le XML brut
Créer un nouveau documentUtiliser docx-js - voir Création de nouveaux documents ci-dessous
Modifier un document existantDécompresser → éditer le XML → recompresser - voir Modification de documents existants ci-dessous

Lecture du contenu

# Extraction de texte
markitdown document.docx > output.md

# Accès brut au XML
python scripts/office/unpack.py document.docx unpacked/

Accepter les modifications suivies

Pour obtenir un document propre avec toutes les modifications suivies acceptées :

python scripts/accept_changes.py input.docx output.docx

Création de nouveaux documents

Générer des fichiers .docx avec JavaScript, puis valider. Installer : npm install -g docx

Configuration

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
        Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
        InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
        PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
        TabStopType, TabStopPosition, Column, SectionType,
        TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
        VerticalAlign, PageNumber, PageBreak } = require('docx');

const doc = new Document({ sections: [{ children: [/* contenu */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));

Validation

Après avoir créé le fichier, validez-le. Si la validation échoue, décompressez, corrigez le XML et recompressez.

python scripts/office/validate.py doc.docx

Taille de page

// CRITIQUE : docx-js utilise A4 par défaut, pas US Letter
// Toujours définir la taille de page explicitement pour des résultats cohérents
sections: [{
  properties: {
    page: {
      size: {
        width: 12240,   // 8,5 pouces en DXA
        height: 15840   // 11 pouces en DXA
      },
      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // Marges d'1 pouce
    }
  },
  children: [/* contenu */]
}]

Tailles de page courantes (en unités DXA, 1440 DXA = 1 pouce) :

PapierLargeurHauteurLargeur du contenu (marges d'1 pouce)
US Letter12 24015 8409 360
A4 (par défaut)11 90616 8389 026

Orientation paysage : docx-js échange largeur/hauteur en interne, donc transmettez les dimensions portrait et laissez-le gérer l'échange :

size: {
  width: 12240,   // Transmettre le bord COURT comme largeur
  height: 15840,  // Transmettre le bord LONG comme hauteur
  orientation: PageOrientation.LANDSCAPE  // docx-js les échange dans le XML
},
// Largeur du contenu = 15840 - marge gauche - marge droite (utilise le bord long)

Styles (Remplacer les titres intégrés)

Utiliser Arial comme police par défaut (universellement prise en charge). Garder les titres en noir pour une meilleure lisibilité.

const doc = new Document({
  styles: {
    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt par défaut
    paragraphStyles: [
      // IMPORTANT : Utiliser des identifiants exacts pour remplacer les styles intégrés
      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 32, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel requis pour la TDM
      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
        run: { size: 28, bold: true, font: "Arial" },
        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Titre")] }),
    ]
  }]
});

Listes (NE JAMAIS utiliser de puces Unicode)

// ❌ INCORRECT - ne jamais insérer manuellement de caractères de puce
new Paragraph({ children: [new TextRun("• Élément")] })  // MAUVAIS
new Paragraph({ children: [new TextRun("\u2022 Élément")] })  // MAUVAIS

// ✅ CORRECT - utiliser la configuration de numérotation avec LevelFormat.BULLET
const doc = new Document({
  numbering: {
    config: [
      { reference: "puces",
        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
      { reference: "nombres",
        levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
    ]
  },
  sections: [{
    children: [
      new Paragraph({ numbering: { reference: "puces", level: 0 },
        children: [new TextRun("Élément de liste à puces")] }),
      new Paragraph({ numbering: { reference: "nombres", level: 0 },
        children: [new TextRun("Élément numéroté")] }),
    ]
  }]
});

// ⚠️ Chaque référence crée une numérotation INDÉPENDANTE
// Même référence = continue (1,2,3 puis 4,5,6)
// Référence différente = redémarre (1,2,3 puis 1,2,3)

Tableaux

CRITIQUE : Les tableaux nécessitent des largeurs doubles - définir à la fois columnWidths sur le tableau ET width sur chaque cellule. Sans les deux, les tableaux s'affichent incorrectement sur certaines plates-formes.

// CRITIQUE : Toujours définir la largeur du tableau pour un rendu cohérent
// CRITIQUE : Utiliser ShadingType.CLEAR (pas SOLID) pour éviter les arrière-plans noirs
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };

new Table({
  width: { size: 9360, type: WidthType.DXA }, // Toujours utiliser DXA (les pourcentages ne fonctionnent pas dans Google Docs)
  columnWidths: [4680, 4680], // Doit totaliser la largeur du tableau (DXA : 1440 = 1 pouce)
  rows: [
    new TableRow({
      children: [
        new TableCell({
          borders,
          width: { size: 4680, type: WidthType.DXA }, // Également définir sur chaque cellule
          shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR pas SOLID
          margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Remplissage de cellule (interne, ne s'ajoute pas à la largeur)
          children: [new Paragraph({ children: [new TextRun("Cellule")] })]
        })
      ]
    })
  ]
})

Calcul de la largeur du tableau :

Toujours utiliser WidthType.DXA — WidthType.PERCENTAGE ne fonctionne pas dans Google Docs.

// Largeur du tableau = somme des columnWidths = largeur du contenu
// US Letter avec marges d'1 pouce : 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360]  // Doit totaliser la largeur du tableau

Règles de largeur :

  • Toujours utiliser WidthType.DXA — jamais WidthType.PERCENTAGE (incompatible avec Google Docs)
  • La largeur du tableau doit être égale à la somme des columnWidths
  • La width de la cellule doit correspondre à la columnWidth correspondante
  • Les margins de la cellule sont un remplissage interne ; elles réduisent la zone de contenu et ne s'ajoutent pas à la largeur de la cellule
  • Pour les tableaux pleine largeur : utiliser la largeur du contenu (largeur de page moins les marges gauche et droite)

Images

// CRITIQUE : le paramètre type est OBLIGATOIRE
new Paragraph({
  children: [new ImageRun({
    type: "png", // Obligatoire : png, jpg, jpeg, gif, bmp, svg
    data: fs.readFileSync("image.png"),
    transformation: { width: 200, height: 150 },
    altText: { title: "Titre", description: "Desc", name: "Nom" } // Les trois sont obligatoires
  })]
})

Sauts de page

// CRITIQUE : PageBreak doit être à l'intérieur d'un Paragraphe
new Paragraph({ children: [new PageBreak()] })

// Ou utiliser pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("Nouvelle page")] })

Hyperliens

// Lien externe
new Paragraph({
  children: [new ExternalHyperlink({
    children: [new TextRun({ text: "Cliquez ici", style: "Hyperlink" })],
    link: "https://example.com",
  })]
})

// Lien interne (signet + référence)
// 1. Créer un signet à la destination
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
  new Bookmark({ id: "chapitre1", children: [new TextRun("Chapitre 1")] }),
]})
// 2. Lien vers celui-ci
new Paragraph({ children: [new InternalHyperlink({
  children: [new TextRun({ text: "Voir le Chapitre 1", style: "Hyperlink" })],
  anchor: "chapitre1",
})]})

Notes de bas de page

const doc = new Document({
  footnotes: {
    1: { children: [new Paragraph("Source : Rapport annuel 2024")] },
    2: { children: [new Paragraph("Voir l'annexe pour la méthodologie")] },
  },
  sections: [{
    children: [new Paragraph({
      children: [
        new TextRun("Le chiffre d'affaires a augmenté de 15 %"),
        new FootnoteReferenceRun(1),
        new TextRun(" en utilisant des mesures ajustées"),
        new FootnoteReferenceRun(2),
      ],
    })]
  }]
});

Taquets de tabulation

// Aligner le texte à droite sur la même ligne (par exemple, date en face d'un titre)
new Paragraph({
  children: [
    new TextRun("Nom de l'entreprise"),
    new TextRun("\tJanvier 2025"),
  ],
  tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})

// Points de suite (style TDM)
new Paragraph({
  children: [
    new TextRun("Introduction"),
    new TextRun({ children: [
      new PositionalTab({
        alignment: PositionalTabAlignment.RIGHT,
        relativeTo: PositionalTabRelativeTo.MARGIN,
        leader: PositionalTabLeader.DOT,
      }),
      "3",
    ]}),
  ],
})

Mises en page multi-colonnes

// Colonnes de largeur égale
sections: [{
  properties: {
    column: {
      count: 2,          // nombre de colonnes
      space: 720,        // espace entre les colonnes en DXA (720 = 0,5 pouce)
      equalWidth: true,
      separate: true,    // ligne verticale entre les colonnes
    },
  },
  children: [/* le contenu s'écoule naturellement entre les colonnes */]
}]

// Colonnes de largeur personnalisée (equalWidth doit être false)
sections: [{
  properties: {
    column: {
      equalWidth: false,
      children: [
        new Column({ width: 5400, space: 720 }),
        new Column({ width: 3240 }),
      ],
    },
  },
  children: [/* contenu */]
}]

Forcer un saut de colonne avec une nouvelle section utilisant type: SectionType.NEXT_COLUMN.

Table des matières

// CRITIQUE : Les titres doivent utiliser UNIQUEMENT HeadingLevel - pas de styles personnalisés
new TableOfContents("Table des matières", { hyperlink: true, headingStyleRange: "1-3" })

En-têtes/Pieds de page

sections: [{
  properties: {
    page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 pouce
  },
  headers: {
    default: new Header({ children: [new Paragraph({ children: [new TextRun("En-tête")] })] })
  },
  footers: {
    default: new Footer({ children: [new Paragraph({
      children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
    })] })
  },
  children: [/* contenu */]
}]

Règles critiques pour docx-js

  • Définir la taille de page explicitement - docx-js utilise A4 par défaut ; utiliser US Letter (12240 x 15840 DXA) pour les documents américains
  • Paysage : transmettre les dimensions portrait - docx-js échange largeur/hauteur en interne ; transmettre le bord court comme width, le bord long comme height, et définir orientation: PageOrientation.LANDSCAPE
  • Ne jamais utiliser \n - utiliser des éléments Paragraphe séparés
  • Ne jamais utiliser de puces Unicode - utiliser LevelFormat.BULLET avec la configuration de numérotation
  • PageBreak doit être dans un Paragraphe - autonome crée un XML invalide
  • ImageRun nécessite type - toujours spécifier png/jpg/etc.
  • Toujours définir la width du tableau avec DXA - ne jamais utiliser WidthType.PERCENTAGE (ne fonctionne pas dans Google Docs)
  • Les tableaux nécessitent des largeurs doubles - tableau columnWidths ET width de la cellule, les deux doivent correspondre
  • Largeur du tableau = somme des columnWidths - pour DXA, s'assurer qu'elles s'additionnent exactement
  • Toujours ajouter les marges de cellule - utiliser margins: { top: 80, bottom: 80, left: 120, right: 120 } pour un remplissage lisible
  • Utiliser ShadingType.CLEAR - jamais SOLID pour l'ombrage du tableau
  • Ne jamais utiliser de tableaux comme séparateurs/règles - les cellules ont une hauteur minimale et s'affichent comme des boîtes vides (y compris dans les en-têtes/pieds de page) ; utiliser border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } } sur un Paragraphe à la place. Pour les pieds de page à deux colonnes, utiliser les taquets de tabulation (voir la section Taquets de tabulation), pas de tableaux
  • TDM nécessite uniquement HeadingLevel - pas de styles personnalisés sur les paragraphes de titre
  • Remplacer les styles intégrés - utiliser des identifiants exacts : "Heading1", "Heading2", etc.
  • Inclure outlineLevel - requis pour la TDM (0 pour H1, 1 pour H2, etc.)

Modification de documents existants

Suivre les 3 étapes dans l'ordre.

Étape 1 : Décompresser

python scripts/office/unpack.py document.docx unpacked/

Extrait le XML, l'imprime joliment, fusionne les passages adjacents et convertit les guillemets intelligents en entités XML (“ etc.) afin qu'ils survivent à l'édition. Utiliser --merge-runs false pour ignorer la fusion de passages.

Étape 2 : Modifier le XML

Modifier les fichiers dans unpacked/word/. Voir la Référence XML ci-dessous pour les modèles.

Utiliser "Claude" comme auteur pour les modifications suivies et les commentaires, sauf si l'utilisateur demande explicitement d'utiliser un autre nom.

Utiliser directement l'outil Edit pour le remplacement de chaînes. Ne pas écrire de scripts Python. Les scripts introduisent une complexité inutile. L'outil Edit montre exactement ce qui est remplacé.

CRITIQUE : Utiliser les guillemets intelligents pour le nouveau contenu. Lors de l'ajout de texte avec des apostrophes ou des guillemets, utiliser des entités XML pour produire des guillemets intelligents :

<!-- Utiliser ces entités pour une typographie professionnelle -->
<w:t>Voici&#x2019;une citation : &#x201C;Bonjour&#x201D;</w:t>
EntitéCaractère
&#x2018;' (guillemet simple gauche)
&#x2019;' (guillemet simple droite / apostrophe)
&#x201C;" (guillemet double gauche)
&#x201D;" (guillemet double droite)

Ajout de commentaires : Utiliser comment.py pour gérer le code passe-partout sur plusieurs fichiers XML (le texte doit être pré-échappé en XML) :

python scripts/comment.py unpacked/ 0 "Texte du commentaire avec &amp; et &#x2019;"
python scripts/comment.py unpacked/ 1 "Texte de réponse" --parent 0  # répondre au commentaire 0
python scripts/comment.py unpacked/ 0 "Texte" --author "Auteur personnalisé"  # nom d'auteur personnalisé

Ensuite, ajouter des marqueurs dans document.xml (voir Commentaires dans la Référence XML).

Étape 3 : Recompresser

python scripts/office/pack.py unpacked/ output.docx --original document.docx

Valide avec réparation automatique, condense le XML et crée le fichier de sortie. Le paramètre --original préserve les métadonnées et les propriétés du document original.


Référence XML

Ajouter du contenu

<w:p>
  <w:pPr>
    <w:pStyle w:val="Heading1"/>
  </w:pPr>
  <w:r>
    <w:rPr/>
    <w:t>Nouveau titre</w:t>
  </w:r>
</w:p>

Modifications suivies (insertion)

<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r>
    <w:rPr/>
    <w:t>Nouveau texte</w:t>
  </w:r>
</w:ins>

Modifications suivies (suppression)

<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
  <w:r>
    <w:delText xml:space="preserve">Ancien texte</w:delText>
  </w:r>
</w:del>

Commentaires

Ajouter d'abord les commentaires avec comment.py, puis les marqueurs dans document.xml :

<w:commentRangeStart w:id="0"/>
<w:r><w:t>Texte commenté</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr/><w:commentReference w:id="0"/></w:r>

Images (encodées en base64 stockées dans le XML)

<w:drawing>
  <wp:inline distT="0" distB="0" distL="0" distR="0">
    <wp:extent cx="1828800" cy="1371600"/>
    <wp:effectExtent l="0" t="0" r="0" b="0"/>
    <wp:docPr id="1" name="Image1" descr="Description"/>
    <a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
      <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
        <pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
          <pic:nvPicPr>
            <pic:cNvPr id="1" name="Image1" descr="Description"/>
            <pic:cNvPicPr/>
          </pic:nvPicPr>
          <pic:blipFill>
            <a:blip r:embed="rId1"/>
            <a:stretch><a:fillRect/></a:stretch>
          </pic:blipFill>
          <pic:spPr>
            <a:xfrm><a:off x="0" y="0"/><a:ext cx="1828800" cy="1371600"/></a:xfrm>
            <a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
          </pic:spPr>
        </pic:pic>
      </a:graphicData>
    </a:graphic>
  </wp:inline>
</w:drawing>

Le fichier image séparé est stocké dans media/image1.png. Les dimensions sont en EMU (914400 EMU = 1 pouce). Convertir comme suit : pouces * 914400, cm * 360000.

Splice de contenu (fusionner des documents complets)

Pour combiner plusieurs documents .docx en un seul document :

python scripts/office/splice.py --input "input1.docx" --input "input2.docx" --output "merged.docx"

L'ordre suit les options --input.

Cela gère la fusion correcte des relations et des espaces de noms.


Dépannage

ProblèmeSolution
Validation échoueDécompresser → vérifier le XML → corriger les balises non fermées
Les tableaux semblables à boîtes videsUtilisé à mauvais escient comme séparateur ; utiliser plutôt border sur un Paragraphe
Google Docs affiche mal le tableauVérifier que la largeur utilise WidthType.DXA (pas PERCENTAGE)
Les images ne s'affichent pasVérifier que type est défini et que les données binaires sont valides
La TDM est videVérifier que les titres utilisent HeadingLevel AVEC outlineLevel
Les listes à puces sont des caractères UnicodeRemplacer par LevelFormat.BULLET avec configuration de numérotation
Les notes de bas de page manquentAjouter les références avec FootnoteReferenceRun(numéro) dans le texte

Skills associés