Skip to content

Stop the skills from producing a README alongside the deck or doc - #26

Merged
glukicov merged 1 commit into
mainfrom
claude/skills-readme-output-spplh2
Sep 3, 2026
Merged

glukicov merged 1 commit into
mainfrom
claude/skills-readme-output-spplh2

Conversation

@glukicov

@glukicov glukicov commented Sep 3, 2026

Copy link
Copy Markdown
Owner

What this changes, and why

Step 6 told the agent to write or extend a shared README.md next to every deck, one
section per deck in the folder. That file was the only artifact of a build that carried no
citations, so it was the one thing check.py could not keep honest, and it went stale the
first time a deck was edited by a follow-up request. It also gave a build two outputs to
coordinate: the intake had to negotiate the folder's readme conventions, and Step 0 read
that readme to learn local conventions instead of reading an actual deck.

A build now leaves exactly one file behind: the deck (plus a PDF if asked for).

  • Step 6 says so explicitly, and everything the readme section used to hold (what the
    deck covers, slide count, navigation keys, and the paragraph on how the file is
    structured for later edits) is reported in the final message instead. Adding a deck to
    an index the repo already keeps becomes the user's call rather than a default.
  • Markdown mode (references/markdown.md) carries the same rule, so a cited doc no
    longer grows an uncited neighbour either.
  • Step 0 learns local conventions by opening an existing deck (its title slide, theme
    and build stamp), not its folder readme.
  • Intake item 6 drops the readme negotiation; Step 4 cleanup now expects nothing
    but the deck and an optional PDF.
  • The demo deck's pipeline slide said "README section written" as the ship step; it now
    says the deck is the only file left behind.

Nothing about the citation mechanism, the scripts, or the templates changes.

How you know it works

The whole gate is green locally: ruff check, ruff format --check, ty check, pytest
(91 passed), and validate.py. Both citation guards still report every citation CURRENT,
on uv and on bare python3, for the HTML deck and the Markdown doc.

The demo deck edit lands on a flow box, so it needed a look rather than a checker:
rendered slide 4 at 1280x720 and viewed it. The longer label wraps to two lines inside its
box with no overflow, no clipping against the nav pill, and the row keeps its shape.
smoke_test.py itself does not run in this environment: it deliberately keeps Chrome's
sandbox, which refuses to start as root, so CI's run is the full-deck pass.

Checks that are easy to miss

  • No new import in skills/slideops/scripts/. Those two files are untouched.
  • dist/skill-demo.pdf is not in the diff.
  • Ships a change to users: .claude-plugin/plugin.json and the skill's
    metadata.version both go to 1.1.2, with a CHANGELOG entry.
  • The deck changed: slide 4 re-rendered and viewed. The title slide did not move, so
    scripts/make_hero.py output is unaffected.
  • No em dashes in prose.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Nyxj8LM1DHDm2i2k2MYGDs


Generated by Claude Code

Step 6 had the agent write or extend a shared README.md next to every
deck, one section per deck in the folder. That sidecar carried no
citations, so it was the one artifact check.py could not keep honest,
and it drifted the first time a deck was edited by a follow-up request.

What it held now goes in the final message instead: coverage, slide
count, navigation keys, and how the file is structured for later edits.
Adding a deck to an index the repo already keeps becomes the user's
call rather than a default. Markdown mode carries the same rule, so a
cited doc no longer grows an uncited neighbour either.

The intake no longer asks about a folder's readme conventions, Step 0
reads an existing deck for local conventions instead of its readme,
and the Step 4 cleanup rule expects nothing but the deck and an
optional PDF.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nyxj8LM1DHDm2i2k2MYGDs
@glukicov
glukicov merged commit 6020266 into main Sep 3, 2026
3 checks passed
@glukicov
glukicov deleted the claude/skills-readme-output-spplh2 branch September 3, 2026 15:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants