@antaif3ng/til-work 0.3.0 → 0.4.0

package/skills/excel-xlsx/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: Excel / XLSX
+slug: excel-xlsx
+version: 1.0.2
+homepage: https://clawic.com/skills/excel-xlsx
+description: "Create, inspect, and edit Microsoft Excel workbooks and XLSX files with reliable formulas, dates, types, formatting, recalculation, and template preservation. Use when (1) the task is about Excel, `.xlsx`, `.xlsm`, `.xls`, `.csv`, or `.tsv`; (2) formulas, formatting, workbook structure, or compatibility matter; (3) the file must stay reliable after edits."
+changelog: Tightened formula anchoring, recalculation, and model traceability after a stricter external spreadsheet audit.
+metadata: {"clawdbot":{"emoji":"📗","requires":{"bins":[]},"os":["linux","darwin","win32"]}}
+---
+
+## When to Use
+
+Use when the main artifact is a Microsoft Excel workbook or spreadsheet file, especially when formulas, dates, formatting, merged cells, workbook structure, or cross-platform behavior matter.
+
+## Core Rules
+
+### 1. Choose the workflow by job, not by habit
+
+- Use `pandas` for analysis, reshaping, and CSV-like tasks.
+- Use `openpyxl` when formulas, styles, sheets, comments, merged cells, or workbook preservation matter.
+- Treat CSV as plain data exchange, not as an Excel feature-complete format.
+- Reading values, preserving a live workbook, and building a model from scratch are different spreadsheet jobs.
+
+### 2. Dates are serial numbers with legacy quirks
+
+- Excel stores dates as serial numbers, not real date objects.
+- The 1900 date system includes the false leap-day bug, and some workbooks use the 1904 system.
+- Time is fractional day data, so formatting and conversion both matter.
+- Date correctness is not enough if the number format still displays the wrong thing to the user.
+
+### 3. Keep calculations in Excel when the workbook should stay live
+
+- Write formulas into cells instead of hardcoding derived results from Python.
+- Use references to assumption cells instead of magic numbers inside formulas.
+- Cached formula values can be stale, so do not trust them blindly after edits.
+- Check copied formulas for wrong ranges, wrong sheets, and silent off-by-one drift before delivery.
+- Absolute and relative references are part of the logic, so copied formulas can be wrong even when they still "work".
+- Test new formulas on a few representative cells before filling them across a whole block.
+- Verify denominators, named ranges, and precedent cells before shipping formulas that depend on them.
+- A workbook should ship with zero formula errors, not with known `#REF!`, `#DIV/0!`, `#VALUE!`, `#NAME?`, or circular-reference fallout left for the user to fix.
+- For model-style work, document non-obvious hardcodes, assumptions, or source inputs in comments or nearby notes.
+
+### 4. Protect data types before Excel mangles them
+
+- Long identifiers, phone numbers, ZIP codes, and leading-zero values should usually be stored as text.
+- Excel silently truncates numeric precision past 15 digits.
+- Mixed text-number columns need explicit handling on read and on write.
+- Scientific notation, auto-parsed dates, and stripped leading zeros are common corruption, not cosmetic issues.
+
+### 5. Preserve workbook structure before changing content
+
+- Existing templates override generic styling advice.
+- Only the top-left cell of a merged range stores the value.
+- Hidden rows, hidden columns, named ranges, and external references can still affect formulas and outputs.
+- Shared strings, defined names, and sheet-level conventions can matter even when the visible cells look simple.
+- Match styles for newly filled cells instead of quietly introducing a new visual system.
+- If the workbook is a template, preserve sheet order, widths, freezes, filters, print settings, validations, and visual conventions unless the task explicitly changes them.
+- Conditional formatting, filters, print areas, and data validation often carry business meaning even when users only mention the numbers.
+- If there is no existing style guide and the file is a model, keep editable inputs visually distinguishable from formulas, but never override an established template to force a generic house style.
+
+### 6. Recalculate and review before delivery
+
+- Formula strings alone are not enough if the recipient needs current values.
+- `openpyxl` preserves formulas but does not calculate them.
+- Verify no `#REF!`, `#DIV/0!`, `#VALUE!`, `#NAME?`, or circular-reference fallout remains.
+- If layout matters, render or visually review the workbook before calling it finished.
+- Be careful with read modes: opening a workbook for values only and then saving can flatten formulas into static values.
+- If assumptions or hardcoded overrides must stay, make them obvious enough that the next editor can audit the workbook.
+
+### 7. Scale the workflow to the file size
+
+- Large workbooks can fail for boring reasons: memory spikes, padded empty rows, and slow full-sheet reads.
+- Use streaming or chunked reads when the file is big enough that loading everything at once becomes fragile.
+- Large-file workflows also need narrower reads, explicit dtypes, and sheet targeting to avoid accidental damage.
+
+## Common Traps
+
+- Type inference on read can leave numbers as text or convert IDs into damaged numeric values.
+- Column indexing varies across tools, so off-by-one mistakes are common in generated formulas.
+- Newlines in cells need wrapping to display correctly.
+- External references break easily when source files move.
+- Password protection in old Excel workflows is not serious security.
+- `.xlsm` can contain macros, and `.xls` remains a tighter legacy format.
+- Large files may need streaming reads or more careful memory handling.
+- Google Sheets and LibreOffice can reinterpret dates, formulas, or styling differently from Excel.
+- Dynamic array or newer Excel functions like `FILTER`, `XLOOKUP`, `SORT`, or `SEQUENCE` may fail or degrade in older viewers.
+- A workbook can look fine while still carrying stale cached values from a prior recalculation.
+- Saving the wrong workbook view can replace formulas with cached values and quietly destroy a live model.
+- Copying formulas without checking relative references can push one bad range across an entire block.
+- Hidden sheets, named ranges, validations, and merged areas often keep business logic that is invisible in a quick skim.
+- A workbook can appear numerically correct while still failing because filters, conditional formats, print settings, or data validation were stripped.
+- A workbook can be numerically correct and still fail visually because wrapped text, clipped labels, or narrow columns were never reviewed.
+
+## Related Skills
+Install with `clawhub install <slug>` if user confirms:
+- `csv` — Plain-text tabular import and export workflows.
+- `data` — General data handling patterns before spreadsheet output.
+- `data-analysis` — Higher-level analysis that can feed workbook deliverables.
+
+## Feedback
+
+- If useful: `clawhub star excel-xlsx`
+- Stay updated: `clawhub sync`

