Repository navigation
Improve guide and refactor rules - #4
Merged
Merged
Conversation
Each rule now has its own page in skills/camera-ready/rules/<section>/, with the rule's text, then optional Details and Examples sections. The script scripts/build_guide.py builds references/guide.md from the rule pages and scripts/guide.template.md, and checks every link to a guide heading. A pre-commit hook and a CI job keep guide.md up to date. The rules' text is unchanged; the Bad/Good examples moved from the guide to the rule pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Agent Skills specification reserves references/ for documentation that agents read on demand, which is what the rule pages are. The links between the guide and the rule pages also become shorter. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace the workflow's --check step with a pytest suite in tests/, whose only test so far checks that references/guide.md is up to date. CI runs the suite on pull requests to main and pushes to main. Restore the README to its version on main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uide The model reads guide.md, so a maintainer comment there only adds noise to its context. The test and the pre-commit hook already keep the guide in sync. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rule pages now link to other rule pages instead of to headings in the guide, and the build script rejects any other relative link. The guide's paragraph on rule pages becomes its own section, which shows the format of a page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rewrite the description with the guide's own rules and add a table of contents heading. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Retitle every rule page as an instruction, split the pages that covered a whole topic into one page per rule, merge pages that repeated each other, and regroup the guide so that every subsection holds at least two rules. Prior work moves from Prose to Story. SKILL.md links straight to the rule pages it names, and make_guide.py now fails on a link to a missing rule page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Fold advice from 14 books on writing into the rules, in our own words, with 8 new rule pages and revisions to the existing ones. - Keep each summary to what to look for, the edit or flag, and the exceptions that prevent harmful edits; move the rest to Details. - Give every rule page at least one Bad/Good example, and have make_guide.py reject a page without one. - List the books in REFERENCES.md and drop sources listed twice. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e prose Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he summaries Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he quote Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ce about rule pages Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ample sentence Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t's change and reason Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ntences Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… an optional explanation Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ide separate quotes, and use real line breaks and lists Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…typography rules an LLM already follows Merge number-forms and units into quantities; punctuation-typography, nonrestrictive-commas, and spelling into marks-and-forms; five-line-summary and one-sentence-summary into argument-summary; section-connections into section-openings; headline-number into claim-before-number; and ambiguous-this into referents. Delete hyphens, latin-abbreviations, and latex-boundaries, keeping their few useful guards in marks-and-forms, and drop the "et al." punctuation instruction from citation-markers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e conflicts between rules - State each rule in its summary instead of pointing to Details, and have make_guide.py reject a summary that mentions Details. - Restore the instructions, exceptions, and illustrations from the old guide that compression had dropped, keeping only deliberate removals. - Cut fluff from the summaries: restatements, generic safeguards that SKILL.md already states, rationale that decides no case, and second illustrations. - Restore accepted book rules that were missing or only in Details, and resolve conflicts between rules with links and exceptions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ng paragraph Merge short summary paragraphs in hedges, scope, variability, display-numbering, math-typography, missing-citations, proof-strategy, and term-consistency, keeping paragraphs separate where they cover different topics. Also drop the exception for claim edits from the guide's list of changes to flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summaries that are checklists or collections of independent subrules now use bullet lists, as the old guide did, with every sentence kept verbatim apart from short lead-ins. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ncept Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… choices and units Replace marks-and-forms with style-choices, which makes the variety of English, term spellings, heading case, the number-spelling cutoff, the serial comma, and "which" or "that" consistent, following the venue. Rename quantities to units-and-numbers, and drop the decorative-formatting, code-punctuation, and "cf." rules. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…guide The Story overview now flags only changes to which claims or contributions the text makes and to their order, so matching a claim's wording to its evidence is an edit the editor may make. Comparisons with prior work are flagged only when they need material from a later section. Summaries keep the hedge of the result they restate. A draft's term is replaced with the field's standard term only when both mean exactly the same thing, and coined labels are otherwise flagged. Heading case falls back to sentence case only when neither case predominates. Blacklisted patterns are removed or flagged as their rule says, and unsupported implications are marked as speculation or flagged. The limitations rule again requires only a limitation phrased as future work to state what the current results do not cover, as on main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…orms Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… rule on free style choices Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… link in the guide and SKILL.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nal and edited text Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.