{"id":"cc7511fb-f8ef-4491-bf23-1fd99861956b","shortId":"ZBYDJN","kind":"skill","title":"clean-slides","tagline":"Inspect, edit, and generate PowerPoint slides. Progressive drill-down inspection, text editing with formatting preservation, table generation from YAML, and PNG rendering for verification.","description":"# PowerPoint Skill\n\nUse the `pptx` CLI for all PowerPoint operations.\n\n## When to use\n- **Inspect** slide contents, shapes, formatting, charts\n- **Edit** text while preserving formatting\n- **Generate** table slides from YAML specs\n- **Render** slides to PNG for visual verification\n\n## Setup\n\nBefore generating slides, ensure the project has a `.clean-slides/` directory. The CLI auto-discovers `template.pptx` and `config.yaml` from there — no flags needed.\n\n```bash\n# Quick start — uses the bundled example template\npptx init\n\n# With a custom/corporate template\npptx init -t path/to/corporate-template.pptx\n```\n\nThis creates `.clean-slides/template.pptx` and `.clean-slides/config.yaml`. All `pptx generate` commands in that directory tree will use them automatically.\n\nIf no `.clean-slides/` directory exists, the CLI prints a hint suggesting `pptx init`.\n\n### Overriding auto-discovery\n\nExplicit flags always win:\n\n```bash\n# Override template and config for a single run\npptx generate spec.yaml -t other.pptx -c other-config.yaml -o output.pptx\n```\n\nSee `examples/custom-template/README.md` for a full walkthrough of custom template setup.\n\n## Core workflow: inspect → edit → verify\n\n```bash\n# 1. Inspect — progressive drill-down\npptx show deck.pptx                    # slide list\npptx show deck.pptx 3                  # shapes on slide 3\npptx show deck.pptx 3 5                # full detail for shape [5]\n\n# 2. Edit — shape identified by index or name\npptx edit deck.pptx 3 5 \"New text\" --out edited.pptx\n\n# 3. Verify — render to PNG\npptx render edited.pptx 3 --out images/\n```\n\n## Inspect commands\n\n```bash\npptx show <file>                       # slides with layout, shape count, word count\npptx show <file> <slide>               # all shapes sorted top→bottom, left→right\npptx show <file> <slide> <shape>       # full JSON: text runs, formatting, chart data\n\npptx layouts <file>                    # available slide layouts with placeholders & content areas\npptx theme <file>                      # color scheme (accent1, accent2, etc.)\npptx xml <file> <slide> <shape>        # raw OOXML for debugging\n```\n\n**Run `pptx layouts` on your template** before generating — it shows each layout's fillable placeholders (title, subtitle, tracker, logo, etc.) and content areas with dimensions. Layouts with a **secondary** content area (e.g. 2/3, 3/4) have a sidebar for supporting content like key takeaways, charts, or images.\n\n**Shape types in output:** `ph0` (placeholder), `text`, `chart`, `image`, `group`, `line`, `shape`\n\n## Edit commands\n\n```bash\npptx edit <file> <slide> <shape> <text> [--out PATH]\npptx batch <file> <edits.json> [--out PATH]\n```\n\n**Text formats — inspect output = edit input:**\n\n```json\n{\"paragraphs\": [\n  {\"runs\": [\n    {\"text\": \"Bold \", \"bold\": true},\n    {\"text\": \"normal\"}\n  ], \"level\": 0}\n]}\n```\n\n**Run fields:** `text`, `font`, `size`, `bold`, `italic`, `underline`, `color`, `superscript`, `subscript`\n\n- `\"bold\": true` → explicitly bold\n- `\"bold\": false` → explicitly not bold (overrides inherited)\n- (omit field) → inherit from parent\n\n## Slide management\n\n```bash\npptx add-slide <file> <layout> [--at N] [--out PATH]\npptx delete-slide <file> <slide> --confirm [--out PATH]\npptx delete-shape <file> <slide> <shape> [--out PATH]\npptx insert <deck.pptx> <source.pptx> [--at N] [--slides 1,3-5] [--out PATH]\n```\n\n### Replace a slide with a generated table\n\n```bash\n# 1. Generate the table slide (title/subtitle are set in the YAML)\npptx generate spec.yaml -t template.pptx -o /tmp/table.pptx\n\n# 2. Insert at position 8, pushing old slide 8 → 9\npptx insert deck.pptx /tmp/table.pptx --at 8 --out deck.pptx\n\n# 3. Delete the old slide (now at position 9)\npptx delete-slide deck.pptx 9 --confirm --out deck.pptx\n\n# 4. Verify\npptx render deck.pptx 8 --out renders/\n```\n\n## Render\n\n```bash\npptx render <file> <slides> [--out DIR] [--dpi N]\npptx crop <png> <L> <T> <R> <B> [--out PATH]\n```\n\n`<slides>` accepts single (`3`), list (`1,8,16`), or ranges (`1,3-5,8`). Multiple slides share one PDF conversion.\n\nCoordinates for crop are in inches (matches shape positions from `show`).\n\n## Generate tables from YAML\n\nContext: `pptx generate` accepts **multiple YAML files** and produces **one deck** with one slide per YAML, in input order.\n\n```bash\npptx generate spec.yaml -o output.pptx\npptx generate slide1.yaml slide2.yaml slide3.yaml -o output.pptx\npptx generate spec.yaml -t template.pptx -o output.pptx\npptx generate spec.yaml -t template.pptx -c config.yaml -o output.pptx\npptx validate spec.yaml\npptx verify spec.yaml --detail\n```\n\n**Top-level YAML keys** (all optional, set before `table:`):\n\n- `title` — **required** — fills the title placeholder\n- `subtitle` — fills the subtitle placeholder\n- `tracker` — fills the on-page tracker (supports `\\n` for line breaks)\n- `slide_layout` — template layout name (e.g. `\"Default\"`, `\"2/3\"`, `\"3/4\"`)\n- `content_layout` — content area policy: `default` (below header) or `full` (near top)\n- `sidebar` — formatted paragraphs for the secondary content area in split layouts (2/3, 3/4, 1/2)\n\nSee `INPUT-SCHEMA.md` for the complete schema.\n\n## Inline formatting\n\nText strings in cells, headers, and sidebar support markdown-style inline formatting:\n\n- `**bold text**` → bold\n- `*italic text*` → italic\n- `[link text](https://example.com)` → clickable hyperlink (blue, underlined)\n\n## Column widths\n\nBy default, columns are sized automatically based on content (wider for cells that need more wrapping room). Override with `column_widths`:\n\n```yaml\ntable:\n  column_widths: equal          # equal body columns — best when columns are items being compared\n  column_widths: [1, 2, 1, 1]  # manual proportions\n```\n\n## Custom templates\n\nThe tool ships with a built-in template config, but supports **any** PowerPoint template. The workflow is: inspect the template, generate a config, review/adjust, then generate slides.\n\n### Step 1: Inspect the template\n\n```bash\npptx layouts template.pptx             # see all layouts, placeholders, content areas\npptx theme template.pptx               # see theme color scheme (dk1, lt1, accent1, etc.)\npptx show template.pptx 1              # inspect shapes on a sample slide\npptx xml template.pptx 1 <shape>       # raw XML for bullet lstStyle details\n```\n\n**What to look for:**\n- **Layouts**: which layout names exist, which have content areas\n- **Placeholders**: what index is title (usually 0), subtitle (usually 1), any tracker/breadcrumb\n- **Theme colors**: what dk1, dk2, accent1 map to — these determine text and accent colors\n- **Fonts**: what headline vs body fonts the template uses (check actual slide text, not just theme — templates often override theme fonts at the slide level)\n- **Bullet hierarchy**: if the template has custom bullet styles, inspect the lstStyle XML on a content placeholder\n\n### Step 2: Generate a starter config\n\n```bash\npptx init-config template.pptx -o template-config.yaml\n```\n\nThis auto-extracts:\n- Theme colors → mapped to semantic names (midnight, electric_blue, etc.)\n- Theme fonts → headline/body\n- Slide dimensions and estimated layout geometry\n- Placeholder indices (title, subtitle, tracker if detected)\n- Available layout names (listed as comments)\n\nThe output is a **complete, valid config** with sensible defaults for everything — but some values will need adjustment.\n\n### Step 3: Review and adjust the config\n\nKey areas to verify and adjust:\n\n1. **`colors`**: The auto-extracted `electric_blue` and `cyan` may not map correctly to your template's accent colors. Compare with `pptx theme` output and adjust.\n\n2. **`fonts`**: The theme's major/minor fonts may differ from what the template actually uses on slides. Inspect a content slide (`pptx show template.pptx 2 <shape>`) and check the actual font in use.\n\n3. **`font_sizes`**: Defaults are conservative (12pt body). Check your template's actual type scale and adjust title, body, table sizes.\n\n4. **`placeholders`**: Verify `title` (usually 0) and `subtitle` (usually 1) are correct. If your template has a tracker/breadcrumb placeholder, set its index. Remove `tracker` if there isn't one.\n\n5. **`default_colors`**: These control what theme color names are used for body text (`tx1`), headers (`tx1` or `accent1`), dividers, and links. Adjust to match your template's design language.\n\n6. **`bullets`**: The hardest to auto-detect. If your template has custom bullet styles with specific chars (•, –, ›) and indentation, inspect the slide master lstStyle:\n   ```bash\n   pptx xml template.pptx 1 <content-placeholder>\n   # Look for <a:lstStyle> with <a:lvl1pPr>, <a:lvl2pPr>, etc.\n   ```\n   Update bullet chars, `mar_l_emu`, `indent_emu`, and spacing to match.\n\n7. **`layout`**: The auto-detected margins and Y positions are estimates. If slides look misaligned, measure positions from `pptx show template.pptx <slide>` output and adjust `content_start_y_emu`, `footer_line_y_emu`, etc.\n\n### Step 4: Generate with custom config\n\n```bash\n# Generate\npptx generate spec.yaml -t template.pptx -c template-config.yaml -o output.pptx\n\n# Validate / verify also accept --config\npptx validate spec.yaml -c template-config.yaml\npptx verify spec.yaml -c template-config.yaml --detail\n```\n\n### Tips for custom templates\n\n- **Start simple**: generate a basic 2×2 table first and render it to check alignment\n- **Iterate**: render after each config adjustment to see the effect\n- **Content areas from layout**: when using `-t template.pptx`, the generator reads content area dimensions from the actual slide layout placeholders, so layout geometry often works even with approximate config values\n- **Bullet levels**: if your template doesn't use custom bullets, the defaults (•, –, ›) work for most templates\n- **The config doesn't need to be perfect**: the generator adapts to the template's actual placeholder positions at runtime; the config mainly controls styling (fonts, colors, spacing)\n\n## Backup policy\n\nBefore editing, save a backup:\n```bash\ncp deck.pptx deck.backup.pptx\npptx edit deck.pptx ... --out deck.edited.pptx\n```\n\nAlways use `--out` to write to a new file unless explicitly asked to overwrite.\n\n## Tips\n\n- **Placeholders** (ph0, ph1, etc.) are structural — edit text only, don't delete or resize\n- **Inspect before editing** — use `show` to find the right shape index\n- **Render after editing** — visual verification catches formatting issues\n- **Copy formatting from inspect** — the JSON output works directly as edit input","tags":["clean","slides","tmustier","agent-skills","cli","pi-package","powerpoint","python"],"capabilities":["skill","source-tmustier","skill-clean-slides","topic-agent-skills","topic-cli","topic-pi-package","topic-powerpoint","topic-python"],"categories":["clean-slides"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/tmustier/clean-slides","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add tmustier/clean-slides","source_repo":"https://github.com/tmustier/clean-slides","install_from":"skills.sh"}},"qualityScore":"0.457","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 15 github stars · SKILL.md body (10,442 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-22T13:03:17.934Z","embedding":null,"createdAt":"2026-04-19T00:41:04.656Z","updatedAt":"2026-04-22T13:03:17.934Z","lastSeenAt":"2026-04-22T13:03:17.934Z","tsv":"'-5':443,539 '/config.yaml':120 '/template.pptx':115 '/tmp/table.pptx':471,485 '0':384,860,1088 '1':190,441,454,532,537,759,761,762,796,824,834,863,1003,1092,1171 '1/2':684 '12pt':1068 '16':534 '2':219,472,760,923,1030,1054,1264,1265 '2/3':331,657,682 '3':204,208,212,230,236,244,442,490,530,538,991,1062 '3/4':332,658,683 '4':508,1083,1223 '5':213,218,231,1112 '6':1142 '7':1188 '8':476,480,487,513,533,540 '9':481,498,504 'accent':878,1021 'accent1':290,819,871,1130 'accent2':291 'accept':528,565,1242 'actual':890,1043,1058,1074,1300,1345 'adapt':1340 'add':417 'add-slid':416 'adjust':989,994,1002,1029,1078,1134,1212,1279 'align':1273 'also':1241 'alway':154,1374 'approxim':1311 'area':285,321,329,662,678,809,853,998,1285,1296 'ask':1385 'auto':82,150,938,1007,1148,1192 'auto-detect':1147,1191 'auto-discov':81 'auto-discoveri':149 'auto-extract':937,1006 'automat':132,726 'avail':279,966 'backup':1358,1364 'base':727 'bash':92,156,189,249,359,414,453,517,581,800,928,1167,1228,1365 'basic':1263 'batch':365 'best':750 'blue':717,948,1010 'bodi':748,884,1069,1080,1124 'bold':378,379,390,396,399,400,404,706,708 'bottom':265 'break':649 'built':773 'built-in':772 'bullet':838,905,912,1143,1155,1177,1314,1323 'bundl':97 'c':170,606,1235,1247,1252 'catch':1419 'cell':696,732 'char':1159,1178 'chart':47,275,342,352 'check':889,1056,1070,1272 'clean':2,76,113,118,136 'clean-slid':1,75,112,117,135 'cli':34,80,141 'clickabl':715 'color':288,393,815,867,879,941,1004,1022,1114,1119,1356 'column':719,723,740,744,749,752,757 'command':124,248,358 'comment':971 'compar':756,1023 'complet':689,976 'config':160,776,790,927,932,978,996,1227,1243,1278,1312,1331,1351 'config.yaml':86,607 'confirm':427,505 'conserv':1067 'content':44,284,320,328,338,659,661,677,729,808,852,920,1049,1213,1284,1295 'context':562 'control':1116,1353 'convers':546 'coordin':547 'copi':1422 'core':184 'correct':1016,1094 'count':256,258 'cp':1366 'creat':111 'crop':525,549 'custom':181,765,911,1154,1226,1257,1322 'custom/corporate':104 'cyan':1012 'data':276 'debug':298 'deck':572 'deck.backup.pptx':1368 'deck.edited.pptx':1373 'deck.pptx':198,203,211,229,484,489,503,507,512,1367,1371 'default':656,664,722,981,1065,1113,1325 'delet':425,432,491,501,1400 'delete-shap':431 'delete-slid':424,500 'design':1140 'detail':215,616,840,1254 'detect':965,1149,1193 'determin':875 'differ':1038 'dimens':323,954,1297 'dir':521 'direct':1430 'directori':78,127,138 'discov':83 'discoveri':151 'divid':1131 'dk1':817,869 'dk2':870 'doesn':1319,1332 'dpi':522 'drill':12,194 'drill-down':11,193 'e.g':330,655 'edit':5,16,48,187,220,228,357,361,372,1361,1370,1395,1405,1416,1432 'edited.pptx':235,243 'effect':1283 'electr':947,1009 'emu':1181,1183,1216,1220 'ensur':70 'equal':746,747 'estim':956,1199 'etc':292,318,820,949,1175,1221,1392 'even':1309 'everyth':983 'exampl':98 'example.com':714 'examples/custom-template/readme.md':175 'exist':139,849 'explicit':152,398,402,1384 'extract':939,1008 'fals':401 'field':386,408 'file':568,1382 'fill':629,634,639 'fillabl':312 'find':1409 'first':1267 'flag':90,153 'font':388,880,885,900,951,1031,1036,1059,1063,1355 'footer':1217 'format':18,46,52,274,369,672,692,705,1420,1423 'full':178,214,270,668 'generat':7,21,53,68,123,166,306,451,455,466,558,564,583,588,595,602,788,793,924,1224,1229,1231,1261,1293,1339 'geometri':958,1306 'group':354 'hardest':1145 'header':666,697,1127 'headlin':882 'headline/body':952 'hierarchi':906 'hint':144 'hyperlink':716 'identifi':222 'imag':246,344,353 'inch':552 'indent':1161,1182 'index':224,856,1104,1413 'indic':960 'inherit':406,409 'init':101,107,147,931 'init-config':930 'inlin':691,704 'input':373,579,1433 'input-schema.md':686 'insert':437,473,483 'inspect':4,14,42,186,191,247,370,785,797,825,914,1047,1162,1403,1425 'isn':1109 'issu':1421 'ital':391,709,711 'item':754 'iter':1274 'json':271,374,1427 'key':340,621,997 'l':1180 'languag':1141 'layout':254,278,281,301,310,324,651,653,660,681,802,806,845,847,957,967,1189,1287,1302,1305 'left':266 'level':383,619,904,1315 'like':339 'line':355,648,1218 'link':712,1133 'list':200,531,969 'logo':317 'look':843,1172,1202 'lststyle':839,916,1166 'lt1':818 'main':1352 'major/minor':1035 'manag':413 'manual':763 'map':872,942,1015 'mar':1179 'margin':1194 'markdown':702 'markdown-styl':701 'master':1165 'match':553,1136,1187 'may':1013,1037 'measur':1204 'midnight':946 'misalign':1203 'multipl':541,566 'n':420,439,523,646 'name':226,654,848,945,968,1120 'near':669 'need':91,734,988,1334 'new':232,1381 'normal':382 'o':172,470,585,592,599,608,934,1237 'often':897,1307 'old':478,493 'omit':407 'on-pag':641 'one':544,571,574,1111 'ooxml':296 'oper':38 'option':623 'order':580 'other-config.yaml':171 'other.pptx':169 'output':348,371,973,1027,1210,1428 'output.pptx':173,586,593,600,609,1238 'overrid':148,157,405,738,898 'overwrit':1387 'page':643 'paragraph':375,673 'parent':411 'path':363,367,422,429,435,445,527 'path/to/corporate-template.pptx':109 'pdf':545 'per':576 'perfect':1337 'ph0':349,1390 'ph1':1391 'placehold':283,313,350,632,637,807,854,921,959,1084,1101,1303,1346,1389 'png':25,62,240 'polici':663,1359 'posit':475,497,555,1197,1205,1347 'powerpoint':8,29,37,780 'pptx':33,100,106,122,146,165,196,201,209,227,241,250,259,268,277,286,293,300,360,364,415,423,430,436,465,482,499,510,518,524,563,582,587,594,601,610,613,801,810,821,831,929,1025,1051,1168,1207,1230,1244,1249,1369 'preserv':19,51 'print':142 'produc':570 'progress':10,192 'project':72 'proport':764 'push':477 'quick':93 'rang':536 'raw':295,835 'read':1294 'remov':1105 'render':26,59,238,242,511,515,516,519,1269,1275,1414 'replac':446 'requir':628 'resiz':1402 'review':992 'review/adjust':791 'right':267,1411 'room':737 'run':164,273,299,376,385 'runtim':1349 'sampl':829 'save':1362 'scale':1076 'schema':690 'scheme':289,816 'secondari':327,676 'see':174,685,804,813,1281 'semant':944 'sensibl':980 'set':461,624,1102 'setup':66,183 'shape':45,205,217,221,255,262,345,356,433,554,826,1412 'share':543 'ship':769 'show':197,202,210,251,260,269,308,557,822,1052,1208,1407 'sidebar':335,671,699 'simpl':1260 'singl':163,529 'size':389,725,1064,1082 'skill':30 'skill-clean-slides' 'slide':3,9,43,55,60,69,77,114,119,137,199,207,252,280,412,418,426,440,448,458,479,494,502,542,575,650,794,830,891,903,953,1046,1050,1164,1201,1301 'slide1.yaml':589 'slide2.yaml':590 'slide3.yaml':591 'sort':263 'source-tmustier' 'space':1185,1357 'spec':58 'spec.yaml':167,467,584,596,603,612,615,1232,1246,1251 'specif':1158 'split':680 'start':94,1214,1259 'starter':926 'step':795,922,990,1222 'string':694 'structur':1394 'style':703,913,1156,1354 'subscript':395 'subtitl':315,633,636,861,962,1090 'suggest':145 'superscript':394 'support':337,645,700,778 'tabl':20,54,452,457,559,626,743,1081,1266 'takeaway':341 'templat':99,105,158,182,304,652,766,775,781,787,799,887,896,909,1019,1042,1072,1097,1138,1152,1258,1318,1329,1343 'template-config.yaml':935,1236,1248,1253 'template.pptx':84,469,598,605,803,812,823,833,933,1053,1170,1209,1234,1291 'text':15,49,233,272,351,368,377,381,387,693,707,710,713,876,892,1125,1396 'theme':287,811,814,866,895,899,940,950,1026,1033,1118 'tip':1255,1388 'titl':314,627,631,858,961,1079,1086 'title/subtitle':459 'tool':768 'top':264,618,670 'top-level':617 'topic-agent-skills' 'topic-cli' 'topic-pi-package' 'topic-powerpoint' 'topic-python' 'tracker':316,638,644,963,1106 'tracker/breadcrumb':865,1100 'tree':128 'true':380,397 'tx1':1126,1128 'type':346,1075 'underlin':392,718 'unless':1383 'updat':1176 'use':31,41,95,130,888,1044,1061,1122,1289,1321,1375,1406 'usual':859,862,1087,1091 'valid':611,977,1239,1245 'valu':986,1313 'verif':28,65,1418 'verifi':188,237,509,614,1000,1085,1240,1250 'visual':64,1417 'vs':883 'walkthrough':179 'wider':730 'width':720,741,745,758 'win':155 'word':257 'work':1308,1326,1429 'workflow':185,783 'wrap':736 'write':1378 'xml':294,832,836,917,1169 'y':1196,1215,1219 'yaml':23,57,464,561,567,577,620,742","prices":[{"id":"304f8fc7-7989-4805-b158-97610baf8f12","listingId":"cc7511fb-f8ef-4491-bf23-1fd99861956b","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"tmustier","category":"clean-slides","install_from":"skills.sh"},"createdAt":"2026-04-19T00:41:04.656Z"}],"sources":[{"listingId":"cc7511fb-f8ef-4491-bf23-1fd99861956b","source":"github","sourceId":"tmustier/clean-slides","sourceUrl":"https://github.com/tmustier/clean-slides","isPrimary":false,"firstSeenAt":"2026-04-19T00:41:04.656Z","lastSeenAt":"2026-04-22T13:03:17.934Z"}],"details":{"listingId":"cc7511fb-f8ef-4491-bf23-1fd99861956b","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"tmustier","slug":"clean-slides","github":{"repo":"tmustier/clean-slides","stars":15,"topics":["agent-skills","cli","pi","pi-package","powerpoint","python"],"license":"mit","html_url":"https://github.com/tmustier/clean-slides","pushed_at":"2026-02-12T18:04:52Z","description":"Opinionated agent skill and toolkit for clean, consulting-style PowerPoint documents","skill_md_sha":"bce05d082f0ba73a06b872747e3a7819b7df0a92","skill_md_path":"SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/tmustier/clean-slides"},"layout":"root","source":"github","category":"clean-slides","frontmatter":{"name":"clean-slides","description":"Inspect, edit, and generate PowerPoint slides. Progressive drill-down inspection, text editing with formatting preservation, table generation from YAML, and PNG rendering for verification."},"skills_sh_url":"https://skills.sh/tmustier/clean-slides"},"updatedAt":"2026-04-22T13:03:17.934Z"}}