skills/jamditis__claude-skills-journalism

mirror of https://github.com/jamditis/claude-skills-journalism.git synced 2026-09-14 16:00:34 +08:00

Files

T

Joe Amditis 3e0e3a8dff Shorten skill and plugin descriptions, remove em-dashes (#277 )

* Shorten skill and plugin descriptions, remove em-dashes

Trim every SKILL.md description to <=130 characters (longest is now 130,
aggregate 7,464 across all 62 skills) so the full set stays under Codex's
skills-metadata budget and stops the overflow warnings on load. Descriptions
stay third-person and front-load their trigger keywords so discovery is
unaffected. Also shorten the 12 plugin.json and matching marketplace.json
blurbs (journalism-core dropped from 1,036 to 378 chars).

Replace em-dashes with commas repo-wide (2,558 lines across 228 files),
following the repo's own ai-writing-detox guidance. The demonstrative
em-dashes that teach the pattern in ai-writing-detox and ai-slop-detector
are preserved; a quote attribution keeps an ASCII hyphen.

All 175 tests pass; validate:agent-skills reports 62 skills, 0 failed.

* Add changelog entry for description and em-dash cleanup

* Fix review: restore table markers, attributions, photo-metadata triggers

The blanket em-dash-to-comma pass corrupted three non-prose uses of the
em-dash that a comma cannot represent:

- Table "not applicable" cells (photo-metadata SKILL.md and reference.md,
  the Brazil recurso-cgu template, and the photo-metadata and
  accessibility-compliance docs pages) became a lone comma. Restored them
  to a hyphen marker: 47 markdown cells and 9 HTML cells.
- Pull-quote and slide citation prefixes in the pdf-playground report and
  slides templates became a leading comma. Restored the ASCII attribution
  hyphen.
- The photo-metadata description dropped its distinctive safety triggers.
  Reworded to keep GPS stripping, C2PA credentials, and AI-source labeling
  alongside IPTC/EXIF/XMP, still within 130 characters.

npm test 175/175, validate:agent-skills 62/62, check:docs-css verified.

* Bump plugin versions, keep visual-explainer triggers, log superjawn divergence

Address the remaining review findings:

- Patch-bump all 12 plugins in plugin.json and marketplace.json (and the
  okf-wiki and visual-explainer root skill version fields) so existing
  installs are offered the shortened descriptions. Update the version-
  alignment guard tests and the journalism-core install canary accordingly.
- Rework the visual-explainer description to keep its distinctive workflow
  triggers (timelines, source maps, slide decks, comparison tables, recaps,
  plan and diff reviews) within the 130-character cap.
- Record the superjawn upstream divergence: drop skill_md_parity to false
  for the five skills whose SKILL.md changed, add supporting_file_overrides
  for the touched supporting files, and document it in superjawn/CREDITS.md.

All 175 node tests pass; validate:agent-skills 62/62; check:docs-css verified;
longest description 130 chars, aggregate 7,472 across 62 skills.

* Rewrite CCM brand em-dash rule to name commas as the replacement

The repo-wide em-dash pass stripped the glyph from the CCM brand rule's
example, leaving 'Prefer em dashes ()' which was both malformed and
contradicted the new no-em-dash policy. Rewrite it to prefer commas.

* Fix parser regression, restore leading-comma sentences, keep more triggers

Fourth review round:

- The repo-wide em-dash sweep rewrote a functional delimiter in
  autocontext/scripts/seed-from-claude-md.py: is_command_reference matched
  "/cmd — description" via " — ", and changing it to ", " both stopped
  recognizing external CLAUDE.md command docs (which still use em-dashes) and
  misclassified any slash-prefixed rule containing a comma. Restored the
  em-dash delimiter (a functional exception, like the ai-writing-detox
  teaching examples) and added a regression-guard test for the case the
  original suite never covered.
- Fixed the sentence-leading commas the sweep left on wrapped lines in
  okf-wiki/SKILL.md, academic-writing, and the okf example photo-metadata
  bundle by moving the comma to the end of the preceding line.
- Reworked the web-scraping and interview-prep descriptions to keep their
  distinctive triggers (social media, yt-dlp, CAPTCHA/403 for web-scraping;
  recording, consent, one-party/all-party law for interview-prep).

Verification: node 175/175, autocontext pytest 26/26 (incl. new guard),
validate:agent-skills 62/62. Longest description 130, aggregate 7,489.

* Fix exported-quote attribution and keep academic-writing compliance triggers

- The em-dash sweep turned the speaker attribution in interview-transcription's
  export_for_story() into a leading comma, so every publication-ready quote
  exported as ", Speaker Name". Restored the ASCII attribution hyphen.
- Reworked the academic-writing description to keep its distinctive compliance
  triggers (CRediT, preregistration, Plan S, Nelson Memo, ORCID, LLM
  disclosure) within the 130-character cap.

* Restore distinctive discovery triggers in four descriptions

Codex's review keeps surfacing skills whose shortened description dropped a
distinctive trigger that maps to dedicated, consequential guidance in the body
(which cannot load if the skill is not selected). Restore those triggers within
the 130-character cap:

- one-way-door: add event schemas and CI/CD (both are explicit one-way-door
  categories with their own contract and deployment-risk checks).
- api-hardening: name Express, FastAPI, and serverless (framework-specific
  hardening sections).
- web-archiving: name the Wayback Machine and Archive.today (how users
  actually ask for this).
- secure-auth: name OWASP and NIST.

node 175/175, validate:agent-skills 62/62; longest description 130 chars.

* Fix CRediT taxonomy and doc-span corruption, restore four more triggers

The em-dash sweep corrupted two constructs where the dash carried meaning:

- The CRediT taxonomy in academic-writing listed "Writing — original draft"
  and "Writing — review & editing" as two of its 14 roles; the comma swap made
  them read as four separate roles. Restored the hyphen in both role names.
- Seven label/value rows in docs/superjawn/index.html (and one dir-tree
  annotation in visual-explainer css-patterns) put the separator at the start
  of the second span, rendering "Web , error string searches". Moved the
  separator onto the label (colon) / used a hyphen annotation.

Also restored distinctive discovery triggers flagged by review:
- python-pipeline: Google Sheets/Drive integration
- page-monitoring: RSS feed generation
- zero-build-frontend: Manifest V3 browser extensions
- pdf-design: secure upload

node 175/175, pytest 304/304, validate:agent-skills 62/62, check:docs-css.

* Sync displayed versions, fix pitch contrast, restore three triggers

- Version bumps: update the displayed plugin versions that trailed the manifest
  bumps: CLAUDE.md inventory (journalism-core, research-toolkit, video-toolkit,
  pdf-playground, superjawn) and the docs badges in docs/index.html,
  docs/superjawn, and docs/video-toolkit, plus the video-toolkit docs test guard.
- story-pitch: the em-dash sweep flattened "background checks - through a
  spreadsheet" into a comma, losing the contrast in the model pitch. Restored
  it with an explicit "but".
- Restore triggers: ai-writing-detox (writing/drafting, not just editing),
  brainstorming (MUST + modifying behavior), okf-wiki (builds from existing
  docs/notes/repo, the input flow, not "from concept files").

node 175/175, validate:agent-skills 62/62, check:docs-css.

* Restore four more discovery triggers

- context-engineering-fundamentals: lost-instructions / dropped-evidence
- vibe-coding: name Copilot, Codex, Aider, Windsurf (not just Claude Code/Cursor)
- video-transcribe: audio-only (WAV, podcasts), not just video
- zero-build-frontend: Google Sheets as a database

node 175/175, validate:agent-skills 62/62.

2026-08-18 07:49:38 -04:00

2.8 KiB

Raw Permalink Blame History

PR snippets, files to edit besides the skill folder

Not part of the skill. Copy these into the repo files, adjusting wording to match whatever is actually there when you branch.

1. `journalism-core/README.md`, skill table row

| [brazil-records-requests](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 |

2. root `README.md`

Same row in the core-skills table, plus the count. "Fourteen" appears in at least three places, the plugin description, the plugin table, and the journalism-core section heading. Grep before committing:

grep -rn -i "fourteen\|14 skills" README.md journalism-core/ .claude-plugin/ docs/

Suggested revision to the plugin blurb: add Brazilian LAI requests to the list after FOIA + NJ OPRA requests.

3. `CHANGELOG.md`

### Added
- `brazil-records-requests` (#266): public records requests under Brazil's
  Access to Information Law (Lei 12.527/2011). Covers portal selection across
  federal, state, municipal, judicial and legislative bodies; the 20+10 day
  response deadlines; the four-level appeal chain (immediate superior, agency
  head, CGU, CMRI); denial diagnosis, including the art. 13 grounds of Decree
  7.724/2012; and six request and appeal templates in Portuguese with English
  glosses. First non-US jurisdiction in `journalism-core`. Triggers on both
  Portuguese and English prompts and does not collide with `foia-requests`.

Follow the existing changelog's version-heading convention, this is a journalism-core minor bump, not a patch.

4. Plugin manifest

Check .claude-plugin/marketplace.json and any plugin.json under journalism-core/ for a skill list, a count, or a description string that names the skills. Update whichever exist.

grep -rn "foia-requests" --include="*.json" .

That grep finds every manifest that enumerates skills, wherever foia-requests is listed, brazil-records-requests belongs too.

5. Docs landing page

The changelog mentions docs/<skill>/index.html landing pages per skill. If that pattern still holds, either add one following the existing template or say in the PR that you left it for the maintainer's generator, ask, don't guess.

Before opening the PR

Statutory citations verified against the current text on planalto.gov.br
Installed to ~/.claude/skills/ and triggered on the three test prompts
Confirmed no trigger collision with foia-requests on US prompts
No AI attribution anywhere in commit messages or file contents
Sentence case in all headings
Branch is off current master

2.8 KiB Raw Permalink Blame History