package/skills/nano-pdf/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: nano-pdf
+description: "Edit PDFs with natural-language instructions using the nano-pdf CLI."
+homepage: https://pypi.org/project/nano-pdf/
+metadata: {"clawdbot":{"emoji":"📄","requires":{"bins":["nano-pdf"]},"install":[{"id":"uv","kind":"uv","package":"nano-pdf","bins":["nano-pdf"],"label":"Install nano-pdf (uv)"}]}}
+---
+
+# nano-pdf
+
+Use `nano-pdf` to apply edits to a specific page in a PDF using a natural-language instruction.
+
+## Quick start
+
+```bash
+nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in the subtitle"
+```
+
+Notes:
+- Page numbers are 0-based or 1-based depending on the tool's version/config; if the result looks off by one, retry with the other.
+- Always sanity-check the output PDF before sending it out.

package/skills/word-docx/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: Word / DOCX
+slug: word-docx
+version: 1.0.2
+homepage: https://clawic.com/skills/word-docx
+description: "Create, inspect, and edit Microsoft Word documents and DOCX files with reliable styles, numbering, tracked changes, tables, sections, and compatibility checks. Use when (1) the task is about Word or `.docx`; (2) the file includes tracked changes, comments, fields, tables, templates, or page layout constraints; (3) the document must survive round-trip editing without formatting drift."
+changelog: Tightened the skill around fragile review workflows, reference stability, and layout drift after a stricter external audit.
+metadata: {"clawdbot":{"emoji":"📘","os":["linux","darwin","win32"]}}
+---
+
+## When to Use
+
+Use when the main artifact is a Microsoft Word document or `.docx` file, especially when tracked changes, comments, headers, numbering, fields, tables, templates, or compatibility matter.
+
+## Core Rules
+
+### 1. Treat DOCX as OOXML, not plain text
+
+- A `.docx` file is a ZIP of XML parts, so structure matters as much as visible text.
+- The critical parts are usually `word/document.xml`, `styles.xml`, `numbering.xml`, headers, footers, and relationship files.
+- Text may be split across multiple runs; never assume one word or sentence lives in one XML node.
+- Use different workflows on purpose: structured extraction for quick reading, style-driven generation for new files, and OOXML-aware editing for fragile existing documents.
+- If the job is mainly reading, extracting, or reviewing, prefer a structure-preserving read path before touching OOXML.
+- For deep edits, inspect the package layout instead of relying only on rendered output.
+- Reading, generating, and preserving an existing reviewed document are different jobs even when the format is the same.
+- Legacy `.doc` inputs usually need conversion before you can trust modern `.docx` assumptions.
+
+### 2. Preserve styles and direct formatting deliberately
+
+- Prefer named styles over direct formatting so the document stays editable.
+- Styles layer: paragraph styles, character styles, and direct formatting do not behave the same.
+- Removing direct formatting is often safer than stacking more inline formatting on top.
+- When editing an existing file, extend the current style system instead of inventing a parallel one.
+- Copying content between documents can silently import foreign styles, theme settings, and numbering definitions.
+
+### 3. Lists and numbering are their own system
+
+- Bullets and numbering belong to Word's numbering definitions, not pasted Unicode characters.
+- `abstractNum`, `num`, and paragraph numbering properties all matter, so restart behavior is rarely "visual only".
+- Indentation and numbering are related but not identical; a list can have broken numbering even if the indent looks right.
+- A list that looks correct in one editor can restart, flatten, or renumber itself later if the underlying numbering state is wrong.
+
+### 4. Page layout lives in sections
+
+- Margins, orientation, headers, footers, and page numbering are section-level behavior.
+- First-page and odd/even headers can differ inside the same document, so one header fix may not fix the document.
+- Set page size explicitly because A4 and US Letter defaults change pagination and table widths.
+- Use section breaks for layout changes; manual spacing and stray page breaks usually create drift.
+- Header and footer media use part-specific relationships, so copied IDs often break images or links.
+- Tables, page breaks, and headers often drift together, so treat layout fixes as document-wide, not local cosmetic edits.
+- Table geometry depends on page width, margins, and fixed widths, so "close enough" table edits often break later in Google Docs or LibreOffice.
+
+### 5. Track changes, comments, and fields need precise edits
+
+- Visible text is not the full document when tracked changes are enabled.
+- Insertions, deletions, and comments carry metadata that can survive careless edits.
+- Deleted text may still exist in the XML even when it no longer appears on screen.
+- Comment anchors and review ranges can break if edits move text without preserving the surrounding structure.
+- Comment markers and review wrappers do not behave like inline formatting, so moving text carelessly can orphan or misplace them.
+- Comments, footnotes, bookmarks, and linked media may live in separate parts, not only in the main document body.
+- Tables of contents, page numbers, dates, cross-references, and mail merge placeholders are fields.
+- Edit the field source carefully and expect cached display values to lag until refresh.
+- Hyperlinks, bookmarks, and references can break if IDs or relationships stop matching.
+- Bookmarks, footnotes, comment ranges, and cross-references depend on stable anchors even when the visible text seems untouched.
+- A document can look correct while still containing stale field output that refreshes later into something different.
+- For review workflows, make minimal replacements instead of rewriting whole paragraphs.
+- In tracked-change workflows, only the changed span should look changed; broad rewrites create noisy reviews and can destroy the original formatting context.
+- For legal, academic, or business review documents, default to review-style edits over wholesale paragraph rewrites unless the user explicitly wants a rewrite.
+
+### 6. Verify round-trip compatibility before delivery
+
+- Complex documents can shift between Word, LibreOffice, Google Docs, and conversion tools.
+- Tables, headers, embedded fonts, and copied styles are common sources of layout drift.
+- Treat `.docm` as macro-bearing and higher risk; treat `.doc` as legacy input that may need conversion first.
+- When layout matters, explicit table widths are safer than auto-fit or percentage-style behavior that different editors reinterpret.
+- A document that passes a text check can still fail on pagination, table widths, or reference refresh after the recipient opens it.
+
+## Common Traps
+
+- Copy-paste can import unwanted styles and numbering definitions.
+- Header or footer images use part-specific relationships, so reusing IDs blindly breaks them.
+- Empty paragraphs used as spacing make templates fragile; spacing belongs in paragraph settings.
+- A clean-looking export can still hide unresolved revisions, comments, or stale field values.
+- Restarting lists "by eye" usually fails because numbering state lives outside the paragraph text.
+- One visible phrase can be split across several runs, bookmarks, revision tags, or field boundaries.
+- Replacing a whole paragraph to change one clause often breaks review quality, bookmarks, comments, or nearby inline formatting.
+- Deleting all visible text from a paragraph or list item can still leave behind an empty paragraph mark, empty bullet, or unstable numbering.
+- Table auto-fit and percentage-like width behavior can look acceptable in Word and still drift in Google Docs or LibreOffice.
+- LibreOffice and Google Docs can shift complex tables, section behavior, and embedded fonts even when Word looks perfect.
+- Compatibility mode can silently cap newer features or change pagination behavior.
+- A single change in page size or margin defaults can ripple through tables, headers, TOC, and cross-references.
+- A revision workflow can look accepted on screen while leftover metadata, comments, or field caches still make the file unstable later.
+- TOC entries, footnotes, and cross-references can look correct until the recipient updates fields and exposes broken anchors.
+
+## Related Skills
+Install with `clawhub install <slug>` if user confirms:
+- `documents` — General document handling and format conversion.
+- `brief` — Concise business writing and structured summaries.
+- `article` — Long-form drafting and editorial structure.
+
+## Feedback
+
+- If useful: `clawhub star word-docx`
+- Stay updated: `clawhub sync`

