skills/jamditis__claude-skills-journalism
1
0
Fork 0
mirror of https://github.com/jamditis/claude-skills-journalism.git synced 2026-09-14 16:00:34 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
jamditis__claude-skills-jou…/hooks/accessibility-check.md
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

3.3 KiB
Raw Permalink Blame History

name, description, event, tools
name description event tools
accessibility-check Check for alt text, heading structure, and accessibility in content PostToolUse
Write
Edit

Accessibility check hook

After writing content, check for accessibility issues that would exclude readers with disabilities.

When this hook fires

  • After Write tool creates content with images or complex structure
  • After Edit tool adds media or formatting
  • When content includes HTML, Markdown with images, or data visualizations

What to check

Images without alt text

❌ ![](image.jpg)
❌ <img src="photo.jpg">

✅ ![Mayor Smith speaks at podium during press conference](image.jpg)
✅ <img src="photo.jpg" alt="Chart showing crime rates declining 15% from 2020 to 2024">

Decorative images not marked

✅ ![](decorative-border.png){aria-hidden="true"}
✅ <img src="icon.svg" alt="" role="presentation">

Heading hierarchy

❌ # Title
    ### Skipped to h3
    ## Then h2

✅ # Title
    ## Section
    ### Subsection

Link text

❌ Click [here](url) to read more
❌ [Read more](url)

✅ Read the [full report on housing costs](url)
✅ [Housing cost report (PDF, 2.3MB)](url)

Color-only information

⚠️ Chart uses only color to distinguish categories
   Add: Pattern, label, or shape differentiation

Data tables

❌ | | Column A | Column B |
   |---|---|---|

✅ | Category | 2023 | 2024 |
   |---|---|---|
   With proper headers and scope

Accessibility checklist

📋 Accessibility checklist:

Images:
- [ ] All images have descriptive alt text
- [ ] Alt text describes content, not just "image of..."
- [ ] Decorative images marked as such
- [ ] Complex images (charts) have detailed descriptions

Structure:
- [ ] Headings follow logical hierarchy (h1 → h2 → h3)
- [ ] No heading levels skipped
- [ ] Content readable without styles

Links:
- [ ] Link text describes destination
- [ ] No "click here" or "read more" alone
- [ ] File type/size noted for downloads

Media:
- [ ] Videos have captions
- [ ] Audio has transcript
- [ ] Auto-play disabled or controllable

Data:
- [ ] Tables have proper headers
- [ ] Charts don't rely only on color
- [ ] Data available in text form

Output format

⚠️ Accessibility check:

Issues found:
- Line [X]: Image missing alt text
- Line [X]: Heading jumps from h1 to h3
- Line [X]: Link text "click here" is not descriptive

Accessibility ensures all readers can access your journalism.

Alt text guidance

Good alt text for journalism:

Image type Alt text approach
News photo Describe key action, people, context
Headshot "Name, title" or "Name speaking at event"
Chart Summarize the main finding
Map Describe what it shows and key locations
Document "Screenshot of [document] showing [key info]"

Example:

![Protesters march down Main Street holding signs that read "Save Our Schools" as police officers watch from the sidewalk](protest.jpg)

Non-blocking

This hook flags issues but doesn't prevent publication. Prioritize fixes based on impact, missing alt text on key images is more critical than minor heading issues.

Skip conditions

Skip for:

  • Plain text files without markup
  • Code files
  • Internal notes/drafts
Reference in New Issue View Git Blame Copy Permalink