@natjswenson/devlog 0.10.0 → 0.11.1

package/evals/baseline/published/ghostwriter-v0.8.1.md

@@ -0,0 +1,221 @@
+---
+title: "How to turn a folder of Claude Code skills into a discoverable plugin marketplace"
+date: 2026-07-11
+project: ghostwriter
+version: v0.8.1
+tags: [claude-code, plugin-marketplace, skill-md, monorepo, ci, json-lint, developer-tooling]
+summary: "Ghostwriter moved from a manual symlink install to a real Claude Code plugin, which meant learning the marketplace.json/plugin.json schema and one directory-nesting rule that Claude Desktop enforces and the CLI quietly didn't."
+---
+
+## Shipped
+
+Ghostwriter, and three sibling skills in the same repo, switched from a manual "symlink this folder into `~/.claude/skills`" install to a real Claude Code plugin: each skill got a `.claude-plugin/plugin.json`, the repo root got a `.claude-plugin/marketplace.json` listing all four, and install became `/plugin marketplace add` + `/plugin install`. A day later, a follow-up release moved every skill's `SKILL.md` one directory deeper, because the first version worked fine from the command line and silently didn't work in Claude Desktop. That gap, and the two lint scripts written to make sure it can't reopen, is the part worth walking through.
+
+## What a plugin marketplace actually is
+
+A marketplace is nothing more than a JSON file. Per the [Claude Code docs](https://code.claude.com/docs/en/plugin-marketplaces), "create `.claude-plugin/marketplace.json` in your repository root. This file defines your marketplace's name, owner information, and a list of plugins with their sources." Each entry needs a `name` and a `source`; for a monorepo, the source is just a relative path:
+
+```json
+{
+  "name": "my-tools",
+  "owner": { "name": "You" },
+  "plugins": [
+    { "name": "formatter", "source": "./plugins/formatter" }
+  ]
+}
+```
+
+Each plugin listed there is, in turn, its own self-contained directory with a `.claude-plugin/plugin.json`:
+
+```json
+{
+  "name": "formatter",
+  "version": "1.0.0",
+  "description": "Formats code on save"
+}
+```
+
+Once both files exist, `/plugin marketplace add ./my-tools` followed by `/plugin install formatter@my-tools` is the entire install, and `/plugin marketplace update` picks up new pushes. No symlinks, no README with manual copy steps.
+
+## Where the skill's content actually lives
+
+This is the part that isn't obvious from the schema alone. The docs describe the skill location as: "**Location**: `skills/` or `commands/` directory in plugin root, or a single `SKILL.md` file at the plugin root," and then add the detail that matters here: "If a plugin has no `skills/` directory and no `skills` manifest field, a `SKILL.md` at the plugin root is loaded as a single skill. Set the frontmatter `name` field to control the skill's invocation name. Without it, Claude Code falls back to the install directory name, which for marketplace-installed plugins is a version string that changes on every update" ([Plugins reference](https://code.claude.com/docs/en/plugins-reference)).
+
+So a root-level `SKILL.md` is documented and supported, as long as its frontmatter names itself explicitly. What happened here was a real-world gap between two Claude Code surfaces: the CLI tolerated the four skills' root-level `SKILL.md` files, but Claude Desktop, after installing the same plugin from the same marketplace entry, reported "This plugin doesn't have any skills or agents." The fix was to nest each skill one directory deeper:
+
+```text
+formatter/
+├── .claude-plugin/
+│   └── plugin.json
+└── skills/
+    └── formatter/
+        └── SKILL.md
+```
+
+```markdown
+---
+name: formatter
+description: Formats the current file
+---
+
+Format the selected file using the project's configured formatter.
+```
+
+That's the layout used above to build the verification scripts below, and it's also what the docs recommend outright for anything beyond a single trivial skill: "For plugins that ship more than one skill, use the `skills/` directory layout." Anthropic's own [official plugin catalog](https://github.com/anthropics/claude-plugins-official) follows the same pattern; its `skill-creator` plugin, for example, nests its skill at `plugins/skill-creator/skills/skill-creator/`, not at the plugin root.
+
+## Build it: a name-consistency lint for one plugin
+
+The nesting fix solves the immediate problem, but it opens a new one: now three separate files each carry the plugin's name (`plugin.json`, the directory itself, `SKILL.md`'s frontmatter), and nothing stops them from drifting apart. A rename in one place and not the other two produces a plugin that installs cleanly and then can't be found under the name anyone expects. The fix is a lint script that checks all three agree:
+
+```python
+#!/usr/bin/env python3
+"""Checks that a plugin's name stays consistent across its manifest, its
+directory, and its skill's frontmatter."""
+import json
+import os
+import re
+import sys
+
+
+def parse_skill_name(skill_md_text):
+    match = re.search(r'^name:\s*(\S+)', skill_md_text, re.MULTILINE)
+    return match.group(1) if match else None
+
+
+def lint_plugin(plugin_dir):
+    errors = []
+    dir_name = os.path.basename(os.path.normpath(plugin_dir))
+
+    plugin_json_path = os.path.join(plugin_dir, ".claude-plugin", "plugin.json")
+    with open(plugin_json_path) as fh:
+        plugin_data = json.load(fh)
+    plugin_name = plugin_data.get("name")
+
+    if plugin_name != dir_name:
+        errors.append(
+            f"plugin.json name {plugin_name!r} != directory name {dir_name!r}"
+        )
+
+    skill_md_path = os.path.join(plugin_dir, "skills", dir_name, "SKILL.md")
+    if os.path.isfile(skill_md_path):
+        with open(skill_md_path) as fh:
+            skill_name = parse_skill_name(fh.read())
+        if skill_name != plugin_name:
+            errors.append(
+                f"SKILL.md name {skill_name!r} != plugin.json name {plugin_name!r}"
+            )
+
+    return errors
+
+
+if __name__ == "__main__":
+    errs = lint_plugin(sys.argv[1])
+    if errs:
+        for e in errs:
+            print(f"FAIL: {e}")
+        sys.exit(1)
+    print("OK")
+```
+
+## Build it: a membership lint for the marketplace file
+
+A single plugin passing its own lint doesn't guarantee the marketplace entry pointing at it is correct. A copy-pasted entry can have the right shape (a `name` and a valid `source`) while pointing at the wrong plugin directory entirely, which a naive "does this name exist somewhere in the plugin set" check won't catch. The check needs to tie each entry's name, its source's directory basename, and that directory's own `plugin.json.name` together as one three-way match, not three independent lookups:
+
+```python
+#!/usr/bin/env python3
+"""Checks marketplace.json against the plugin.json files it references:
+every entry resolves, and no entry is cross-wired to the wrong plugin."""
+import glob
+import json
+import os
+import sys
+
+
+def lint_marketplace(repo_root):
+    errors = []
+    marketplace_path = os.path.join(repo_root, ".claude-plugin", "marketplace.json")
+    with open(marketplace_path) as fh:
+        data = json.load(fh)
+
+    entry_names = set()
+    for entry in data.get("plugins", []):
+        entry_name = entry["name"]
+        source_dir = os.path.normpath(os.path.join(repo_root, entry["source"]))
+        source_plugin_json = os.path.join(source_dir, ".claude-plugin", "plugin.json")
+
+        if not os.path.isfile(source_plugin_json):
+            errors.append(f"entry {entry_name!r}: no plugin.json at {entry['source']}")
+            continue
+
+        with open(source_plugin_json) as fh:
+            source_name = json.load(fh).get("name")
+
+        # Per-row three-way tie: catches a cross-wired entry (right shape,
+        # wrong target) that a set-membership check alone would miss.
+        source_basename = os.path.basename(source_dir)
+        if entry_name != source_basename or source_name != entry_name:
+            errors.append(
+                f"entry {entry_name!r}: basename={source_basename!r}, "
+                f"plugin.json.name={source_name!r} -- all three must match"
+            )
+        entry_names.add(entry_name)
+
+    dirs_with_plugin_json = {
+        os.path.basename(os.path.dirname(os.path.dirname(p)))
+        for p in glob.glob(os.path.join(repo_root, "plugins", "*", ".claude-plugin", "plugin.json"))
+    }
+    orphans = dirs_with_plugin_json - entry_names
+    if orphans:
+        errors.append(f"plugin directories with no marketplace entry: {sorted(orphans)}")
+
+    return errors
+
+
+if __name__ == "__main__":
+    errs = lint_marketplace(sys.argv[1])
+    if errs:
+        for e in errs:
+            print(f"FAIL: {e}")
+        sys.exit(1)
+    print("OK")
+```
+
+## Use it, then break it on purpose
+
+Run both against a correctly wired plugin and marketplace:
+
+```text
+$ python3 lint_plugin.py my-tools/plugins/formatter
+OK
+$ python3 lint_marketplace.py my-tools
+OK
+```
+
+Now rename only `plugin.json`'s `name` field, leaving the directory and `SKILL.md` untouched, the exact drift a careless rename produces:
+
+```text
+$ python3 lint_plugin.py my-tools/plugins/formatter
+FAIL: plugin.json name 'code-formatter' != directory name 'formatter'
+FAIL: SKILL.md name 'formatter' != plugin.json name 'code-formatter'
+$ python3 lint_marketplace.py my-tools
+FAIL: entry 'formatter': basename='formatter', plugin.json.name='code-formatter' -- all three must match
+```
+
+Both scripts catch it immediately, and both point at exactly which file disagrees with which. Wire either one into CI as a pre-merge check and this class of bug never reaches a released plugin.
+
+## Gotchas
+
+**A root-level `SKILL.md` worked in the CLI and silently failed in Desktop.** The CLI accepted a plugin whose `SKILL.md` sat directly at the plugin root; Claude Desktop, installing from that same marketplace entry, reported the plugin had no skills or agents at all. Nothing in either surface raised an error at publish time, so the first sign of trouble was a teammate opening Desktop after the marketplace conversion had already shipped. The fix, and the safer default going forward, is the nested `skills/<name>/SKILL.md` layout described above, plus setting the frontmatter `name` explicitly rather than relying on the install-directory fallback.
+
+**Nesting the skill one directory deeper broke a test that assumed the old layout.** A version-consistency test read `CHANGELOG.md` relative to the skill's own directory, which worked when `CHANGELOG.md` sat next to `SKILL.md`. After the nesting fix moved `SKILL.md` down a level, `CHANGELOG.md` deliberately stayed at the outer plugin root, so the test's relative path pointed at the wrong location. CI caught it on the same pull request, which is the case for this kind of refactor: a path assumption baked into a test is invisible until something that isn't the test itself moves.
+
+## Sources
+
+- [Create and distribute a plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) — the marketplace.json/plugin.json schema and the required `name`/`source` fields.
+- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) — the skill discovery rules, including the root-`SKILL.md` fallback and its version-string caveat.
+- [anthropics/claude-plugins-official](https://github.com/anthropics/claude-plugins-official) — confirms the nested `skills/<name>/SKILL.md` layout in a real, official plugin (`skill-creator`).
+
+## Changelog
+
+- fix: nest SKILL.md under skills/<name>/ so plugins are discoverable (#32) ([cd9bc5b](https://github.com/natejswenson/claude-skills/commit/cd9bc5b94453c2f70632e1c784e8fcf878dfda7a))
+- feat: convert claude-skills into a Claude Code plugin marketplace (#30) ([7537f10](https://github.com/natejswenson/claude-skills/commit/7537f103c73283a82e5432e99f552d206ccb808c))

package/evals/baseline/published/local-fitness-v0.25.0.md

@@ -0,0 +1,233 @@
+---
+title: "Grading a workout without failing every easy day"
+date: 2026-07-20
+project: local-fitness
+version: v0.25.0
+tags: [scoring, rubric-design, product-design, median, robust-statistics, python, llm, pytest]
+summary: "Any system that grades a user against their own history hits the same wall: the naive rubric punishes the behavior you asked for. Four design decisions fix it, and a real graded report card shows what each one is worth."
+---
+
+## Shipped
+
+This release added a graded report card for a single workout. Four metrics, letter
+grades, an overall, and a written read on top. Before it, my fitness agent could
+describe a run but never judge one, so the same workout got called "solid" one day
+and "flat" the next depending on how the model felt.
+
+Here is a real card, for a real run:
+
+![A generated report card: overall grade B for a 3.06 mile run, with distance A, pace C, average heart rate A+, and training load A, plus a per-mile table and a heart-rate chart.](/devlog-assets/local-fitness/v0.25.0-report-card.png)
+
+The grading is plain Python, not model output. The model gets the four paragraphs
+at the top and is told the letters are not its to revise. That division is the easy
+part to agree with. The hard part is the rubric itself, and the decisions behind it
+transfer to anything that scores a user against their own past: a reading streak,
+a support queue, a spend budget. That is what this post is about, so it stays on
+the decisions rather than walking you through building a fitness app.
+
+## Read the card before reading the code
+
+Look at the pace row. The plan prescribed 10:28 per mile; the run came in at 9:28.
+A full minute per mile faster, and it scores a **C** while the heart rate row scores
+an A+.
+
+That combination is the entire design problem in one screenshot. A naive rubric
+would have done the opposite on both counts. It would have rewarded running faster,
+because faster is better in almost every system anyone has ever built. And it would
+have punished a heart rate below the runner's norm, because lower is better right
+up until it isn't.
+
+Both instincts are wrong here, for the same reason: **the expected behavior was not
+"maximize."** It was "stay easy." Distance from normal is not the same thing as
+failure, and a rubric that cannot tell them apart will fail every deliberate
+deviation you ever asked a user to make.
+
+## Decision 1: collapse every metric to one number
+
+The temptation with four metrics is four scoring functions. Resist it. Reduce each
+metric to a single non-negative relative deviation, then push all of them through
+one shared band table.
+
+```python
+GRADE_BANDS = ((0.05, "A"), (0.10, "B"), (0.20, "C"), (0.35, "D"))
+
+
+def grade_from_deviation(d, widen=1.0):
+    """One deviation to one letter. `widen` scales every boundary at once:
+    above 1.0 for a loose reference, below 1.0 for an explicit instruction."""
+    if d is None:
+        return None          # ungradeable stays out of the average entirely
+    d = max(0.0, float(d))
+    for threshold, letter in GRADE_BANDS:
+        if d <= threshold * widen + 1e-9:
+            return letter
+    return "F"
+```
+
+Four deviation functions and one grader means the rubric has exactly one place where
+strictness lives. When a grade looks wrong, you are debugging one table, not four
+scattered thresholds that drifted apart over six months.
+
+The `widen` parameter is doing more work than it looks. It is the seam that lets one
+table serve expectations of very different confidence, which turns out to matter a
+lot. More on that in decision 3.
+
+`None` propagating through is the other quiet load-bearing bit. A metric you cannot
+grade must be *absent* from the average, not zero. Renormalize by the weights you
+actually used, or a missing heart rate reading silently drags a good workout down.
+
+## Decision 2: gate the deviation by direction
+
+This is the one that rescues the easy run, and it is three lines.
+
+```python
+def pace_deviation(actual, expected, intent):
+    """Pace is seconds per mile, so LOWER is faster."""
+    if intent in ("easy", "long"):
+        return max(0.0, (expected - actual) / expected)   # only too FAST costs
+    if intent == "quality":
+        return max(0.0, (actual - expected) / expected)   # only too SLOW costs
+    return abs(actual / expected - 1.0)                   # no stated intent
+```
+
+An easy day is penalized for being too fast and never for being too slow. A tempo
+day is the mirror image. Anything without a stated intent falls back to a two-sided
+comparison with deliberately wider bands, because you are guessing.
+
+The general form: **before you can grade a deviation you have to know which
+direction was the point.** Most scoring systems skip this because most metrics look
+like "more is better," and then they quietly punish exactly the restraint they were
+built to encourage. If your product ever tells a user to slow down, spend less, or
+close fewer tickets on purpose, an absolute-difference rubric will grade that
+instruction as a failure.
+
+Note the same logic on the card's other rows. Distance is one-sided against the
+rolling median, because running longer than usual is never a penalty, but two-sided
+against a plan, because a 12-miler on a 10-mile prescription is overcooking it.
+Heart rate is graded against a *range* rather than a point, which is why its row
+reads "in range" instead of a percentage.
+
+## Decision 3: pick a reference, then say which one you used
+
+Every expectation needs a source, and there are only two honest ones: something the
+user was told to do, or something the user typically does. The card names its source
+on every row. Distance and pace here say `plan`; heart rate and load fall back to a
+60-day rolling median, because the plan has no column for them.
+
+Three rules make that fallback trustworthy.
+
+**Use the median, not the mean.** Python's own docs are blunt that the mean ["is
+strongly affected by outliers"](https://docs.python.org/3/library/statistics.html)
+while the median ["is a robust measure of central location."](https://docs.python.org/3/library/statistics.html)
+NIST's handbook explains the mechanism in a sentence: ["Extreme values in the tails
+distort the mean. However, these extreme values do not distort the median since the
+median is based on ranks."](https://www.itl.nist.gov/div898/handbook/eda/section3/eda351.htm)
+Every real activity history contains a race, a sensor fault, or a once-a-year
+effort, and each one drags a mean.
+
+**Refuse to grade on a thin reference.** Under five comparable activities, the card
+returns n/a and says so. Grading against two data points is worse than not grading,
+because a letter looks equally authoritative either way.
+
+**Only compare like with like.** More on that in the gotchas; it is where I got this
+most wrong.
+
+And the tightening rule from decision 1 lands here. **A plan target is an
+instruction; a rolling median is a reference.** They are both just an expected value
+in code, which makes it natural to grade them identically, but they carry completely
+different confidence. So plan-referenced bands are scaled by 0.6.
+
+You can check that arithmetic against the card. Sixty seconds against a 628-second
+target is a 9.6% deviation. Under the plain bands that sits inside B, near the
+bottom of it; the real grader adds a +/- for position within a band, so it renders
+B-. Tightened for a prescription the same deviation crosses into C, which is what
+the card shows. That one multiplier is the difference between a card that says B-
+and hands out an overall A, and a card that says C, which is the honest verdict for
+a prescribed easy run executed a minute per mile too hot.
+
+## Decision 4: display the number you actually graded against
+
+Look at the heart rate row: actual 136, expected "≤ 142 bpm", delta "in range."
+
+An earlier version printed the bare rolling median in that column instead. A run at
+136 against a 146 median rendered as "-7%" sitting next to a B+, when the real
+finding was that it sat 6% *above* the ceiling that produced the grade. Every number
+in the row was individually true and the row as a whole was incoherent.
+
+If a metric is judged against a band, the band is what goes in the expected column.
+This is the cheapest correctness check you can build into a scoring UI: **a user
+must be able to recompute your grade from the numbers you showed them.** If they
+can't, the grade reads as a black box no matter how principled the code behind it is.
+
+## Gotchas
+
+**Pooling incomparable categories poisons the reference.** My first version pooled
+all running together. Treadmill and road are different heart rate regimes, and on
+live data the mixed pool put median heart rate at 119 against an outdoor average
+near 140, which handed a perfectly normal easy outdoor run a D. The rubric was
+reporting an artifact of the pool, not a judgment. Symptom: a grade that moves when
+unrelated activity is added to the history, with no change to the graded item. The
+escape is exact-category first, widening only when that pool is too thin, and saying
+on the card when it widened.
+
+**Bands calibrated on intuition rather than on your distribution.** My original
+easy-heart-rate ceiling was 0.88 of the median, which sounds reasonable and was
+unreachable. The reference median is taken over all comparable activity, and for a
+runner whose training is mostly easy, that median already sits near easy heart rate.
+Demanding 12% below it asked for a number that appeared in 1 of 13 runs in the
+window, and the one that qualified looks like a sensor fault. Heart rate became a
+standing penalty rather than a judgment. Before changing a bound, check what
+fraction of real history clears it. If the answer is "almost none," you wrote a
+constant, not a criterion.
+
+**A card that contradicts its own coaching text.** Before the plan-tightening rule,
+this same run scored an overall A while the written read said the runner never ran
+easy at all. Two subsystems, one computing grades and one describing them, disagreeing
+in public. Worth building a check for whenever a generated summary sits next to
+generated numbers.
+
+**Grade only what you can grade for everyone.** The per-mile table on the card is
+presentation, not input; no grade reads it. Only 87 of 747 activities in my database
+have per-lap splits, because the daily sync writes them and the historical backfill
+never did. A splits-dependent grade would be unavailable on 88% of history and would
+quietly mean different things on different rows. Same for the heart rate trace under
+the chart, which is fetched on demand for one activity rather than backfilled.
+
+**Adding an LLM to a tool will put your test suite on the network.** The read at the
+top of the card is a model call, and every render generates one, so the moment tests
+rendered a card they were making real API calls. The suite went from 10 seconds to 7
+minutes, cost real money, and stayed green throughout, which is why nobody noticed.
+Block it at the choke point with an autouse fixture, the same shape pytest's own docs
+use to remove `requests.sessions.Session.request` so ["any attempts within tests to
+create http requests will fail"](https://docs.pytest.org/en/stable/how-to/monkeypatch.html):
+
+```python
+@pytest.fixture(autouse=True)
+def _no_live_model_calls(monkeypatch):
+    """Patch the single SDK entrypoint every generator funnels through, so a
+    module added next month inherits this without anyone wiring it up."""
+    import my_llm_sdk
+
+    def _blocked(*args, **kwargs):
+        raise RuntimeError("Live model call in a test. Patch the generator.")
+
+    monkeypatch.setattr(my_llm_sdk, "query", _blocked)
+```
+
+Two things make it work. Patch the one entrypoint rather than each call site. And
+make sure callers degrade to a deterministic fallback, so the raise becomes the
+offline path and the default test run exercises it. An autouse fixture is one that
+[all tests automatically request](https://docs.pytest.org/en/stable/how-to/fixtures.html)
+without naming it, and in a `conftest.py` it covers every test in that directory and
+below.
+
+## Sources
+
+- [`statistics` module, Python docs](https://docs.python.org/3/library/statistics.html) — the median as a robust measure of central location versus the mean's sensitivity to outliers.
+- [Measures of location, NIST/SEMATECH e-Handbook of Statistical Methods](https://www.itl.nist.gov/div898/handbook/eda/section3/eda351.htm) — why extreme values distort the mean but not a rank-based statistic.
+- [monkeypatch, pytest docs](https://docs.pytest.org/en/stable/how-to/monkeypatch.html) — the autouse-fixture pattern for blocking remote calls across a suite.
+- [Fixtures, pytest docs](https://docs.pytest.org/en/stable/how-to/fixtures.html) — how `autouse=True` reaches every test in a directory tree.
+
+## Changelog
+
+- feat: workout_report_card — graded per-workout report card with coach read and HR/pace chart (0.25.0) (#125) (#126) ([724a1ab](https://github.com/natejswenson/local-fitness/commit/724a1abca6ac276ae891a06a97bd19af4bb8f84f))

package/evals/baseline/published/resume-v1.0.1.md

@@ -0,0 +1,129 @@
+---
+title: "How to tell which package in a monorepo actually needs a release"
+date: 2026-07-11
+project: resume
+version: v1.0.1
+tags: [git, monorepo, semver, release-engineering, tagging, path-filter, ci-cd]
+summary: "Two sibling packages in the same repo both got a patch release from the exact same commit. Here's the git-tag-plus-path-filter technique that tells you which packages actually need a release when one commit touches all of them."
+---
+
+## Shipped
+
+Four sibling skills in one repo all got a `.claude-plugin/plugin.json` and a `CHANGELOG.md` entry in the same two commits, part of [converting the whole repo into a Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Two of those four, resume and a sibling skill, immediately got a real git release tag cut for it (`resume-v1.0.1`); the other two didn't, at least not yet. That split is the actual topic here: how do you decide, mechanically, which package in a monorepo genuinely needs a release when one commit touches several of them at once?
+
+## The problem with one shared commit
+
+A monorepo with several independently versioned packages runs into this the first time an infrastructure change lands in one commit that legitimately touches every package: a CI migration, a lint rule, a shared build script. Every package's code changed, so does every package deserve a new release? A single repo-wide version number sidesteps the question by making everything one release, but that has its own cost. As one team's writeup on this puts it plainly: with a unified version "we would have to 'build the world' every time there is an update to the repo," which stopped being feasible once "some of the components take >15min to build" ([Streamdal: Monorepos: Version, Tag, and Release Strategy](https://streamdal.com/blog/monorepos-version-tag-and-release-strategy/)). Per-package versioning avoids that, but only if there's a mechanical way to tell "this package's code changed" from "this package needs a new tag."
+
+## Build it: a tag prefix per package
+
+The standard fix, and the one used here, is a distinct tag prefix per package instead of one shared version:
+
+```text
+resume-v1.0.0
+resume-v1.0.1
+ghostwriter-v0.8.0
+ghostwriter-v0.8.1
+```
+
+Per the same writeup, this "is not valid semantic versioning but it is a common approach to tagging multiple components that live within the same repository." It buys three things a single repo version can't: only the changed package needs its build/release pipeline to run, tag volume stays proportional to actual releases per package instead of exploding with every commit, and `git tag -l 'resume-v*'` alone answers "what has resume shipped" without touching any other package's history.
+
+## Build it: deciding when a shared commit earns a package its own tag
+
+A prefix alone doesn't answer the actual question, though: given a commit that touches multiple packages, which of those packages' tag prefixes should include it? The rule that works is a path filter checked against the commit range since that package's last tag, not against the commit in isolation:
+
+```python
+#!/usr/bin/env python3
+"""Finds git tags that represent a real release for one package in a
+monorepo: a tag matching that package's prefix, with commits since the
+previous matching tag that actually touch that package's path."""
+import subprocess
+import sys
+
+
+def run(*args):
+    return subprocess.run(
+        ["git", *args], cwd=sys.argv[1], capture_output=True, text=True, check=True
+    ).stdout.strip()
+
+
+def tags_for_prefix(prefix):
+    all_tags = run("tag", "--sort=creatordate").splitlines()
+    return [t for t in all_tags if t.startswith(prefix)]
+
+
+def find_releases(prefix, path_filter):
+    tags = tags_for_prefix(prefix)
+    releases = []
+    for i, tag in enumerate(tags):
+        prev_tag = tags[i - 1] if i > 0 else None
+        commit_range = f"{prev_tag}..{tag}" if prev_tag else tag
+        commits = run("log", "--oneline", commit_range, "--", path_filter)
+        if commits:
+            releases.append((tag, prev_tag, commits.splitlines()))
+    return releases
+
+
+if __name__ == "__main__":
+    prefix, path_filter = sys.argv[2], sys.argv[3]
+    for tag, prev_tag, commits in find_releases(prefix, path_filter):
+        print(f"{tag} (since {prev_tag or 'repo start'}): {len(commits)} commit(s)")
+        for c in commits:
+            print(f"  {c}")
+```
+
+The `-- <path_filter>` on `git log` is what makes this a per-package answer instead of a repo-wide one: it only returns commits in that range that touched files under the package's own directory, silently dropping commits that only touched other packages.
+
+## Use it, then verify it against a real shared commit
+
+To see this handle the actual scenario, a two-package repo with a shared infrastructure commit at the end:
+
+```text
+$ git log --oneline --all
+c96fcda feat: convert all packages into plugin-installable format
+50e7884 feat: initial api and worker
+dcb1bb6 feat(api): add health check endpoint
+$ git tag
+api-v1.0.0
+api-v1.1.0
+api-v1.2.0
+worker-v1.0.0
+worker-v1.1.0
+```
+
+`api-v1.2.0` and `worker-v1.1.0` were both tagged at `c96fcda`, the shared commit. Running the script for each package:
+
+```text
+$ python3 find_releases.py . api-v packages/api
+api-v1.0.0 (since repo start): 1 commit(s)
+  50e7884 feat: initial api and worker
+api-v1.1.0 (since api-v1.0.0): 1 commit(s)
+  dcb1bb6 feat(api): add health check endpoint
+api-v1.2.0 (since api-v1.1.0): 1 commit(s)
+  c96fcda feat: convert all packages into plugin-installable format
+
+$ python3 find_releases.py . worker-v packages/worker
+worker-v1.0.0 (since repo start): 1 commit(s)
+  50e7884 feat: initial api and worker
+worker-v1.1.0 (since worker-v1.0.0): 1 commit(s)
+  c96fcda feat: convert all packages into plugin-installable format
+```
+
+The shared commit `c96fcda` correctly shows up as the release-triggering commit for both packages, each under its own path filter, while `dcb1bb6` (an api-only commit) never appears in worker's list at all. That's the whole answer: a package gets a release when its own path filter finds real commits in the range, whether or not other packages' commits happen to share the same hash.
+
+## Gotchas
+
+**A version bump in a manifest file is not the same signal as a release tag.** In the run that prompted this, four sibling packages all got their `plugin.json` version field and `CHANGELOG.md` bumped in the exact same commit. Two of them also got a fresh git tag cut for that bump; two didn't, at least not at the time of writing. Anything downstream that keys off "which packages were released" by scanning git tags, the way the script above does, would miss those two entirely, even though their manifest files genuinely changed. If a release-detection process reads tags, a manifest bump with no matching tag is invisible to it, whether that's an oversight or a deliberate choice to hold that package's release for later. Either way, don't assume a changed version field implies a cut release; check the tag. It's the same risk the [npm blog's monorepo writeup](https://blog.npmjs.org/post/186494959890/monorepos-and-npm.html) names directly: "asking humans to remember to do this across a large collection of packages... is asking for trouble." A tag-scanning script doesn't get to forget; a human bumping four manifest files by hand can, and evidently did for two of them.
+
+**A shared commit read as duplicate content the first time through, not as two separate release stories.** Writing this pair of posts, the two package's commit ranges resolved to the exact same two commits, because that's genuinely what happened. The first pass toward the two writeups almost retold the whole marketplace-conversion story twice. The fix was deciding up front which package's post owns the full narrative and giving the other one a genuinely different angle instead, the technique this post covers, rather than two copies of the same walkthrough with the package name swapped.
+
+## Sources
+
+- [Streamdal: Monorepos: Version, Tag, and Release Strategy](https://streamdal.com/blog/monorepos-version-tag-and-release-strategy/) — the per-package tag-prefix pattern and why a single repo-wide version breaks down.
+- [npm Blog Archive: Monorepos and npm](https://blog.npmjs.org/post/186494959890/monorepos-and-npm.html) — on the risk of lockstep versioning: "asking humans to remember to do this across a large collection of packages... is asking for trouble," the human-error case for a mechanical check over a manual convention.
+- [Create and distribute a plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) — background on the plugin conversion that produced the shared commit this post's example is drawn from.
+
+## Changelog
+
+- fix: nest SKILL.md under skills/<name>/ so plugins are discoverable (#32) ([cd9bc5b](https://github.com/natejswenson/claude-skills/commit/cd9bc5b94453c2f70632e1c784e8fcf878dfda7a))
+- feat: convert claude-skills into a Claude Code plugin marketplace (#30) ([7537f10](https://github.com/natejswenson/claude-skills/commit/7537f103c73283a82e5432e99f552d206ccb808c))

package/examples/react/useDevLogEntries.js

@@ -34,6 +34,8 @@ function validateManifest(data) {
   const entries = [];
   for (const e of data.entries) {
     if (!e || typeof e !== 'object') continue;
+    // Tombstoned rows (removed: true) are editorial retirements, not entries.
+    if (e.removed) continue;
     const { date, file, title, summary, version } = e;
     if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
     if (typeof file !== 'string' || !/^[a-zA-Z0-9._-]+\.md$/.test(file)) continue;