Skip to content
Back to search

claude-skills-journalism

MarketplaceWorks with Claude CodeGitHub

Agent skills and Claude Code plugins for journalism, research, and media organizations

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jamditis/claude-skills-journalism with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jamditis/claude-skills-journalism'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jamditis-claude-skills-journalism/badge.svg)](/listings/jamditis-claude-skills-journalism)

HTML

<a href="/listings/jamditis-claude-skills-journalism"><img src="/api/listings/jamditis-claude-skills-journalism/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

Choose the section for your client. During the Codex pilot, use only one Codex installation path for a given skill or package.

Claude Code

**Prerequisite:** You need [Claude Code](https://code.claude.com/docs/en/overview) installed. Run `claude --version` in your terminal to check.

Plugins (recommended)

Plugins bundle skills and, where provided, commands, agents, or hooks. The table below lists each package’s commands. Run these two commands inside a Claude Code session:

/plugin marketplace add jamditis/claude-skills-journalism
/plugin install pdf-playground@claude-skills-journalism

Then restart Claude Code (close and reopen). See the [PDF Playground README](./pdf-playground/) for detailed setup instructions and troubleshooting.

**Available plugins:**

| Plugin | Description | Commands | Updated | |--------|-------------|----------|--------| | [autocontext](./autocontext/) | Cross-session knowledge persistence with skill evolution. Lessons accumulate per-skill, and `/autocontext:evolve` folds them back into skill files | `/autocontext:setup`, `/autocontext:init`, `/autocontext:review`, `/autocontext:status`, `/autocontext:evolve` | Nov 4, 2026 | | [dev-toolkit](./dev-toolkit/) | Fourteen development-focused skills for journalists, researchers, and small newsroom dev teams: accessibility, context management, minimal-code implementation, UI completeness, directed multi-agent execution, Electron, mobile debugging, Python pipelines, ethical scraping, no-build frontends, web UI craft, and project instruction maintenance | `/dev-toolkit:director`; other skills model-selected | Nov 4, 2026 | | [journalism-core](./journalism-core/) | Sixteen core journalism skills, including AP-style writing, AI-slop detoxing, source verification (deepfakes/C2PA), FOIA + NJ OPRA requests, Brazilian LAI requests, fact-checking, interview prep, transcription + meeting actions, story pitches, editorial workflow, crisis communications, newsletter publishing with current Gmail / Yahoo / Outlook bulk-sender requirements, and embedded photo metadata for wire distribution | n/a, skills only | Nov 4, 2026 | | [newsroom-agent-ops](./newsroom-agent-ops/) | Nine skills for safe recurring newsroom work: unattended runs, briefings, intake, delivery, coordination, reconciliation, chat triage, deadline tracking, and issue progression | n/a, skills only | Nov 4, 2026 | | [okf-wiki](./okf-wiki/) | Scaffold an Open Knowledge Format (OKF) knowledge base: one-concept-per-file markdown with YAML frontmatter, directory navigation, and a validator. Generates a starter wiki that passes its own conformance and secret-leak checks, ships session-start hooks that orient Claude on the knowledge base before it works, and includes an optional GitHub-wiki bootstrap. For newsroom institutional memory, research atlases, decision logs, and infrastructure maps | n/a, skill only | Nov 4, 2026 | | [pdf-design](./pdf-design/) | PDF report and proposal design system with brand variables, budget tables, and reusable content blocks (stats strips, three-column, four-tile pillars, partner grids) | n/a, skill-only | Nov 4, 2026 | | [pdf-playground](./pdf-playground/) | Create branded proposals, reports, one-pagers, newsletters, slides, and event materials with an interactive control panel for live design editing (colors, fonts, spacing, sections) and a guided wizard for proposals | `/pdf-playground:proposal`, `/pdf-playground:report`, `/pdf-playground:onepager`, `/pdf-playground:newsletter`, `/pdf-playground:slides`, `/pdf-playground:event`, `/pdf-playground:preview` | Nov 4, 2026 | | [project-templates-toolkit](./project-templates-toolkit/) | Four skills for setting up, tracking, and closing out journalism projects: a project instruction writer (institutional knowledge), a LESSONS.md retrospective writer (failures and decisions), a template-selector decision tree across 6 project types, and an evidence-based weighted progress tracker | n/a, skills only | Nov 4, 2026 |

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.

.claude-plugin/marketplace.json · Manifest · 165 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": "claude-skills-journalism",
  3. "version": "2.9.0",
  4. "description": "Agent skills and Claude Code plugins for journalism, research, and media organizations",
  5. "owner": {
  6. "name": "Joe Amditis",
  7. "email": "jamditis@gmail.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "autocontext",
  12. "description": "Accumulates project knowledge across sessions and developers through structured lessons and hooks",
  13. "version": "1.1.2",
  14. "author": {
  15. "name": "Joe Amditis",
  16. "email": "jamditis@gmail.com"
  17. },
  18. "source": "./autocontext",
  19. "category": "Productivity"
  20. },
  21. {
  22. "name": "dev-toolkit",
  23. "description": "Fourteen development skills for newsroom and research dev teams: accessibility, context management, minimal-code implementation, UI completeness, directed multi-agent execution, Electron, mobile debugging, Python pipelines, ethical scraping, no-build frontends, web UI craft, and project instruction maintenance.",
  24. "version": "2.1.1",
  25. "author": {
  26. "name": "Joe Amditis",
  27. "email": "jamditis@gmail.com"
  28. },
  29. "source": "./dev-toolkit",
  30. "category": "Development"
  31. },
  32. {
  33. "name": "journalism-core",
  34. "description": "Sixteen core journalism skills for reporting, verification, publishing, and digital investigations: AP-style writing, AI-slop detox, source verification, FOIA/OPRA and Brazilian LAI requests, fact-checking, interview prep, transcription and meeting actions, story pitches, editorial workflow, crisis comms, newsletter publishing, data journalism, social-media OSINT, and embedded photo metadata.",
  35. "version": "1.7.0",
  36. "author": {
  37. "name": "Joe Amditis",
  38. "email": "jamditis@gmail.com"
  39. },
  40. "source": "./journalism-core",
  41. "category": "Journalism"
  42. },
  43. {
  44. "name": "newsroom-agent-ops",
  45. "description": "Nine skills for safe recurring newsroom agent work: unattended runs, briefings, intake, delivery, coordination, reconciliation, chat triage, deadline tracking, and issue progression.",
  46. "version": "1.0.0",
  47. "author": {
  48. "name": "Joe Amditis",
  49. "email": "jamditis@gmail.com"
  50. },
  51. "source": "./newsroom-agent-ops",
  52. "category": "Productivity"
  53. },
  54. {
  55. "name": "okf-wiki",
  56. "description": "Scaffold an Open Knowledge Format (OKF) knowledge base from docs, plans, notes, or a repo: one-concept-per-file Markdown with YAML frontmatter, navigation, and validation. Built for newsroom memory, research atlases, decision logs, and infrastructure maps.",
  57. "version": "0.8.4",
  58. "author": {
  59. "name": "Joe Amditis",
  60. "email": "jamditis@gmail.com"
  61. },
  62. "source": "./okf-wiki",
  63. "category": "Productivity"
  64. },
  65. {
  66. "name": "pdf-design",
  67. "description": "PDF report and proposal design system with interactive editing",
  68. "version": "1.1.4",
  69. "author": {
  70. "name": "Joe Amditis",
  71. "email": "jamditis@gmail.com"
  72. },
  73. "source": "./pdf-design",
  74. "category": "Design"
  75. },
  76. {
  77. "name": "pdf-playground",
  78. "description": "Interactive playground for creating and testing PDF reports and proposals",
  79. "version": "1.3.8",
  80. "author": {
  81. "name": "Joe Amditis",
  82. "email": "jamditis@gmail.com"
  83. },
  84. "source": "./pdf-playground",
  85. "category": "Productivity"
  86. },
  87. {
  88. "name": "project-templates-toolkit",
  89. "description": "Four skills for starting, tracking, and closing out journalism projects: a project-instruction writer, a LESSONS.md retrospective writer, a template-selector decision tree for editorial tools, events, publications, research, pipelines, and archives, and an evidence-based weighted progress tracker.",
  90. "version": "1.1.1",
  91. "author": {
  92. "name": "Joe Amditis",
  93. "email": "jamditis@gmail.com"
  94. },
  95. "source": "./project-templates-toolkit",
  96. "category": "Productivity"
  97. },
  98. {
  99. "name": "research-toolkit",
  100. "description": "Six skills for research, source preservation, and academic workflows: academic writing, legal paywall bypass (Unpaywall, library databases), web archiving (Wayback, Archive.today, ArchiveBox), page-change monitoring, AI-enriched digital archives, and a curated free-API catalog.",
  101. "version": "1.1.4",
  102. "author": {
  103. "name": "Joe Amditis",
  104. "email": "jamditis@gmail.com"
  105. },
  106. "source": "./research-toolkit",
  107. "category": "Research"
  108. },
  109. {
  110. "name": "security-toolkit",
  111. "description": "Five defensive security skills covering OWASP Top 10, supply-chain hardening, and secret scanning: pre-deployment audit checklists, secure authentication (hashing, sessions, JWT, OAuth, passkeys), API hardening (rate limiting, CORS, throttling), npm/bun install-time cooldown with a sandboxed bypass scan, and local Gitleaks scans for private repositories.",
  112. "version": "1.3.0",
  113. "author": {
  114. "name": "Joe Amditis",
  115. "email": "jamditis@gmail.com"
  116. },
  117. "source": "./security-toolkit",
  118. "category": "Security"
  119. },
  120. {
  121. "name": "superjawn",
  122. "description": "Research-augmented fork of obra/superpowers. Ships 13 workflow skills (brainstorming, planning, code review, debugging, verification, worktrees, parallel agents) standalone, with no dependency on the upstream superpowers plugin.",
  123. "version": "2.1.0",
  124. "author": {
  125. "name": "Joe Amditis",
  126. "email": "jamditis@gmail.com"
  127. },
  128. "source": "./superjawn",
  129. "category": "Productivity"
  130. },
  131. {
  132. "name": "video-toolkit",
  133. "description": "Four composable skills for social-video accountability reporting: downloading public video from X, TikTok, YouTube, Instagram, and Facebook, transcribing it with a provenance record, extracting and vision-analyzing frames, and building an interactive dashboard.",
  134. "version": "1.0.6",
  135. "author": {
  136. "name": "Joe Amditis",
  137. "email": "jamditis@gmail.com"
  138. },
  139. "source": "./video-toolkit",
  140. "category": "Journalism"
  141. },
  142. {
  143. "name": "web-design-picker",
  144. "description": "Build distinct website directions, a client review picker, asset catalog, previews, and Cloudflare-ready handoff packages.",
  145. "version": "1.0.1",
  146. "author": {
  147. "name": "Joe Amditis",
  148. "email": "jamditis@gmail.com"
  149. },
  150. "source": "./web-design-picker",
  151. "category": "Design"
  152. },
  153. {
  154. "name": "visual-explainer",
  155. "description": "HTML diagrams, data tables, and architecture views adapted from nicobailon/visual-explainer with newsroom and academic design sensibilities. Generates self-contained pages with Mermaid diagrams, KPI cards, slide decks, and zoom/pan controls.",
  156. "version": "0.7.5",
  157. "author": {
  158. "name": "Joe Amditis",
  159. "email": "jamditis@gmail.com"
  160. },
  161. "source": "./visual-explainer",
  162. "category": "Design"
  163. }
  164. ]
  165. }