package/skills/playwright-mcp/SKILL.md

@@ -1,90 +0,0 @@
----
-name: playwright-mcp
-description: "Browser automation via Playwright MCP server. Use when the user needs to navigate websites, click elements, fill forms, extract data, take screenshots, or perform browser automation workflows."
----
-
-# Playwright MCP Skill
-
-Browser automation powered by Playwright MCP server.
-
-## Prerequisites
-
-Install the Playwright MCP server:
-
-```bash
-npm install -g @playwright/mcp
-npx playwright install chromium
-```
-
-## MCP Configuration
-
-Add to your `~/.til/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp", "--headless"]
-    }
-  }
-}
-```
-
-For headed mode (visible browser):
-```json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp"]
-    }
-  }
-}
-```
-
-## MCP Tools Reference
-
-| Tool | Description |
-|------|-------------|
-| `browser_navigate` | Navigate to URL |
-| `browser_click` | Click element by CSS selector or coordinates |
-| `browser_type` | Type text into input field |
-| `browser_select_option` | Select dropdown option |
-| `browser_get_text` | Get text content of element or page |
-| `browser_evaluate` | Execute JavaScript in page context |
-| `browser_snapshot` | Get accessible page snapshot (recommended before interactions) |
-| `browser_close` | Close browser context |
-| `browser_choose_file` | Upload file to input |
-| `browser_press` | Press keyboard key (Enter, Tab, etc.) |
-
-## Workflow
-
-1. **Navigate** to the target URL
-2. **Snapshot** to understand the page structure
-3. **Interact** with elements (click, type, select)
-4. **Extract** data or take screenshots as needed
-5. **Close** when done
-
-## Configuration Options
-
-| Flag | Description |
-|------|-------------|
-| `--allowed-hosts` | Restrict navigation to specific hosts |
-| `--blocked-origins` | Block specific origins |
-| `--browser` | Browser engine (chromium, firefox, webkit) |
-| `--headless` | Run without visible browser window |
-| `--viewport-size` | Set viewport dimensions (e.g. "1280x720") |
-| `--timeout-action` | Action timeout in ms |
-| `--timeout-navigation` | Navigation timeout in ms |
-| `--output-dir` | Directory for screenshots and traces |
-| `--save-trace` | Save Playwright trace file |
-| `--save-video` | Record browser session video |
-
-## Tips
-
-- Always use `browser_snapshot` before interacting with elements
-- Use CSS selectors for reliable element targeting
-- Set appropriate timeouts for slow-loading pages
-- Use `--headless` in CI/automation environments
-- Use `browser_evaluate` for complex page manipulation