skilltta-task-guidance
Task-specific operational guidance synthesized at test time from retrieved training examples.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- skilltta-task-guidance
- description
- Task-specific operational guidance synthesized at test time from retrieved training examples.
03 SKILL.md 正文
SKILL.md
When to use
Use this skill when a task requires OCR-based extraction of structured fields (e.g., dates, monetary totals) from a folder of scanned receipt/document images and writing results to a tabular file (Excel/CSV) with a strict schema. The binding contract specifies:
- The exact input directory and output file path.
- The exact sheet name, column names, column order, row ordering, and formatting of each field.
- Priority-ordered keyword rules for locating the target value and exclusion keywords to skip.
- A null policy when extraction fails.
- Exact evaluator comparison (line-by-line against an oracle), so any extra column/row/sheet or format drift fails.
Before acting, gather:
- The list and count of image files in the input directory (and their extensions).
- The task prompt's keyword priority list, exclusion list, and fallback rule (e.g., "last number on next line").
- The expected formats: ISO date (YYYY-MM-DD), amount as string with exactly two decimals, filename form.
- Which OCR/imaging libraries are pre-installed (do not install new ones unless allowed).
Possible Failure Modes
- Writing numeric totals as floats instead of strings with exactly two decimals (e.g.,
47.7instead of"47.70"), causing line-by-line mismatch. - Losing leading/trailing formatting: dropping the
.00, keeping currency symbols (RM,$), or keeping comma thousand-separators in the stored value (must parse1,234.56but store"1234.56"). - Picking up SUBTOTAL, TAX/GST/SST, DISCOUNT, CHANGE, or CASH TENDERED lines because exclusion keywords weren't checked before matching total keywords.
- Ignoring keyword priority: matching generic
TOTALbefore checking forGRAND TOTALorTOTAL RM, producing wrong amounts. - Failing the two-line fallback: when the keyword line has no number, not consulting the next line's last number.
- Date parsing pitfalls: ambiguous formats (DD/MM/YY vs MM/DD/YY), 2-digit years, OCR confusions (
O↔0,l↔1,S↔5), producing invalid ISO strings instead of null. - Not setting the field to null on failure — writing empty strings,
NaN, or"None"instead of a real null that pandas writes as an empty cell. - Row ordering: sorting by numeric value rather than lexicographic filename (or vice versa) when the contract says "ordered by filename".
- Producing extra sheets (pandas default
Sheet1), extra index column (forgettingindex=False), or extra columns from debug fields. - Wrong sheet name capitalization/spacing (must be exactly
results). - Iterating non-image files or hidden files in the directory; not filtering by extension.
- Using an OCR config that mangles digits — no preprocessing (thresholding, resize, grayscale) can hurt accuracy on low-quality scans.
- Not handling images that fail OCR at all (exceptions) — should degrade to null, not crash.
Possible procedures
- Enumerate inputs deterministically: list files in the input directory, filter to image extensions, and sort by filename (string sort) to guarantee stable output order.
- OCR each image:
- Open with PIL; consider grayscale conversion and mild upscaling for small images.
- Run
pytesseract.image_to_string. Split output into lines; keep original casing for debugging but compare uppercased for keyword matching.
- Extract total amount (respect priority):
- First pass: skip any line containing an exclusion keyword.
- Search in priority tiers: (a)
GRAND TOTAL, (b)TOTAL RM/TOTAL: RM, (c)TOTAL AMOUNT, (d) genericTOTAL,AMOUNT,TOTAL DUE,AMOUNT DUE,BALANCE DUE,NETT TOTAL,NET TOTAL. Stop at the highest-priority match found. - On the matched line, extract the last number matching a pattern like
\d{1,3}(,\d{3})*(\.\d+)?|\d+\.\d+. If none, look at the next non-empty line and take its last number (fallback rule). - Normalize: strip currency symbols, remove commas, cast to float, then format with
f"{value:.2f}"and store as string. - If nothing extracted, store
None.
- Extract date:
- Regex candidates for common receipt formats:
DD/MM/YYYY,DD-MM-YYYY,YYYY-MM-DD,DD MMM YYYY, etc. Try multiple patterns. - Validate with
datetime.strptimeand reformat toYYYY-MM-DD. - If parsing fails or ambiguous, store
None.
- Regex candidates for common receipt formats:
- Assemble DataFrame with exactly the required columns in the required order, sorted by filename.
- Write Excel with
openpyxlengine,sheet_name="results",index=False. Do not create any other sheets. Ensure thetotal_amountcolumn dtype is object/string so"47.70"is preserved literally. - Recovery on OCR/parse errors: wrap per-image processing in try/except; on any failure, still append a row with
Nonefor the failed field(s) rather than skipping the row.
Verification Checklist
- [ ] Output file exists at the exact required path; only one sheet with the exact required name.
- [ ] Columns are exactly
filename,date,total_amountin that order; no index column; no extra columns. - [ ] Row count equals number of image files in the input directory; rows sorted by filename ascending (string order).
- [ ]
datevalues are either validYYYY-MM-DDstrings or empty/null (neverNaT,"None", or malformed). - [ ]
total_amountvalues are strings with exactly two decimals, no currency prefix, no thousand separators (e.g.,"1234.56"), or empty/null on failure. - [ ] Exclusion keywords (SUBTOTAL, SUB TOTAL, TAX, GST, SST, DISCOUNT, CHANGE, CASH TENDERED) are never the source of extracted totals.
- [ ] Keyword priority is respected: more specific patterns override generic ones on the same receipt.
- [ ] Two-line fallback is implemented and used when the keyword line lacks a numeric value.
- [ ] Nothing from retrieved examples (unrelated Faker/CSV/histogram code) leaked into the solution.
- [ ] Unrelated files in the workspace are untouched; only the required output file is created/overwritten.
- [ ] Re-open the produced Excel with pandas to confirm sheet name, headers, dtypes (total_amount as string), and row order before finishing.
04 同仓库更多 Skills
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms