Skip to content
Back to search

uap-release-analyzer

A Claude skill for analyzing tranches of declassified UAP/UFO documents (war.gov PURSUE, FBI Vault, NARA, AARO). Inventory + text extraction + entity surfacing + standardized 11-section REPORT.md.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ckpxgfnksd-max--uap-release-analyzer/badge.svg)](/listings/ckpxgfnksd-max--uap-release-analyzer)

HTML

<a href="/listings/ckpxgfnksd-max--uap-release-analyzer"><img src="/api/listings/ckpxgfnksd-max--uap-release-analyzer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Inside Claude Code (per-user skills directory)
git clone https://github.com/ckpxgfnksd-max/uap-release-analyzer.git \
  ~/.claude/skills/uap-release-analyzer

Or package via `skill-creator`:

python -m scripts.package_skill /path/to/uap-release-analyzer
# produces uap-release-analyzer.skill — install via Claude Code UI

Dependencies: `pdfplumber`, `pypdf`. Install via `pip install pdfplumber pypdf`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 127 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: uap-release-analyzer
  3. description: Inventory, extract, and analyze tranches of declassified UAP/UFO files — including war.gov/UFO/ "PURSUE" releases, FBI Vault, NARA boxes, and AARO publications. Use this skill whenever the user points at a folder of UAP/UFO/declassified PDFs, asks "what's in this release?", references war.gov/UFO/, AARO, PURSUE, FOIA tranches, FBI 62-HQ-83894, or asks for keyword/entity/redaction analysis across a corpus of declassified documents — even if they don't explicitly ask for an "analysis." Also triggers on requests to compare tranches, summarize a single declassified PDF, classify documents by agency, or surface (b)(1)/(b)(6)/NOFORN redaction patterns. Produces a standardized inventory.csv, per-file digest, entities.json, and REPORT.md.
  4. license: Complete terms in LICENSE.txt
  5. ---
  6. # UAP / Declassified Release Analyzer
  7. This skill turns a folder of declassified UAP/UFO documents into a structured analytic report. It was built from a real workflow against the May 2026 war.gov/UFO/ "PURSUE" tranche (162 files, 4,000+ pages, mixed FBI/DOW/NASA/DOS/NARA sources), so it's tuned to the quirks of that universe — but it generalizes to any tranche of FOIA-released government PDFs.
  8. ## When to use
  9. Trigger on prompts like "analyze the UFO files I just downloaded", "build me a report on this UAP release", "what's in `~/Downloads/release_01/`?", "compare release 1 and release 2", "find redaction patterns in these FBI files", "summarize this AARO PDF", or whenever the user references a directory of declassified documents and wants any kind of summary, inventory, or pattern surfacing. Also trigger if the user just dumps a path and asks "what's interesting in here?" — this skill is the right tool.
  10. ## Why a skill
  11. The work has a fixed shape that repeats across every new tranche:
  12. 1. Inventory — what files came down, sizes, page counts, which agency.
  13. 2. Text extraction — pull text where there is a text layer; flag the (often majority) of files that are scanned and need OCR.
  14. 3. Entity surfacing — locations, agencies, phenomena vocabulary, named people.
  15. 4. Redaction pattern analysis — which FOIA exemptions show up where, which files are most redacted.
  16. 5. Cross-document patterns — year clusters, agency × location heatmap, names that appear in 5+ files.
  17. 6. A standardized report the user can read in ten minutes.
  18. Doing this freshly every time wastes effort and produces inconsistent outputs. The bundled scripts make every tranche analyzable the same way.
  19. ## The standard workflow
  20. Run scripts in this order. Each writes intermediate artifacts that the next step consumes. They are **idempotent and incremental** — re-running on the same folder skips work that's already done.
  21. ```
  22. release_root/
  23. release_NN/ # the actual PDFs/PNGs/JPGs (input)
  24. text/ # extracted text per PDF (created)
  25. inventory.csv # one row per file (created)
  26. analytics/ # aggregated outputs (created)
  27. top_terms.csv
  28. terms_by_agency.csv
  29. entities.json
  30. per_file_digest.csv
  31. cross_doc.json
  32. REPORT.md # human-readable analytic writeup (created)
  33. ```
  34. **Step 1 — Inventory.** Run `scripts/inventory.py <release_root>`. This walks the release directory, classifies each file by filename prefix (see `references/agency_vocab.md`), reads PDF page counts, and writes `inventory.csv`. Don't write inventory by hand — the script handles encrypted PDFs, weird filenames with spaces or em-dashes, and files that pypdf can't open.
  35. **Step 2 — Text extraction.** Run `scripts/extract_text.py <release_root> [start] [end]`. Extracts text via pdfplumber, writing one `.txt` per PDF into `text/`. Skips files that already have a non-empty `.txt`. Many FBI / NARA / older photo-PDFs have **no text layer** — those will produce 0-char files; that's expected and fine, the analytics treat them as "scanned, OCR needed". The optional `[start] [end]` slice arguments let you process in chunks if your sandbox has a per-call timeout (the war.gov FBI sections are 200+ pages each — extract them in batches of ~25 if running in a 45-second-call environment).
  36. **Run scripts in the foreground of your turn**, not via background-and-end-turn patterns. The pipeline is fast enough (a few minutes from cold) that you can stay in-turn. If a single `extract_text.py` call would actually time out, prefer the `[start] [end]` chunking pattern over backgrounding — chunked calls each finish quickly, the script is idempotent, and progress is visible.
  37. **Step 3 — Analytics.** Run `scripts/analyze.py <release_root>`. Reads the extracted text + inventory, then writes the contents of `analytics/`. This is fast even on 800K+ characters of text.
  38. **Step 4 — Report.** Run `scripts/build_report.py <release_root>`. Reads inventory + analytics and writes a `REPORT.md` with the sections listed under "Report structure" below.
  39. When the user just says "analyze the release at `<path>`", run all four in sequence with that path. When they ask a narrower question ("how many files?", "which file is most redacted?"), call only the relevant script or read the existing artifacts directly.
  40. ## Report structure
  41. Always use this exact section order in `REPORT.md` so reports across tranches stay comparable. If a section has no data for this tranche, leave a one-line "no data" note — don't omit the heading.
  42. ```
  43. # <Release name> — Raw Analytics
  44. **Source:** ... · **Cleared for release:** ...
  45. **Files in this analysis:** N of M (note any gaps)
  46. ## 1. Inventory — counts, total size, page counts, by agency
  47. ## 2. What's actually in the release — narrative summary of the major buckets
  48. ## 3. Where the activity is concentrated — top locations
  49. ## 4. Phenomena terminology — UAP/craft/orb/disc/etc. with counts
  50. ## 5. Agency cross-references — agencies named in text
  51. ## 6. Year clusters — when is this material from
  52. ## 7. Redactions — top markers + most-redacted files
  53. ## 8. Notable individual files
  54. ## 9. Cross-document patterns
  55. ## 10. What's missing / caveats — OCR gaps, files we couldn't pull, etc.
  56. ## 11. Files in this analysis — paths to inventory.csv / analytics/*
  57. ```
  58. The "What's missing" section matters — it's what makes the report honest. Always call out files we couldn't OCR, files referenced on a source page but not downloaded, and heuristic limits of the entity extraction.
  59. ## Agency classification
  60. Files are classified by filename prefix. The full vocabulary is in `references/agency_vocab.md`. The high-confidence prefixes from the war.gov universe:
  61. - `65_hs1*`, `fbi-photo-*`, `usper-*`, `serial*`, `2024-04-30-*` → FBI
  62. - `dow-uap*`, `western_us_event*` → DOW (Department of War)
  63. - `nasa-uap*` → NASA
  64. - `dos-uap*`, `059uap*` → DOS (State)
  65. - `18_*`, `38_*`, `59_*`, `255*`, `331_*`, `341_*`, `342_*` → NARA (record-group prefixes)
  66. - otherwise → OTHER (flag for the user; might be a new bucket worth adding to the vocab)
  67. If you encounter a tranche with prefixes not in the vocab, add them to `references/agency_vocab.md` (the table) and `scripts/inventory.py` + `scripts/analyze.py` (`PREFIX_RULES`) rather than scattering inline filename checks across scripts. A useful threshold: if `OTHER` exceeds ~3% of files in any tranche, that's a signal the vocab needs extending, not the data being weird.
  68. When bootstrapping a brand-new tranche (e.g., the user has just downloaded `release_02/` and asks "what's the fastest way to a written report?"), surface this vocab-extension workflow in your reply alongside `run_all.py`. Otherwise the user will discover the OTHER bucket only after the fact.
  69. ## FOIA / classification markers
  70. `references/foia_codes.md` lists the FOIA exemptions and classification stamps to look for. Most of the meaningful redaction signal in modern tranches comes from `(b)(1)` (national security), `(b)(3)` (statutory), `(b)(6)` (personal privacy), and the classification banners `SECRET//NOFORN`, `REL TO USA`, `CUI`, `FOUO`. The analyzer counts these by file so the report can name the most-redacted documents.
  71. ## Pulling files from war.gov/UFO/ (PURSUE releases)
  72. If the user wants to pull from the source page rather than analyzing files they already have, see `references/war_gov_quirks.md`. It documents the things that bit us on the first run: the page renders 10 records per page across paginated DOM, the "Download" button is hooked through `<a download>`-style behavior so URLs are only available after the modal opens, ~28 of 162 records are served via inline viewer (no clean URL), and `www.war.gov` is typically not on a workspace egress allowlist (you'll need browser-driven downloads or a one-time allowlist). Don't reinvent the scrape — check the reference first.
  73. ## Working with the user
  74. - **Start narrow.** Ask for the path if they didn't give one. Don't guess.
  75. - **Show progress.** Tranches are big (the May 2026 release was 2.5 GB / 4,000 pages); print `[N/total]` lines as you go so the user isn't flying blind.
  76. - **Don't run OCR by default.** Tesseract on 4,000 scanned pages takes hours. Note the gap in the "What's missing" section and offer OCR as a follow-up.
  77. - **Surface cross-tranche links** if the user has more than one release in the parent folder — a sibling `release_02/` makes "what's new vs. release_01?" the obvious next question.
  78. - **Honest caveats.** Entity extraction here is keyword-list + regex, not full NER. Year mentions ≠ incident dates. Say so in the report.
  79. ## Bundled scripts
  80. - `scripts/inventory.py <release_root>` — build inventory.csv
  81. - `scripts/extract_text.py <release_root> [start] [end]` — extract text in optional chunks
  82. - `scripts/analyze.py <release_root>` — write analytics/
  83. - `scripts/build_report.py <release_root>` — write REPORT.md
  84. - `scripts/run_all.py <release_root>` — convenience: run the four in order
  85. ## Bundled references
  86. - `references/agency_vocab.md` — filename-prefix → agency rules
  87. - `references/foia_codes.md` — FOIA exemptions and classification stamps
  88. - `references/war_gov_quirks.md` — how war.gov/UFO/ is structured + scraping notes
  89. Read references on demand. Don't preload them into context unless the user's question is in their domain.
README.md · README · 115 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # uap-release-analyzer
  2. A Claude Code / Claude.ai skill that turns a folder of declassified UAP/UFO documents — war.gov "PURSUE" releases, FBI Vault tranches, NARA boxes, AARO publications — into a structured analytic report.
  3. ## What it does
  4. Run it against a release directory (e.g. `~/Documents/UFO/release_01/`) and it produces:
  5. - `inventory.csv` — one row per file: agency (inferred from filename prefix), document type, page count, size
  6. - `text/*.txt` — extracted text via pdfplumber, with empty files flagged for the (often majority) of files that are scanned with no text layer
  7. - `analytics/`
  8. - `top_terms.csv`, `terms_by_agency.csv` — token frequencies
  9. - `entities.json` — locations, agencies, phenomena vocabulary, year clusters, names appearing in 5+ files
  10. - `per_file_digest.csv` — top terms / locations / redactions / 2-sentence summary per file
  11. - `cross_doc.json` — redaction patterns, agency totals, scanned-vs-text split
  12. - `REPORT.md` — 11-section human-readable analytic writeup
  13. The four scripts are idempotent and incremental — re-running on the same folder skips work that's already done.
  14. ## Installation
  15. ```bash
  16. # Inside Claude Code (per-user skills directory)
  17. git clone https://github.com/ckpxgfnksd-max/uap-release-analyzer.git \
  18. ~/.claude/skills/uap-release-analyzer
  19. ```
  20. Or package via `skill-creator`:
  21. ```bash
  22. python -m scripts.package_skill /path/to/uap-release-analyzer
  23. # produces uap-release-analyzer.skill — install via Claude Code UI
  24. ```
  25. Dependencies: `pdfplumber`, `pypdf`. Install via `pip install pdfplumber pypdf`.
  26. ## Layout
  27. ```
  28. uap-release-analyzer/
  29. ├── SKILL.md # frontmatter + workflow
  30. ├── scripts/
  31. │ ├── inventory.py
  32. │ ├── extract_text.py
  33. │ ├── analyze.py
  34. │ ├── build_report.py
  35. │ └── run_all.py # convenience: run the four in order
  36. ├── references/
  37. │ ├── agency_vocab.md # filename-prefix → agency rules
  38. │ ├── foia_codes.md # FOIA exemptions and classification stamps
  39. │ └── war_gov_quirks.md # how war.gov/UFO/ is structured + scraping notes
  40. ├── evals/evals.json # 4 test cases used to iterate the skill
  41. ├── ARTICLE.md # development notes (English)
  42. ├── ARTICLE_CN.md # 中文版开发笔记
  43. └── LICENSE.txt
  44. ```
  45. ## Usage
  46. ```bash
  47. # One-shot: full pipeline
  48. python scripts/run_all.py ~/Documents/UFO/release_01/
  49. # Or step-by-step (inventory and extract are the slow parts; both are idempotent)
  50. python scripts/inventory.py ~/Documents/UFO/release_01/
  51. python scripts/extract_text.py ~/Documents/UFO/release_01/ # all files
  52. python scripts/extract_text.py ~/Documents/UFO/release_01/ 0 25 # chunked
  53. python scripts/analyze.py ~/Documents/UFO/release_01/
  54. python scripts/build_report.py ~/Documents/UFO/release_01/
  55. ```
  56. ## Example dataset
  57. The May 2026 war.gov "PURSUE" release this skill was tuned against is mirrored at [`ckpxgfnksd-max/uap-release-01`](https://github.com/ckpxgfnksd-max/uap-release-01) (Git LFS, **~3.7 GB / 160 files**: 118 PDFs, 28 MP4 videos, 14 images). Clone it as your `release_01/` to reproduce the eval scoreboard:
  58. ```bash
  59. git lfs install # one-time
  60. git clone https://github.com/ckpxgfnksd-max/uap-release-01.git ~/Documents/UFO/release_01
  61. python scripts/run_all.py ~/Documents/UFO/release_01
  62. ```
  63. Or fetch only the buckets you care about:
  64. ```bash
  65. GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/ckpxgfnksd-max/uap-release-01.git ~/Documents/UFO/release_01
  66. cd ~/Documents/UFO/release_01
  67. git lfs pull --include "dow-uap-*.pdf" # text-bearing DOW mission report PDFs
  68. git lfs pull --include "dow-uap-pr*.mp4" # 27 DOW Unresolved-Report videos (1.3 GB)
  69. git lfs pull --include "65_hs1*" # heavy FBI scanned sections
  70. ```
  71. The 28 videos in the corpus aren't analyzed by this skill — `analyze.py` only reads PDF text. They're mirrored for completeness so future video-aware analysis (e.g., scene-classification or transcript extraction) has a stable input set. The skill flags any non-PDF file as `(image file — vision analysis required)` or similar in `per_file_digest.csv` and skips it for text analytics.
  72. ## Eval scoreboard (iteration-1)
  73. | Eval | with skill | baseline | Δ |
  74. |---|---|---|---|
  75. | Full-tranche walkthrough | 100% | 60% | +40 |
  76. | Single-file summary | 100% | 100% | 0 |
  77. | Scanned-tranche honest caveats | 100% | 88% | +12 |
  78. | Fresh-tranche bootstrap | 88% | 50% | +38 |
  79. | **Mean** | **97%** | **74%** | **+23** |
  80. See `ARTICLE.md` for the build story and the bugs the eval surfaced.
  81. ## Honest caveats
  82. - Entity extraction is keyword-list + regex, not full NER. Year mentions ≠ incident dates.
  83. - Scanned PDFs (no text layer) produce 0-char `.txt` files by design — the analyzer treats them as "OCR needed" rather than running OCR (multi-hour). Run Tesseract as a follow-up if you need that content searchable.
  84. - The agency vocabulary is tuned to the May 2026 war.gov tranche. New tranches with new prefixes should be added to `references/agency_vocab.md` and `scripts/inventory.py PREFIX_RULES`.
  85. ## License
  86. MIT. See `LICENSE.txt`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.