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

3.7 KiB

Raw Permalink Blame History

Contributing

Thanks for your interest in contributing to this skill collection. Whether you're fixing a bug, improving an existing skill, or proposing a new one, this guide will help you get started.

Quick start

Fork the repository
Clone your fork: git clone https://github.com/YOUR-USERNAME/claude-skills-journalism.git
Create a branch: git checkout -b my-skill-or-fix
Make your changes
Test with Claude Code locally
Submit a pull request

Adding a new skill

Directory structure

Each skill lives in its own directory at the repo root:

skill-name/
├── SKILL.md          # Main instructions (required)
├── templates/        # Reusable templates (optional)
├── examples/         # Example inputs/outputs (optional)
└── scripts/          # Helper scripts (optional)

SKILL.md format

Every skill needs a SKILL.md file with YAML frontmatter:

---
name: skill-name
description: When to use this skill and what it does
---

# Skill title

Instructions, workflows, and knowledge for Claude to use.

The description field is what Claude uses to decide when to activate the skill, so make it specific about trigger conditions.

Skill guidelines

Focus area: journalism, media, communications, academic, or technical workflows that support those fields
Actionable content: include workflows and decision trees, not just reference info
Templates: provide templates where applicable, they make skills immediately useful
Sources: cite standards, style guides, or verification methods you reference
Sentence case: use sentence case for all headings, not title case
No AI slop: avoid the banned words and patterns listed in the ai-writing-detox skill

Testing your skill

Before submitting:

Install the skill locally: cp -r your-skill/ ~/.claude/skills/
Start a Claude Code session
Give it a prompt that should trigger the skill
Verify it activates and produces useful output
Test edge cases and different prompt phrasings

Adding a hook

Hooks are single markdown files in the hooks/ directory. Each hook has frontmatter specifying when it runs:

---
name: hook-name
description: What this hook checks
event: PostToolUse | PreToolUse | UserPromptSubmit | Stop | SessionStart
tools: [Write, Edit]  # for Pre/PostToolUse hooks
---

Hook instructions here.

All hooks should be non-blocking warnings, they provide guidance but don't prevent actions.

Improving existing skills

Improvements to existing skills are welcome. Common areas:

Adding templates for new use cases
Expanding workflows with missing steps
Fixing outdated references or broken links
Adding examples that demonstrate the skill in action

Reporting bugs

Use the bug report template to file issues. Include your Claude Code version (claude --version) and steps to reproduce.

Proposing new skills

Use the skill request template to propose ideas. Describe the target audience, key workflows, and any reference materials.

Style guide

Sentence case for all headings
Keep descriptions short and direct
Avoid AI writing patterns (see ai-writing-detox)
Include actionable steps, not just theory
Cite your sources

Code of conduct

This project follows the Contributor Covenant. Be respectful and constructive.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

3.7 KiB Raw Permalink Blame History