README.md · README · 492 lines

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

  1. # Journalism agent skills
  2. [Project: Journalism skills maintenance](https://github.com/users/jamditis/projects/6)
  3. A collection of Agent Skills for journalists, researchers, academics, media professionals, and communications practitioners. The same repository serves Claude Code and Codex while keeping Claude-only commands, agents, and hooks clearly labeled.
  4. **Docs site:** [skills.amditis.tech](https://skills.amditis.tech), interactive skill browser, setup guides, and full documentation.
  5. ## Guides
  6. Setup and workflow guides, separate from the skills themselves:
  7. | Guide | Description |
  8. |-------|-------------|
  9. | [The Codex review setup I run](https://codex.amditis.tech/) | Code-review setup, everyday workflow, and model-routing notes |
  10. | [Autonomous and hands-on dev work](https://skills.amditis.tech/autonomy/) | A first-person account of running dev work with Claude in two modes, autonomous sessions that pull tasks off GitHub issues, and hands-on multi-agent reviews at the keyboard, held to one quality bar, with copy-able prompts to adapt the approach to your own agent |
  11. | [Multi-agent workflows](https://skills.amditis.tech/workflows/) | Plain-language guide to running many AI agents on one job, fan-out, pipeline, and adversarial-verify patterns, with real examples from ICIJ, The Markup, Full Fact, and Elicit, plus honest cautions |
  12. | [Dot skills](https://skills.amditis.tech/dot-skills/) | An unofficial workshop for ChatGPT dots, OpenAI's always-on agents: Markdown playbooks for status cards, incident updates, visual audits, and source evidence, a small progress-tracker lab, and honest field notes. There is no dot marketplace yet, so these are shared here |
  13. | [A month with two ChatGPT dots](https://skills.amditis.tech/dot-skills/field-report/) | A first-person field report on running two dots in newsroom Slack workspaces: repeated approvals, daily computer crashes, a message sent from the wrong account, the Blender work that surprised me, and the skills that kept them usable |
  14. | [Persistent sessions](https://skills.amditis.tech/persistent-sessions/) | Keep Claude Code sessions alive through disconnects using tmux, setup, key bindings, activity notifications, and scheduler coexistence |
  15. ## What are agent skills?
  16. Skills are modular instruction sets that an AI coding agent loads when relevant to a task. Each skill contains domain knowledge, workflows, templates, and supporting files. Shared skills in this repository follow the [Agent Skills specification](https://agentskills.io/specification); Claude and Codex provide their own installation and runtime layers around that shared content.
  17. ## Repository control plane
  18. [`skills-catalog.yaml`](./skills-catalog.yaml) lists every package and stable
  19. skill. It records each skill's package, path, lifecycle, and invocation mode.
  20. The defaults preserve the existing model-selected invocation behavior.
  21. Each stable skill includes `agents/openai.yaml` for Codex display metadata.
  22. These files do not change invocation policy. Run `npm run validate:catalog` to
  23. check catalog coverage, package mappings, skill names, and metadata files.
  24. See [INFLUENCES.md](./INFLUENCES.md) and
  25. [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for design credit and
  26. license notices.
  27. ## Installation
  28. Choose the section for your client. During the Codex pilot, use only one Codex installation path for a given skill or package.
  29. ### Claude Code
  30. **Prerequisite:** You need [Claude Code](https://code.claude.com/docs/en/overview) installed. Run `claude --version` in your terminal to check.
  31. #### Plugins (recommended)
  32. Plugins bundle skills and, where provided, commands, agents, or hooks. The table below lists each package’s commands. Run these two commands inside a Claude Code session:
  33. ```
  34. /plugin marketplace add jamditis/claude-skills-journalism
  35. /plugin install pdf-playground@claude-skills-journalism
  36. ```
  37. Then restart Claude Code (close and reopen). See the [PDF Playground README](./pdf-playground/) for detailed setup instructions and troubleshooting.
  38. **Available plugins:**
  39. | Plugin | Description | Commands | Updated |
  40. |--------|-------------|----------|--------|
  41. | [autocontext](./autocontext/) | Cross-session knowledge persistence with skill evolution. Lessons accumulate per-skill, and `/autocontext:evolve` folds them back into skill files | `/autocontext:setup`, `/autocontext:init`, `/autocontext:review`, `/autocontext:status`, `/autocontext:evolve` | Nov 4, 2026 |
  42. | [dev-toolkit](./dev-toolkit/) | Fourteen development-focused skills for journalists, researchers, and small newsroom dev teams: accessibility, context management, minimal-code implementation, UI completeness, directed multi-agent execution, Electron, mobile debugging, Python pipelines, ethical scraping, no-build frontends, web UI craft, and project instruction maintenance | `/dev-toolkit:director`; other skills model-selected | Nov 4, 2026 |
  43. | [journalism-core](./journalism-core/) | Sixteen core journalism skills, including AP-style writing, AI-slop detoxing, source verification (deepfakes/C2PA), FOIA + NJ OPRA requests, Brazilian LAI requests, fact-checking, interview prep, transcription + meeting actions, story pitches, editorial workflow, crisis communications, newsletter publishing with current Gmail / Yahoo / Outlook bulk-sender requirements, and embedded photo metadata for wire distribution | n/a, skills only | Nov 4, 2026 |
  44. | [newsroom-agent-ops](./newsroom-agent-ops/) | Nine skills for safe recurring newsroom work: unattended runs, briefings, intake, delivery, coordination, reconciliation, chat triage, deadline tracking, and issue progression | n/a, skills only | Nov 4, 2026 |
  45. | [okf-wiki](./okf-wiki/) | Scaffold an Open Knowledge Format (OKF) knowledge base: one-concept-per-file markdown with YAML frontmatter, directory navigation, and a validator. Generates a starter wiki that passes its own conformance and secret-leak checks, ships session-start hooks that orient Claude on the knowledge base before it works, and includes an optional GitHub-wiki bootstrap. For newsroom institutional memory, research atlases, decision logs, and infrastructure maps | n/a, skill only | Nov 4, 2026 |
  46. | [pdf-design](./pdf-design/) | PDF report and proposal design system with brand variables, budget tables, and reusable content blocks (stats strips, three-column, four-tile pillars, partner grids) | n/a, skill-only | Nov 4, 2026 |
  47. | [pdf-playground](./pdf-playground/) | Create branded proposals, reports, one-pagers, newsletters, slides, and event materials with an interactive control panel for live design editing (colors, fonts, spacing, sections) and a guided wizard for proposals | `/pdf-playground:proposal`, `/pdf-playground:report`, `/pdf-playground:onepager`, `/pdf-playground:newsletter`, `/pdf-playground:slides`, `/pdf-playground:event`, `/pdf-playground:preview` | Nov 4, 2026 |
  48. | [project-templates-toolkit](./project-templates-toolkit/) | Four skills for setting up, tracking, and closing out journalism projects: a project instruction writer (institutional knowledge), a LESSONS.md retrospective writer (failures and decisions), a template-selector decision tree across 6 project types, and an evidence-based weighted progress tracker | n/a, skills only | Nov 4, 2026 |
  49. | [research-toolkit](./research-toolkit/) | Six skills for research, source preservation, and academic workflows: academic writing, legal paywall-bypass via Unpaywall and library databases, web archiving (Wayback / Archive.today / ArchiveBox), web page change monitoring, AI-enriched digital archive construction, and a curated free-API catalog with sunset currency notes (IEX Cloud, CrowdTangle, ProPublica Congress, X, Reddit) | n/a, skills only | Nov 4, 2026 |
  50. | [security-toolkit](./security-toolkit/) | Five defensive security skills covering OWASP Top 10 fundamentals, supply-chain hardening, and secret scanning: pre-deployment audit checklists (auth, input validation, secrets management), secure authentication patterns (password hashing, session management, JWT, OAuth, passkeys), API hardening (rate limiting, CORS, request throttling, defense-in-depth for Express, FastAPI, and serverless), and npm/bun supply-chain hardening with install-time cooldown plus a sandboxed pre-install scan for the bypass case (defends against Mini Shai-Hulud-class worms) | `/security-toolkit:hotpatch` | Nov 4, 2026 |
  51. | [superjawn](./superjawn/) | Research-augmented fork of obra/superpowers. Default-on research phase fires before brainstorming, systematic-debugging, and writing-skills. Includes 13 skills with no soft dependencies on the upstream `superpowers` plugin | invoked indirectly via skills (e.g. `superjawn:brainstorming`, `superjawn:systematic-debugging`, `superjawn:writing-plans`) | Nov 4, 2026 |
  52. | [video-toolkit](./video-toolkit/) | Four composable skills for social-video accountability reporting: downloading public video from Twitter/X, TikTok, YouTube, Instagram, and Facebook; transcribing it with a provenance sidecar and a CPU path any evaluator can re-run; extracting and vision-analyzing frames; and aggregating the result into an interactive dashboard | n/a, skills only | Nov 4, 2026 |
  53. | [web-design-picker](./web-design-picker/) | Build two to five distinct website directions, a switchable client review site, downloadable design assets, preview images, static QA reports, and separate Cloudflare Drop and design-handoff packages | n/a, skill only | Nov 4, 2026 |
  54. | [visual-explainer](./visual-explainer/) | HTML diagrams, data tables, architecture views, slide decks, and KPI dashboards adapted from nicobailon/visual-explainer with journalism, newsroom, and academic design sensibilities | `/visual-explainer:project-recap` | Nov 4, 2026 |
  55. #### Skills (manual installation)
  56. Most skills live inside a plugin's `skills/` directory. The `okf-wiki/SKILL.md`, `pdf-design/SKILL.md`, `visual-explainer/SKILL.md`, and `web-design-picker/SKILL.md` root-skill packages keep the skill at the package root. To install one skill without taking a whole plugin, clone the repo and copy or symlink the directory that directly contains its `SKILL.md`. Claude Code discovers skills at `~/.claude/skills/<skill-name>/SKILL.md`, one level deep:
  57. ```
  58. git clone https://github.com/jamditis/claude-skills-journalism.git ~/projects/claude-skills-journalism
  59. cd ~/projects/claude-skills-journalism
  60. mkdir -p ~/.claude/skills
  61. # Pull a single skill out of a plugin's skills/ directory:
  62. cp -r journalism-core/skills/source-verification ~/.claude/skills/
  63. cp -r research-toolkit/skills/free-apis-catalog ~/.claude/skills/
  64. cp -r research-toolkit/skills/web-archiving ~/.claude/skills/
  65. cp -r dev-toolkit/skills/web-scraping ~/.claude/skills/
  66. cp -r dev-toolkit/skills/director ~/.claude/skills/
  67. cp -r newsroom-agent-ops/skills/unattended-agent-runs ~/.claude/skills/
  68. cp -r security-toolkit/skills/secure-auth ~/.claude/skills/
  69. cp -r project-templates-toolkit/skills/project-memory ~/.claude/skills/
  70. # A root-skill package is already the directory to copy:
  71. cp -r okf-wiki ~/.claude/skills/
  72. cp -r web-design-picker ~/.claude/skills/
  73. # Or symlink so git pull updates them in place (ln -sfn replaces an existing link):
  74. ln -sfn "$PWD/research-toolkit/skills/free-apis-catalog" ~/.claude/skills/free-apis-catalog
  75. ln -sfn "$PWD/dev-toolkit/skills/director" ~/.claude/skills/director
  76. ln -sfn "$PWD/web-design-picker" ~/.claude/skills/web-design-picker
  77. ln -sfn "$PWD/visual-explainer" ~/.claude/skills/visual-explainer
  78. ```
  79. The standalone copy or link invokes the skill as `/director`. The installed
  80. plugin invokes it as `/dev-toolkit:director` because Claude Code namespaces
  81. plugin skills.
  82. Do not clone the repo directly into `~/.claude/skills/journalism-skills/`, that nests each `SKILL.md` too deep and Claude Code won't find them.
  83. ### Codex
  84. **Prerequisite:** Install [Codex CLI](https://developers.openai.com/codex/cli). Run `codex --version` in your terminal to check. The legacy-compatible package route below is verified with Codex CLI 0.147.0.
  85. Codex can install `journalism-core` through this repository's Claude marketplace metadata:
  86. ```bash
  87. codex plugin marketplace add jamditis/claude-skills-journalism
  88. codex plugin add journalism-core@claude-skills-journalism
  89. ```
  90. This legacy-compatible package route exposes the 16 nested `journalism-core` skills. It does not convert Claude commands, agents, hooks, or root-level skills into Codex components. This repository ships Codex UI metadata but no native Codex plugin manifests.
  91. You can instead install standards-based skills with the `skills` CLI. This user-level command makes the 16 core skills available across your Codex projects:
  92. ```bash
  93. npx skills@latest add https://github.com/jamditis/claude-skills-journalism/tree/master/journalism-core \
  94. --skill '*' --agent codex --copy -g -y
  95. ```
  96. That command installs `journalism-core` in Codex's documented user skill directory, `~/.agents/skills`. The clean-install canary checks that exact global destination. Remove `-g` to install into the current project's `.agents/skills` directory and record the source and content hashes in that project's `skills-lock.json`. To install one skill instead:
  97. ```bash
  98. npx skills@latest add jamditis/claude-skills-journalism \
  99. --skill fact-check-workflow --agent codex --copy -g -y
  100. ```
  101. Codex desktop can [import skills from another agent](https://learn.chatgpt.com/docs/import.md). Import leaves the source installation in place. Until duplicate-identity and uninstall behavior has been tested for this repository, do not import a skill and also install the same skill through `npx skills` or the package route.
  102. Codex's bundled skill installer writes to a different Codex-specific directory and is not a tested installation path for this repository. Codex does not deduplicate same-name skills across install roots, so don't combine it with the `.agents/skills` route above.
  103. Use only one Codex installation path for the same skill identity.
  104. See the checked-in [Codex compatibility matrix](./plans/codex-compatibility-matrix.md) for tested versions, package boundaries, and pending runtime gates. A valid install is not a package-wide runtime support claim. The historical pilots remain tied to their recorded snapshots.
  105. ### Claude.ai
  106. Skills can be added via the Claude.ai interface under Settings > Skills.
  107. ## Skills overview
  108. The `Updated` column in every table below is the date that skill or plugin last
  109. changed, taken from git history rather than typed by hand. Use it to judge
  110. whether your installed copy has drifted: a skill that cites statutes, platform
  111. APIs, or vendor behavior is worth re-checking against its sources once it is
  112. several months old. The same dates appear as tape on each card at
  113. [skills.amditis.tech](https://skills.amditis.tech/), where the tape yellows with
  114. age.
  115. ### Core journalism skills (in `journalism-core` plugin)
  116. These sixteen skills ship together as the [journalism-core](./journalism-core/) plugin. Install via `/plugin install journalism-core@claude-skills-journalism` to get all of them at once.
  117. | Skill | Description | Updated |
  118. |-------|-------------|--------|
  119. | [ai-writing-detox](./journalism-core/skills/ai-writing-detox/) | Eliminate AI-generated patterns that erode reader trust. Banned words, phrases, and structures with alternatives | Oct 23, 2026 |
  120. | [brazil-records-requests](./journalism-core/skills/brazil-records-requests/) | Public records requests under Brazil's Access to Information Law (Lei 12.527/2011), portal selection across federal, state, municipal, judicial and legislative bodies; deadlines; the four-level appeal chain (first instance, agency head, CGU, CMRI); templates in Portuguese with English glosses | Aug 21, 2026 |
  121. | [crisis-communications](./journalism-core/skills/crisis-communications/) | Breaking news protocol, rapid verification, crisis response, misinformation countering | Aug 21, 2026 |
  122. | [data-journalism](./journalism-core/skills/data-journalism/) | Dataset analysis, chart and map creation, statistical reasoning, data-driven story structure | Aug 21, 2026 |
  123. | [editorial-workflow](./journalism-core/skills/editorial-workflow/) | Story assignment tracking, deadline management, editorial calendars, handoff protocols | Aug 21, 2026 |
  124. | [fact-check-workflow](./journalism-core/skills/fact-check-workflow/) | Claim extraction, evidence gathering, rating scales, correction protocols | Aug 21, 2026 |
  125. | [foia-requests](./journalism-core/skills/foia-requests/) | Public records request drafting (federal FOIA + NJ OPRA), tracking, appeals, current statutory citations | Oct 23, 2026 |
  126. | [interview-prep](./journalism-core/skills/interview-prep/) | Pre-interview research, question frameworks, recording consent, attribution guidelines | Aug 21, 2026 |
  127. | [interview-transcription](./journalism-core/skills/interview-transcription/) | Whisper / WhisperX transcription pipelines, quote management, speaker diarization | Oct 23, 2026 |
  128. | [meeting-transcript-actions](./journalism-core/skills/meeting-transcript-actions/) | Turn verified meeting transcripts into attributed notes, owned actions, decisions, and unresolved questions | Oct 23, 2026 |
  129. | [newsletter-publishing](./journalism-core/skills/newsletter-publishing/) | Email newsletter creation, subscriber management, deliverability, 2024–2026 Gmail / Yahoo / Outlook bulk-sender compliance | Aug 21, 2026 |
  130. | [newsroom-style](./journalism-core/skills/newsroom-style/) | AP Style enforcement, attribution rules, headline formatting, number conventions | Aug 21, 2026 |
  131. | [photo-metadata](./journalism-core/skills/photo-metadata/) | Embed caption, byline, credit, alt text, keywords, copyright / Creative Commons license, AI-source labeling (IPTC Digital Source Type), and Google-Images licensing into a photo's IPTC/EXIF/XMP metadata; strip GPS for source protection; read C2PA Content Credentials; batch-tag a folder for a news wire | Aug 21, 2026 |
  132. | [social-media-intelligence](./journalism-core/skills/social-media-intelligence/) | Narrative tracking, coordinated-campaign analysis, account authenticity checks, OSINT for digital investigations | Aug 21, 2026 |
  133. | [source-verification](./journalism-core/skills/source-verification/) | SIFT method, image and video verification, deepfake detection (2026), C2PA Content Credentials, verification trails | Aug 21, 2026 |
  134. | [story-pitch](./journalism-core/skills/story-pitch/) | Pitch templates for daily news, features, investigations, op-eds, and freelance queries | Aug 21, 2026 |
  135. ### Newsroom agent operations skills
  136. These nine skills ship together as the [newsroom-agent-ops](./newsroom-agent-ops/) plugin.
  137. | Skill | Description | Updated |
  138. |-------|-------------|---------|
  139. | [unattended-agent-runs](./newsroom-agent-ops/skills/unattended-agent-runs/) | Run recurring work with leases, checkpoints, recovery, delivery checks, and resource limits | Oct 23, 2026 |
  140. | [scheduled-briefing](./newsroom-agent-ops/skills/scheduled-briefing/) | Build concise, source-backed, phone-readable newsroom briefings | Oct 23, 2026 |
  141. | [deadline-and-reply-tracking](./newsroom-agent-ops/skills/deadline-and-reply-tracking/) | Track due dates, acknowledgments, replies, waiting states, and next-owner actions | Oct 23, 2026 |
  142. | [email-request-intake](./newsroom-agent-ops/skills/email-request-intake/) | Process allowlisted email requests while treating messages and attachments as untrusted data | Oct 23, 2026 |
  143. | [document-delivery](./newsroom-agent-ops/skills/document-delivery/) | Inspect, share, send, and verify editable documents and PDFs | Oct 23, 2026 |
  144. | [chat-mention-triage](./newsroom-agent-ops/skills/chat-mention-triage/) | Classify team-chat mentions without duplicating the designated live responder | Oct 23, 2026 |
  145. | [record-reconciliation](./newsroom-agent-ops/skills/record-reconciliation/) | Reconcile task, contact, and interaction records with privacy controls and readback | Oct 23, 2026 |
  146. | [multi-agent-coordinator](./newsroom-agent-ops/skills/multi-agent-coordinator/) | Coordinate workers with durable prompts, event-driven watches, review gates, and cleanup | Oct 23, 2026 |
  147. | [issue-pool-progression](./newsroom-agent-ops/skills/issue-pool-progression/) | Advance claimed issues through review, release, deployment, and live verification | Oct 23, 2026 |
  148. ### Research and academic skills (in `research-toolkit` plugin)
  149. These six skills ship together as the [research-toolkit](./research-toolkit/) plugin. Install via `/plugin install research-toolkit@claude-skills-journalism` to get all of them at once.
  150. | Skill | Description | Updated |
  151. |-------|-------------|--------|
  152. | [academic-writing](./research-toolkit/skills/academic-writing/) | Research design, literature reviews, IMRaD structure, peer review responses, grant proposals | Oct 23, 2026 |
  153. | [content-access](./research-toolkit/skills/content-access/) | Unpaywall, CORE, Semantic Scholar APIs, library databases, ethical access patterns | Aug 21, 2026 |
  154. | [digital-archive](./research-toolkit/skills/digital-archive/) | Building archives with AI enrichment, entity extraction, knowledge graphs | Oct 23, 2026 |
  155. | [free-apis-catalog](./research-toolkit/skills/free-apis-catalog/) | Curated free-API catalog organized by journalism use-case, with currency notes for major API sunsets (IEX Cloud, CrowdTangle, ProPublica Congress, X, Reddit) and an evaluation rubric | Aug 21, 2026 |
  156. | [page-monitoring](./research-toolkit/skills/page-monitoring/) | Change detection, RSS generation, webhook alerts, automatic archiving on changes | Aug 21, 2026 |
  157. | [web-archiving](./research-toolkit/skills/web-archiving/) | Wayback Machine, Archive.today, legal evidence preservation, multi-archive redundancy | Aug 21, 2026 |
  158. ### Design and production
  159. | Skill | Description | Updated |
  160. |-------|-------------|--------|
  161. | [pdf-design](./pdf-design/) | Professional PDF reports and proposals with brand system, budget tables, and multi-page layouts. For the full interactive experience, use [pdf-playground](./pdf-playground/) instead | Nov 4, 2026 |
  162. | [web-design-picker](./web-design-picker/) | Produce distinct responsive website directions, a client review picker, downloadable design assets, preview images, static QA reports, and deployment and handoff packages | Nov 4, 2026 |
  163. | [visual-explainer](./visual-explainer/) | Turn complex data into styled HTML pages, architecture diagrams, data tables, flowcharts, timelines, source maps, and dashboards with dark/light theme support. Now registered as a plugin (`/plugin install visual-explainer@claude-skills-journalism`) | Nov 4, 2026 |
  164. ### PDF Playground skill
  165. This skill ships inside the [pdf-playground](./pdf-playground/) plugin.
  166. | Skill | Description | Updated |
  167. |-------|-------------|--------|
  168. | [document-design](./pdf-playground/skills/document-design/) | Create print-ready HTML proposals, reports, one-pagers, newsletters, slides, flyers, and other PDF-ready documents with reusable brand and layout patterns | Oct 23, 2026 |
  169. ### Superjawn skills
  170. These thirteen skills ship inside the [superjawn](./superjawn/) plugin.
  171. | Skill | Description | Updated |
  172. |-------|-------------|--------|
  173. | [brainstorming](./superjawn/skills/brainstorming/) | Explore intent, requirements, design, and relevant research before creative implementation work | Oct 23, 2026 |
  174. | [dispatching-parallel-agents](./superjawn/skills/dispatching-parallel-agents/) | Divide independent tasks among parallel agents without shared-state conflicts | Oct 23, 2026 |
  175. | [executing-plans](./superjawn/skills/executing-plans/) | Execute a written implementation plan with freshness and review checkpoints | Oct 23, 2026 |
  176. | [finishing-a-development-branch](./superjawn/skills/finishing-a-development-branch/) | Verify completed work and choose a safe integration, pull request, or cleanup path | Oct 23, 2026 |
  177. | [receiving-code-review](./superjawn/skills/receiving-code-review/) | Evaluate review feedback against the code before implementing it | Oct 23, 2026 |
  178. | [requesting-code-review](./superjawn/skills/requesting-code-review/) | Request focused review before integration or after a major implementation | Oct 23, 2026 |
  179. | [subagent-driven-development](./superjawn/skills/subagent-driven-development/) | Execute independent plan tasks with agents in the current session | Oct 23, 2026 |
  180. | [systematic-debugging](./superjawn/skills/systematic-debugging/) | Investigate root cause and relevant evidence before proposing a bug fix | Oct 23, 2026 |
  181. | [using-git-worktrees](./superjawn/skills/using-git-worktrees/) | Create isolated worktrees with safe directory selection and verification | Oct 23, 2026 |
  182. | [using-superjawn](./superjawn/skills/using-superjawn/) | Discover and invoke the right Superjawn skill for the current task | Oct 23, 2026 |
  183. | [verification-before-completion](./superjawn/skills/verification-before-completion/) | Run and inspect verification evidence before claiming work is complete | Oct 3, 2026 |
  184. | [writing-plans](./superjawn/skills/writing-plans/) | Turn a specification or requirements into a checked implementation plan | Oct 23, 2026 |
  185. | [writing-skills](./superjawn/skills/writing-skills/) | Research, create, edit, and verify reusable skills | Oct 23, 2026 |
  186. ### Project documentation skills (in `project-templates-toolkit` plugin)
  187. These four skills ship together as the [project-templates-toolkit](./project-templates-toolkit/) plugin. Install via `/plugin install project-templates-toolkit@claude-skills-journalism` to get all of them at once.
  188. | Skill | Description | Updated |
  189. |-------|-------------|--------|
  190. | [goal-progress-bar](./project-templates-toolkit/skills/goal-progress-bar/) | Render weighted progress with current evidence, scope changes, blocked-state checks, and protection against false 100% | Oct 28, 2026 |
  191. | [project-memory](./project-templates-toolkit/skills/project-memory/) | Generate project instruction files that capture project-specific knowledge. Includes templates for editorial tools, events, publications, research, pipelines, and archives | Oct 23, 2026 |
  192. | [project-retrospective](./project-templates-toolkit/skills/project-retrospective/) | Generate LESSONS.md files that document what worked and what didn't. Templates for investigations, events, publications, and tools | Aug 21, 2026 |
  193. | [template-selector](./project-templates-toolkit/skills/template-selector/) | Decision tree for choosing the right project documentation template | Oct 23, 2026 |
  194. ### Development skills (in `dev-toolkit` plugin)
  195. These fourteen skills ship together as the [dev-toolkit](./dev-toolkit/) plugin. Install via `/plugin install dev-toolkit@claude-skills-journalism` to get all of them at once, or copy individual skills from `dev-toolkit/skills/<name>/`.
  196. | Skill | Description | Updated |
  197. |-------|-------------|--------|
  198. | [accessibility-compliance](./dev-toolkit/skills/accessibility-compliance/) | WCAG 2.2 baseline, alt text, focus management, motion preferences, accessible charts | Aug 21, 2026 |
  199. | [claude-md-updater](./dev-toolkit/skills/claude-md-updater/) | Detect durable session lessons and propose scoped project instruction edits for approval | Oct 23, 2026 |
  200. | [context-engineering-fundamentals](./dev-toolkit/skills/context-engineering-fundamentals/) | Attention budget, lost-in-middle recall, context degradation patterns, and mitigations for long sessions | Aug 21, 2026 |
  201. | [director](./dev-toolkit/skills/director/) | Explicit top-tier direction through workers configured in the applicable project instruction file | Oct 23, 2026 |
  202. | [electron-dev](./dev-toolkit/skills/electron-dev/) | Electron security model (contextIsolation, sandbox), IPC patterns, packaging | Aug 21, 2026 |
  203. | [mobile-debugging](./dev-toolkit/skills/mobile-debugging/) | Eruda, vConsole, Chrome DevTools on Android, Safari Web Inspector for iOS, console capture | Oct 4, 2026 |
  204. | [one-way-door](./dev-toolkit/skills/one-way-door/) | Flag irreversible architectural decisions (data models, infra, auth, APIs) before committing | Oct 23, 2026 |
  205. | [ponytail-dev](./dev-toolkit/skills/ponytail-dev/) | Implement or review software with minimal code and proportional checks | Oct 23, 2026 |
  206. | [python-pipeline](./dev-toolkit/skills/python-pipeline/) | Data pipelines (pandas, polars, DuckDB, asyncio) with modular architecture | Oct 23, 2026 |
  207. | [surface-completeness](./dev-toolkit/skills/surface-completeness/) | Verify UI coverage, accessibility, browser support, performance evidence, and current documentation | Oct 28, 2026 |
  208. | [vibe-coding](./dev-toolkit/skills/vibe-coding/) | AI-assisted development workflow (Claude Code, Cursor, Aider, Continue) | Oct 23, 2026 |
  209. | [web-scraping](./dev-toolkit/skills/web-scraping/) | Ethical scraping patterns (Playwright, robots.txt, anti-bot defense, terms-of-service) | Oct 23, 2026 |
  210. | [web-ui-best-practices](./dev-toolkit/skills/web-ui-best-practices/) | Container queries, `:has()`, view transitions, scroll-driven animations, signs of taste in web UI | Aug 21, 2026 |
  211. | [zero-build-frontend](./dev-toolkit/skills/zero-build-frontend/) | ESM import maps, htmx, Alpine.js, no-build deployment | Aug 21, 2026 |
  212. ### Security skills (in `security-toolkit` plugin)
  213. These five skills ship together as the [security-toolkit](./security-toolkit/) plugin, paired with the `/security-toolkit:hotpatch` slash command. Install via `/plugin install security-toolkit@claude-skills-journalism` to get all of them at once.
  214. | Skill | Description | Updated |
  215. |-------|-------------|--------|
  216. | [api-hardening](./security-toolkit/skills/api-hardening/) | Rate limiting, input validation, CORS, security headers, API key management, defense-in-depth for Express, FastAPI, and serverless | Aug 21, 2026 |
  217. | [private-secret-scanning](./security-toolkit/skills/private-secret-scanning/) | Local Gitleaks scans for staged changes, push ranges, and full history in private repositories, with pre-commit and pre-push hooks, redacted reports, and a fail-closed self-test | Oct 23, 2026 |
  218. | [secure-auth](./security-toolkit/skills/secure-auth/) | Production-ready authentication patterns: password hashing, session management, JWT, OAuth, passkeys / WebAuthn, MFA | Aug 21, 2026 |
  219. | [security-checklist](./security-toolkit/skills/security-checklist/) | Pre-deployment security audit covering OWASP Top 10 fundamentals: authentication, input validation, secrets, database security, compliance basics | Oct 23, 2026 |
  220. | [supply-chain-hardening](./security-toolkit/skills/supply-chain-hardening/) | npm/bun install-time cooldown plus sandboxed pre-install scan (bwrap on Linux, sandbox-exec on macOS). Defends against Mini Shai-Hulud-class worms; paired with `/security-toolkit:hotpatch` for the cooldown-bypass case | Oct 23, 2026 |
  221. ### Video analysis skills (in `video-toolkit` plugin)
  222. These four skills ship together as the [video-toolkit](./video-toolkit/) plugin and compose into one pipeline. Install via `/plugin install video-toolkit@claude-skills-journalism`, or copy individual skills from `video-toolkit/skills/<name>/`.
  223. | Skill | What it does | Updated |
  224. |-------|--------------|--------|
  225. | [video-download](./video-toolkit/skills/video-download/) | Collect public video from Twitter/X, TikTok, YouTube, Instagram, and Facebook via yt-dlp, with a browser-automation fallback for broken extractors | Aug 21, 2026 |
  226. | [video-transcribe](./video-toolkit/skills/video-transcribe/) | Batch Whisper transcription with a provenance sidecar per transcript; the CPU `whisper.cpp` path is the transcript of record so an auditor can re-run it without a GPU | Aug 21, 2026 |
  227. | [video-frames](./video-toolkit/skills/video-frames/) | Extract frames, build 3x3 grid composites, and run vision analysis over on-screen text, setting, and presentation style | Sep 23, 2026 |
  228. | [video-dashboard](./video-toolkit/skills/video-dashboard/) | Aggregate transcripts and frame analysis into topic, tone, and cross-platform views behind a single-page dashboard | Aug 21, 2026 |
  229. ## Hooks
  230. Hooks are automated checks that run at specific points in your workflow. Most are **non-blocking warnings**. `one-way-door-check` and `no-ai-attribution` block until you resolve them. `prose-question-guard` blocks a stop once to move a question into `AskUserQuestion`.
  231. The 17 standalone hooks in [`hooks/`](./hooks/) are optional and installed manually from their reference files. Installing a skill package does not enable these top-level hooks. The [prose question guard](./hooks/prose-question-guard.md) uses Python 3 on Windows, macOS, and Linux; its [public guide](https://skills.amditis.tech/prose-question-guard/) includes platform-specific setup and an example from my Claude Code session.
  232. ### Writing quality hooks
  233. | Hook | Event | Description |
  234. |------|-------|-------------|
  235. | [ap-style-check](./hooks/ap-style-check.md) | PostToolUse | Flag common AP Style violations |
  236. | [ai-slop-detector](./hooks/ai-slop-detector.md) | PostToolUse | Warn about AI-generated patterns |
  237. | [accessibility-check](./hooks/accessibility-check.md) | PostToolUse | Check alt text, heading structure, link text |
  238. | [copywriting-preflight](./hooks/copywriting-preflight.md) | UserPromptSubmit | Interview for intent before drafting a new piece or revision |
  239. ### Verification hooks
  240. | Hook | Event | Description |
  241. |------|-------|-------------|
  242. | [source-attribution-check](./hooks/source-attribution-check.md) | PostToolUse | Flag unattributed quotes and claims |
  243. | [verification-reminder](./hooks/verification-reminder.md) | PostToolUse | Prompt to verify facts before including |
  244. | [data-methodology-check](./hooks/data-methodology-check.md) | PostToolUse | Ensure data stories include methodology |
  245. ### Editorial workflow hooks
  246. | Hook | Event | Description |
  247. |------|-------|-------------|
  248. | [source-diversity-check](./hooks/source-diversity-check.md) | PostToolUse | Note when sources may lack diversity |
  249. | [legal-review-flag](./hooks/legal-review-flag.md) | PostToolUse | Flag potentially defamatory content |
  250. | [pre-publish-checklist](./hooks/pre-publish-checklist.md) | Stop | Reminder checklist before completing tasks |
  251. | [deadline-tracker](./hooks/deadline-tracker.md) | SessionStart | Surface upcoming deadlines |
  252. ### Preservation hooks
  253. | Hook | Event | Description |
  254. |------|-------|-------------|
  255. | [archive-reminder](./hooks/archive-reminder.md) | PostToolUse | Remind to archive URLs when citing sources |
  256. ### Interaction hooks
  257. | Hook | Event | Purpose |
  258. |------|-------|---------|
  259. | [prose-question-guard](./hooks/prose-question-guard.md) | Stop | Nudge prose questions into `AskUserQuestion`; [installation and guide](https://skills.amditis.tech/prose-question-guard/) |
  260. ### Development hooks
  261. | Hook | Event | Description |
  262. |------|-------|-------------|
  263. | [one-way-door-check](./hooks/one-way-door-check.md) | PreToolUse | Block creation of files representing irreversible architectural decisions |
  264. | [bug-report-detector](./hooks/bug-report-detector.md) | UserPromptSubmit | Detect bug reports and remind the agent to establish the failure before fixing it |
  265. | [pre-commit-review](./hooks/pre-commit-review.md) | PreToolUse | Surface the staged diff for line-by-line review before a commit, and flag deletions of safety-critical guardrails |
  266. | [no-ai-attribution](./hooks/no-ai-attribution.md) | PreToolUse | Block AI authorship credit in commits, PR bodies, and comments before they land |
  267. ## Skill structure
  268. Each shared skill follows the Agent Skills standard:
  269. ```
  270. skill-name/
  271. ├── SKILL.md # Main instructions (required)
  272. ├── examples/ # Example inputs/outputs (optional)
  273. ├── templates/ # Reusable templates (optional)
  274. └── scripts/ # Helper scripts (optional)
  275. ```
  276. ### SKILL.md format
  277. ```yaml
  278. ---
  279. name: skill-name
  280. description: When to use this skill and what it does
  281. ---
  282. # Skill title
  283. Instructions and knowledge for Claude to use.
  284. ```
  285. ## Usage examples
  286. ### Source verification
  287. When you ask Claude to verify a claim or check a source:
  288. ```
  289. "Can you help me verify this viral tweet claiming [X]?"
  290. "What steps should I take to verify this document?"
  291. "Help me check if this image is authentic"
  292. ```
  293. ### Interview preparation
  294. When preparing for interviews:
  295. ```
  296. "Help me prepare questions for interviewing the mayor about the budget"
  297. "What background research should I do before this interview?"
  298. "Create a question framework for an investigative interview"
  299. ```
  300. ### Story pitching
  301. When developing story ideas:
  302. ```
  303. "Help me pitch this feature story idea"
  304. "Draft a query letter for this freelance investigation"
  305. "What's the angle for this daily news story?"
  306. ```
  307. ### Fact-checking
  308. When verifying claims:
  309. ```
  310. "Walk me through fact-checking this politician's statement"
  311. "Help me document the evidence for this claim"
  312. "What rating should this fact-check receive?"
  313. ```
  314. ### Project documentation
  315. When setting up or closing projects:
  316. ```
  317. "Generate project instructions for this investigation project"
  318. "Write a retrospective for the conference website we just finished"
  319. "Which template should I use for this newsletter project?"
  320. ```
  321. ### Social media intelligence
  322. When investigating online narratives:
  323. ```
  324. "Help me analyze this account for authenticity"
  325. "Track how this claim is spreading across platforms"
  326. "Check for signs of coordinated behavior"
  327. ```
  328. ### Web archiving and monitoring
  329. When preserving or tracking content:
  330. ```
  331. "Archive this page to multiple services for redundancy"
  332. "Set up monitoring for changes to this government page"
  333. "Find academic papers related to this topic"
  334. ```
  335. ## Contributing
  336. Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide, skill structure, testing, and style guidelines.
  337. Quick version: fork, create your skill with a `SKILL.md` frontmatter file, run `npm run validate:agent-skills`, test the clients affected by your change, and submit a PR.
  338. ## Target audiences
  339. - **Investigative journalists** - source verification, FOIA, data analysis
  340. - **Newsroom developers** - scraping, data pipelines, visualization tools
  341. - **Academic researchers** - writing, methodology, peer review
  342. - **Graduate students** - thesis writing, literature reviews, proposals
  343. - **Communications professionals** - content strategy, research methods
  344. - **Fact-checkers** - verification workflows, evidence documentation
  345. - **Digital archivists** - preservation, metadata, knowledge graphs
  346. - **Editors** - workflow management, style enforcement, quality control
  347. ## Related resources
  348. - [Anthropic official skills](https://github.com/anthropics/skills)
  349. - [Claude Code documentation](https://code.claude.com/docs/en/overview)
  350. - [Codex skills documentation](https://learn.chatgpt.com/docs/build-skills)
  351. - [Agent Skills specification](https://agentskills.io/specification)
  352. - [autopunk-media-skills](https://github.com/ur-grue/autopunk-media-skills), broadcast, TV, podcast, and radio production skills; complements this repo's investigative focus. Free library, paired with a paid product ([autopunk.io](https://autopunk.io))
  353. - [NICAR (Investigative Reporters & Editors)](https://www.ire.org/nicar/)
  354. - [First Draft News](https://firstdraftnews.org/)
  355. - [Verification Handbook](https://verificationhandbook.com/)
  356. - [AP Stylebook](https://www.apstylebook.com/)
  357. - [Bellingcat OSINT guides](https://www.bellingcat.com/resources/)
  358. ## License
  359. MIT License - See [LICENSE](./LICENSE) for details.
  360. ## Author
  361. Joe Amditis ([@jamditis](https://github.com/jamditis))
security-toolkit/scripts/hotpatch.example.sh · Bundled script · 579 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # hotpatch, bypass the supply-chain cooldown for one install, after a
  3. # sandboxed pre-install scan. Defends against attacks that ship within the
  4. # 7-day cooldown window (e.g. Mini Shai-Hulud, TanStack 2026-05-11).
  5. #
  6. # Usage:
  7. # hotpatch <pkg>[@<version>] [--manager npm|bun] [--force] [--yes]
  8. # hotpatch --scan-local <tarball-path> # offline test mode
  9. # hotpatch --self-test # run unit fixtures
  10. #
  11. # Defaults:
  12. # --manager autodetected from cwd (bun.lock → bun, package.json → npm)
  13. # --version "latest"
  14. # Install runs with --ignore-scripts (postinstall is the #1 attack vector)
  15. #
  16. # Exit 0 on success, 1 on user-visible error, 2 on red-flag abort.
  17. set -euo pipefail
  18. VERSION="0.1.0"
  19. SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)"
  20. SCAN_DIR=""
  21. trap 'cleanup' EXIT
  22. cleanup() { [ -n "${SCAN_DIR:-}" ] && [ -d "$SCAN_DIR" ] && rm -rf "$SCAN_DIR"; }
  23. die() { echo "hotpatch: $*" >&2; exit 1; }
  24. # Distinct exit code (2) so CI/automation can tell "scan blocked install"
  25. # apart from "error" (1). Honors the contract in the script header.
  26. die_red() { echo "hotpatch: $*" >&2; exit 2; }
  27. warn() { echo "WARN: $*" >&2; }
  28. need_value() {
  29. # Usage: need_value "$#" "$1", fail loudly when a flag is given without
  30. # its required value (otherwise set -u crashes with "unbound variable").
  31. local remaining="$1" flag="$2"
  32. [ "$remaining" -ge 2 ] || die "flag $flag requires a value"
  33. }
  34. declare -a FLAGS_RED=()
  35. declare -a FLAGS_YELLOW=()
  36. flag_red() { FLAGS_RED+=("$*"); echo " RED $*"; }
  37. flag_yellow() { FLAGS_YELLOW+=("$*"); echo " YEL $*"; }
  38. print_usage() {
  39. cat <<EOF
  40. hotpatch v$VERSION, sandboxed bypass for npm/bun cooldown
  41. hotpatch <pkg>[@<version>] [--manager npm|bun] [--force] [--yes]
  42. hotpatch --scan-local <tarball-path>
  43. hotpatch --self-test
  44. Flags:
  45. --manager npm|bun Force package manager (default: autodetect from cwd)
  46. --force Install even if red flags raised
  47. --yes, -y Skip interactive confirm
  48. --scan-local PATH Scan a local .tgz/.tar.gz without registry/network
  49. --self-test Run unit-test fixtures and exit
  50. EOF
  51. }
  52. # ---- Parse args ----
  53. PKG=""
  54. MANAGER=""
  55. FORCE=0
  56. ASSUME_YES=0
  57. SCAN_LOCAL=""
  58. SELF_TEST=0
  59. while [ $# -gt 0 ]; do
  60. case "$1" in
  61. --manager) need_value "$#" "$1"; MANAGER="$2"; shift 2 ;;
  62. --force) FORCE=1; shift ;;
  63. --yes|-y) ASSUME_YES=1; shift ;;
  64. --scan-local) need_value "$#" "$1"; SCAN_LOCAL="$2"; shift 2 ;;
  65. --self-test) SELF_TEST=1; shift ;;
  66. -h|--help) print_usage; exit 0 ;;
  67. -*) die "unknown flag: $1" ;;
  68. *) PKG="$1"; shift ;;
  69. esac
  70. done
  71. # ---- Static-check functions ----
  72. # Each takes the extracted package root and updates FLAGS_RED/FLAGS_YELLOW.
  73. check_install_hooks() {
  74. local pkg_root="$1" pkg_json="$1/package.json"
  75. [ -f "$pkg_json" ] || { flag_red "missing package.json"; return; }
  76. local hooks
  77. hooks=$(python3 - "$pkg_json" <<'PY'
  78. import json, sys
  79. p = json.load(open(sys.argv[1]))
  80. scripts = p.get('scripts', {})
  81. risky = {k: v for k, v in scripts.items()
  82. if k in ('preinstall', 'install', 'postinstall', 'prepare', 'prepublish')}
  83. for k, v in risky.items():
  84. print(f'{k}={v}')
  85. PY
  86. )
  87. if [ -n "$hooks" ]; then
  88. flag_yellow "install/prepare hooks present (will be skipped via --ignore-scripts):"
  89. echo "$hooks" | sed 's/^/ /'
  90. fi
  91. }
  92. check_git_deps() {
  93. local pkg_root="$1" pkg_json="$1/package.json"
  94. [ -f "$pkg_json" ] || return
  95. local sus
  96. sus=$(python3 - "$pkg_json" <<'PY'
  97. import json, sys
  98. p = json.load(open(sys.argv[1]))
  99. out = []
  100. for field in ('dependencies', 'optionalDependencies', 'peerDependencies'):
  101. for k, v in (p.get(field) or {}).items():
  102. if isinstance(v, str) and ('github:' in v or v.startswith('git+') or v.startswith('git@')):
  103. out.append(f'{field}.{k} = {v}')
  104. print('\n'.join(out))
  105. PY
  106. )
  107. if [ -n "$sus" ]; then
  108. flag_red "git URLs in dependency fields (Mini Shai-Hulud pattern):"
  109. echo "$sus" | sed 's/^/ /'
  110. fi
  111. }
  112. check_large_root_js() {
  113. # Flag large JS at the package root that ISN'T declared in package.json.
  114. # Mini Shai-Hulud planted router_init.js at root, undeclared. Legitimate
  115. # bundle files (lodash.js, react.production.min.js) are always referenced
  116. # by main/module/exports/bin/files.
  117. local pkg_root="$1" pkg_json="$1/package.json"
  118. local unref
  119. unref=$(python3 - "$pkg_root" "$pkg_json" <<'PY'
  120. import json, os, sys
  121. root, manifest = sys.argv[1], sys.argv[2]
  122. declared = set()
  123. try:
  124. p = json.load(open(manifest))
  125. except Exception:
  126. p = {}
  127. def add(v):
  128. if isinstance(v, str):
  129. declared.add(os.path.normpath(v.lstrip('./')))
  130. elif isinstance(v, dict):
  131. for x in v.values():
  132. add(x)
  133. elif isinstance(v, list):
  134. for x in v:
  135. add(x)
  136. for k in ('main', 'module', 'browser', 'types', 'typings'):
  137. add(p.get(k))
  138. add(p.get('exports'))
  139. add(p.get('bin'))
  140. add(p.get('files'))
  141. flagged = []
  142. for entry in os.listdir(root):
  143. path = os.path.join(root, entry)
  144. if not os.path.isfile(path):
  145. continue
  146. if not entry.endswith(('.js', '.mjs', '.cjs')):
  147. continue
  148. if os.path.getsize(path) < 500 * 1024:
  149. continue
  150. # Match against any declared path that references this entry
  151. if any(entry == d or entry == os.path.basename(d) for d in declared):
  152. continue
  153. flagged.append(f'{entry} ({os.path.getsize(path)//1024}KB)')
  154. print('\n'.join(flagged))
  155. PY
  156. )
  157. if [ -n "$unref" ]; then
  158. flag_red "large unreferenced JS at package root (Mini Shai-Hulud planted router_init.js this way):"
  159. echo "$unref" | sed 's/^/ /'
  160. fi
  161. }
  162. check_credential_paths() {
  163. # Look for string references to sensitive paths in *.js files near the root.
  164. local pkg_root="$1"
  165. local matches
  166. matches=$(grep -rEo --include='*.js' --include='*.mjs' --include='*.cjs' \
  167. -l '\.ssh/|\.aws/|\.npmrc|\.gnupg|GITHUB_TOKEN|AWS_SECRET|VAULT_TOKEN|/etc/shadow|kube/config' \
    • Dismissed after review: Reads a credential file in a script that also sends data over the network
    • Line 182 on GitHub
  168. "$pkg_root" 2>/dev/null | head -5 || true)
  169. if [ -n "$matches" ]; then
  170. flag_yellow "files reference credential/secret paths:"
  171. echo "$matches" | sed "s|$pkg_root/||; s/^/ /"
  172. fi
  173. }
  174. # ---- Sandboxed extract ----
  175. # Dispatches to a platform-specific backend so the same scan workflow runs
  176. # on Linux (bwrap) and macOS (sandbox-exec). The contract is identical:
  177. # extract <tarball> into <dest> with no network and no writes outside <dest>.
  178. # Probe whether bwrap can actually function. Unprivileged user namespaces are
  179. # blocked on many CI runners (GitHub Actions Ubuntu hosts, certain Docker
  180. # containers) and inside hardened production environments. The cheapest test
  181. # is a no-op bind+true; if it can't even mount /, it can't sandbox anything.
  182. bwrap_works() {
  183. bwrap --bind / / -- true 2>/dev/null
  184. }
  185. sandboxed_extract() {
  186. local tarball="$1" dest="$2"
  187. mkdir -p "$dest"
  188. local os
  189. os="$(uname -s)"
  190. case "$os" in
  191. Linux)
  192. if command -v bwrap >/dev/null 2>&1 && bwrap_works; then
  193. sandboxed_extract_bwrap "$tarball" "$dest"
  194. elif command -v bwrap >/dev/null 2>&1; then
  195. warn "bwrap installed but blocked by host policy (likely AppArmor/seccomp restriction on unprivileged user namespaces, common in CI runners and containers). Falling back to unsandboxed tar. Static scan still runs."
  196. tar -xzf "$tarball" -C "$dest"
  197. else
  198. warn "bwrap not installed; falling back to unsandboxed tar. Install bubblewrap (apt/dnf/pacman install bubblewrap) for isolation."
  199. tar -xzf "$tarball" -C "$dest"
  200. fi
  201. ;;
  202. Darwin)
  203. if command -v sandbox-exec >/dev/null 2>&1; then
  204. sandboxed_extract_macos "$tarball" "$dest"
  205. else
  206. warn "sandbox-exec not found; falling back to unsandboxed tar."
  207. tar -xzf "$tarball" -C "$dest"
  208. fi
  209. ;;
  210. *)
  211. warn "unsupported OS ($os); falling back to unsandboxed tar. Sandbox backends: Linux (bwrap), macOS (sandbox-exec)."
  212. tar -xzf "$tarball" -C "$dest"
  213. ;;
  214. esac
  215. }
  216. sandboxed_extract_bwrap() {
  217. local tarball="$1" dest="$2"
  218. # bwrap: ro system, only the scan dir is writable.
  219. # /bin and /lib are symlinks into /usr on Debian unified-/usr layout, so
  220. # binding /usr alone is sufficient. Add symlinks back inside the sandbox so
  221. # tools that hardcode /bin/sh still work.
  222. #
  223. # We enumerate --unshare-* flags individually instead of --unshare-all because
  224. # --unshare-net triggers loopback (lo) interface setup inside the new netns,
  225. # which requires CAP_NET_ADMIN, not granted to unprivileged users on
  226. # hardened/containerized hosts (e.g. GitHub Actions runners), producing
  227. # "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted". Tar
  228. # extraction doesn't need network anyway; the script's `curl` calls all
  229. # happen OUTSIDE the sandbox, and filesystem confinement (--bind, --ro-bind)
  230. # is what actually contains a malicious archive during extraction.
  231. bwrap \
  232. --ro-bind /usr /usr \
  233. --symlink usr/bin /bin \
  234. --symlink usr/lib /lib \
  235. --symlink usr/lib /lib64 \
  236. --ro-bind-try /etc/alternatives /etc/alternatives \
  237. --bind "$(dirname "$tarball")" "$(dirname "$tarball")" \
  238. --bind "$dest" "$dest" \
  239. --proc /proc --dev /dev \
  240. --setenv PATH /usr/bin:/usr/local/bin \
  241. --unshare-user --unshare-ipc --unshare-pid \
  242. --unshare-uts --unshare-cgroup-try \
  243. --die-with-parent \
  244. -- \
  245. /usr/bin/tar -xzf "$tarball" -C "$dest"
  246. }
  247. sandboxed_extract_macos() {
  248. local tarball="$1" dest="$2"
  249. local tarball_abs dest_abs profile rc
  250. # sandbox-exec subpath rules require absolute, resolved paths.
  251. # We resolve the tarball as a FILE (not its parent dir) so the read scope
  252. # stays tight, tar reads the archive itself, never its siblings.
  253. tarball_abs="$(cd "$(dirname "$tarball")" && pwd -P)/$(basename "$tarball")"
  254. dest_abs="$(cd "$dest" && pwd -P)"
  255. profile="$(mktemp -t hotpatch-sandbox.XXXXXX)"
  256. # The profile is a Scheme-syntax deny-default policy.
  257. # Read scope: system dirs + the tarball file only. NOT the user homedir;
  258. # otherwise a malicious archive's symlinks/hardlinks could exfiltrate
  259. # ~/.ssh, ~/.aws, etc. via tar's symlink-follow behavior.
  260. # Write scope: $dest only, the tarball directory is read-only.
  261. # Process exec: /usr/bin/tar only.
  262. # Network: denied at the syscall layer.
  263. # sandbox-exec is technically deprecated by Apple but still ships and
  264. # works on macOS 14/15. If/when it's removed, fall back to `tar
  265. # --no-xattrs --no-same-owner` inside a `chroot` jail.
  266. cat > "$profile" <<PROFILE
  267. (version 1)
  268. (deny default)
  269. (allow process-fork)
  270. (allow sysctl-read)
  271. (allow signal (target self))
  272. (allow mach-lookup)
  273. (allow file-read*
  274. (subpath "/usr")
  275. (subpath "/System")
  276. (subpath "/Library")
  277. (subpath "/bin")
  278. (subpath "/sbin")
  279. (subpath "/private/var/db/dyld")
  280. (literal "/dev/null")
  281. (literal "/dev/urandom")
  282. (literal "$tarball_abs"))
  283. (allow file-write*
  284. (subpath "$dest_abs"))
  285. (deny network*)
  286. (allow process-exec
  287. (literal "/usr/bin/tar"))
  288. PROFILE
  289. sandbox-exec -f "$profile" /usr/bin/tar -xzf "$tarball" -C "$dest"
  290. rc=$?
  291. rm -f "$profile"
  292. return $rc
  293. }
  294. # ---- Run the scan against an extracted package ----
  295. run_static_checks() {
  296. local pkg_root="$1"
  297. echo "==> static checks"
  298. check_install_hooks "$pkg_root"
  299. check_git_deps "$pkg_root"
  300. check_large_root_js "$pkg_root"
  301. check_credential_paths "$pkg_root"
  302. }
  303. # ---- OSV.dev (free, no auth) + npm deprecation check ----
  304. check_external() {
  305. local name="$1" version="$2" meta_file="$3"
  306. echo "==> external feeds"
  307. # 1. npm registry deprecation flag (TanStack used this to mark compromised versions)
  308. local deprecated
  309. deprecated=$(python3 - "$meta_file" "$version" <<'PY'
  310. import json, sys
  311. d = json.load(open(sys.argv[1]))
  312. v = sys.argv[2]
  313. info = d['versions'].get(v, {})
  314. print(info.get('deprecated', ''))
  315. PY
  316. )
  317. if [ -n "$deprecated" ]; then
  318. if echo "$deprecated" | grep -qiE 'security|compromise|malicious|do not|vulnerab'; then
  319. flag_red "registry marks this version deprecated for security:"
  320. echo " $deprecated" | head -2 | sed 's/^/ /'
  321. else
  322. flag_yellow "registry marks this version deprecated:"
  323. echo " $deprecated" | head -2 | sed 's/^/ /'
  324. fi
  325. fi
  326. # 2. OSV.dev, free public vulnerability database
  327. local osv_resp
  328. osv_resp=$(curl -fsSL --max-time 10 -X POST "https://api.osv.dev/v1/query" \
  329. -d "{\"package\":{\"name\":\"$name\",\"ecosystem\":\"npm\"},\"version\":\"$version\"}" 2>/dev/null) \
  330. || { echo " osv api unavailable (skipped)"; return; }
  331. local osv_count
  332. osv_count=$(echo "$osv_resp" | python3 -c "
  333. import json, sys
  334. try:
  335. d = json.load(sys.stdin)
  336. vulns = d.get('vulns', [])
  337. print(len(vulns))
  338. for v in vulns[:5]:
  339. sev = v.get('database_specific', {}).get('severity', '?')
  340. print(f\" {v.get('id','?')} ({sev}): {v.get('summary','')[:80]}\", file=sys.stderr)
  341. except Exception as e:
  342. print(0)
  343. " 2>&1)
  344. # python wrote count to stdout and per-vuln lines to stderr; capture both
  345. local count_line=$(echo "$osv_resp" | python3 -c "
  346. import json,sys
  347. try: d=json.load(sys.stdin); print(len(d.get('vulns',[])))
  348. except: print(0)
  349. ")
  350. if [ "$count_line" -gt 0 ]; then
  351. flag_red "OSV.dev reports $count_line known vulnerability/vulnerabilities for this version"
  352. echo "$osv_resp" | python3 -c "
  353. import json, sys
  354. d = json.load(sys.stdin)
  355. for v in d.get('vulns', [])[:5]:
  356. sev = v.get('database_specific', {}).get('severity', '?')
  357. print(f\" {v.get('id','?')} ({sev}): {v.get('summary','')[:90]}\")
  358. "
  359. else
  360. echo " OSV: no known vulnerabilities for $name@$version"
  361. fi
  362. }
  363. # ---- Main flows ----
  364. do_self_test() {
  365. # Look for the fixture in (1) the plugin's test-fixtures dir relative to this
  366. # script, (2) ~/.claude/hotpatch-fixtures/ (officejawn convention).
  367. local fixture
  368. for candidate in \
  369. "$SCRIPT_DIR/../test-fixtures/fake-mini-shai.tgz" \
  370. "$HOME/.claude/hotpatch-fixtures/fake-mini-shai.tgz"; do
  371. if [ -f "$candidate" ]; then fixture="$candidate"; break; fi
  372. done
  373. [ -n "${fixture:-}" ] || die "self-test fixture not found (looked in ../test-fixtures/ and ~/.claude/hotpatch-fixtures/)"
  374. echo "==> self-test: scanning $fixture"
  375. SCAN_DIR=$(mktemp -d /tmp/hotpatch.XXXXXX)
  376. sandboxed_extract "$fixture" "$SCAN_DIR/extracted"
  377. run_static_checks "$SCAN_DIR/extracted/package"
  378. echo
  379. echo "expected: 1+ RED (git URL in deps, large root JS), 1+ YEL (postinstall hook)"
  380. echo "got: ${#FLAGS_RED[@]} red, ${#FLAGS_YELLOW[@]} yellow"
  381. if [ "${#FLAGS_RED[@]}" -ge 2 ] && [ "${#FLAGS_YELLOW[@]}" -ge 1 ]; then
  382. echo "SELF-TEST PASSED"
  383. exit 0
  384. else
  385. echo "SELF-TEST FAILED, scan did not flag the synthetic Mini Shai-Hulud fixture"
  386. exit 1
  387. fi
  388. }
  389. do_scan_local() {
  390. local tarball="$1"
  391. [ -f "$tarball" ] || die "tarball not found: $tarball"
  392. SCAN_DIR=$(mktemp -d /tmp/hotpatch.XXXXXX)
  393. sandboxed_extract "$tarball" "$SCAN_DIR/extracted"
  394. local pkg_root="$SCAN_DIR/extracted/package"
  395. [ -d "$pkg_root" ] || die "tarball did not extract a 'package/' directory"
  396. run_static_checks "$pkg_root"
  397. echo
  398. echo "==> summary: ${#FLAGS_RED[@]} red, ${#FLAGS_YELLOW[@]} yellow (scan-local: no install attempted)"
  399. [ "${#FLAGS_RED[@]}" -gt 0 ] && exit 2 || exit 0
  400. }
  401. do_hotpatch() {
  402. [ -n "$PKG" ] || { print_usage; die "missing package name"; }
  403. # Manager autodetect
  404. if [ -z "$MANAGER" ]; then
  405. if [ -f bun.lock ] || [ -f bun.lockb ]; then MANAGER=bun
  406. elif [ -f package.json ] || [ -f package-lock.json ]; then MANAGER=npm
  407. else die "no package.json in cwd; specify --manager npm|bun"; fi
  408. fi
  409. # Parse name@version
  410. local name version_req
  411. case "$PKG" in
  412. @*/*@*) name="${PKG%@*}"; version_req="${PKG##*@}" ;;
  413. @*/*) name="$PKG"; version_req="latest" ;;
  414. *@*) name="${PKG%@*}"; version_req="${PKG##*@}" ;;
  415. *) name="$PKG"; version_req="latest" ;;
  416. esac
  417. echo "==> hotpatch: $name@$version_req via $MANAGER"
  418. # Set up scan dir first so we can spool metadata
  419. SCAN_DIR=$(mktemp -d /tmp/hotpatch.XXXXXX)
  420. local meta_file="$SCAN_DIR/meta.json"
  421. # Fetch metadata to disk (big JSON breaks heredoc interpolation).
  422. # --max-time / --connect-timeout so a hung registry can't hang the script.
  423. curl -fsSL --max-time 30 --connect-timeout 10 \
  424. "https://registry.npmjs.org/${name//\//%2F}" -o "$meta_file" \
  425. || die "package not found on registry (or fetch timed out): $name"
  426. local tarball_url version pub_date age_days
  427. read -r version tarball_url pub_date age_days < <(python3 - "$meta_file" "$version_req" <<'PY'
  428. import json, sys
  429. from datetime import datetime, timezone
  430. d = json.load(open(sys.argv[1]))
  431. v = sys.argv[2]
  432. if v == 'latest':
  433. v = d['dist-tags']['latest']
  434. if v not in d['versions']:
  435. sys.exit(f"version {v} not found on registry")
  436. tb = d['versions'][v]['dist']['tarball']
  437. pub = d['time'].get(v, '')
  438. if pub:
  439. age = int((datetime.now(timezone.utc) - datetime.fromisoformat(pub.replace('Z','+00:00'))).total_seconds() / 86400)
  440. else:
  441. age = -1
  442. print(v, tb, pub or '?', age)
  443. PY
  444. ) || die "version resolution failed"
  445. echo " resolved: $name@$version (published $pub_date, age ${age_days}d)"
  446. # Download tarball
  447. local tarball="$SCAN_DIR/pkg.tgz"
  448. curl -fsSL --max-time 60 --connect-timeout 10 -o "$tarball" "$tarball_url" \
  449. || die "tarball download failed (or timed out)"
  450. local size_kb=$(( $(stat -c%s "$tarball") / 1024 ))
  451. echo " tarball: ${size_kb}KB"
  452. # Size + fileCount delta vs prior version, using registry metadata (no
  453. # second HEAD request, Cloudflare HEAD responses sometimes drop Content-Length).
  454. local prior this_size this_files prior_size prior_files
  455. read -r prior this_size this_files prior_size prior_files < <(python3 - "$meta_file" "$version" <<'PY'
  456. import json, sys
  457. from datetime import datetime
  458. d = json.load(open(sys.argv[1]))
  459. this_v = sys.argv[2]
  460. times = d['time']
  461. if this_v not in times or this_v not in d['versions']:
  462. print('', 0, 0, 0, 0); sys.exit()
  463. this_dist = d['versions'][this_v]['dist']
  464. this_size = this_dist.get('unpackedSize') or 0
  465. this_files = this_dist.get('fileCount') or 0
  466. this = datetime.fromisoformat(times[this_v].replace('Z','+00:00'))
  467. def is_stable(v):
  468. # Skip prereleases (5.7.0-dev.x, 1.0.0-rc.1, etc.) so baseline is meaningful.
  469. return '-' not in v
  470. older = [(v, times[v]) for v in d['versions']
  471. if v != this_v and v in times and is_stable(v)
  472. and datetime.fromisoformat(times[v].replace('Z','+00:00')) < this]
  473. older.sort(key=lambda x: x[1], reverse=True)
  474. if older:
  475. prev = older[0][0]
  476. pd = d['versions'][prev]['dist']
  477. print(prev, this_size, this_files,
  478. pd.get('unpackedSize') or 0, pd.get('fileCount') or 0)
  479. else:
  480. print('', this_size, this_files, 0, 0)
  481. PY
  482. )
  483. if [ -n "$prior" ] && [ "$prior_size" -gt 0 ]; then
  484. local size_ratio file_delta
  485. size_ratio=$(( this_size * 100 / prior_size ))
  486. file_delta=$(( this_files - prior_files ))
  487. echo " vs $prior: unpackedSize ${prior_size}B (this is ${size_ratio}%), fileCount ${prior_files} (delta: $file_delta)"
  488. if [ "$size_ratio" -gt 300 ]; then
  489. flag_red "unpacked size is ${size_ratio}% of prior version, 3x+ growth is rare in legit releases"
  490. elif [ "$size_ratio" -gt 150 ]; then
  491. flag_yellow "unpacked size is ${size_ratio}% of prior version, sanity-check what was added"
  492. fi
  493. # File count jump without proportional size change = single fat payload (Mini Shai-Hulud pattern).
  494. if [ "$file_delta" -gt 0 ] && [ "$file_delta" -lt 5 ] && [ "$size_ratio" -gt 200 ]; then
  495. flag_red "added $file_delta file(s) but size jumped ${size_ratio}%, consistent with a single planted payload"
  496. fi
  497. fi
  498. # Extract and scan
  499. sandboxed_extract "$tarball" "$SCAN_DIR/extracted"
  500. local pkg_root="$SCAN_DIR/extracted/package"
  501. [ -d "$pkg_root" ] || die "tarball did not extract a 'package/' directory"
  502. run_static_checks "$pkg_root"
  503. check_external "$name" "$version" "$meta_file"
  504. # Report
  505. echo
  506. echo "==> report"
  507. echo " package: $name@$version"
  508. echo " published: $pub_date (${age_days}d ago)"
  509. echo " tarball: ${size_kb}KB"
  510. echo " red flags: ${#FLAGS_RED[@]}"
  511. echo " yellow flags: ${#FLAGS_YELLOW[@]}"
  512. if [ "${#FLAGS_RED[@]}" -gt 0 ] && [ "$FORCE" -eq 0 ]; then
  513. echo
  514. die_red "ABORT: red flags present. Re-run with --force to install anyway, or pick a different version."
  515. fi
  516. if [ "$ASSUME_YES" -eq 0 ]; then
  517. echo
  518. read -p "proceed with install? [y/N] " ans
  519. case "$ans" in y|Y|yes) ;; *) die "aborted by user" ;; esac
  520. fi
  521. echo
  522. echo "==> installing $name@$version via $MANAGER (--ignore-scripts, --bypass cooldown)"
  523. case "$MANAGER" in
  524. npm) npm install "${name}@${version}" --min-release-age=0 --ignore-scripts ;;
  525. bun) bun add "${name}@${version}" --minimum-release-age=0 --ignore-scripts ;;
  526. *) die "unknown manager: $MANAGER" ;;
  527. esac
  528. echo
  529. echo "==> done. Install scripts were SKIPPED."
  530. echo " If $name needs postinstall (native modules), inspect the script and"
  531. echo " re-run manually after review: (cd node_modules/$name && npm run postinstall)"
  532. }
  533. # ---- Dispatch ----
  534. if [ "$SELF_TEST" -eq 1 ]; then do_self_test; fi
  535. if [ -n "$SCAN_LOCAL" ]; then do_scan_local "$SCAN_LOCAL"; fi
  536. do_hotpatch

Ratings and comments

Sign in to rate this skill.

Sign in

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