ibm-sg-references
Skill4 starsChanged 4 months agoApache-2.0View on GitHub
Review documentation for IBM Style Guide reference issues — citations, footnotes, geographic locations, product and service names (official capitalization, trademark usage), product version formatting ("version 4.12 and later" not "recent versions"), and name/title conventions. Use this skill when checking product names, version references, citation formatting, geographic references, or footnote usage in documentation.
In this repository53 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- action-commentsSkill
- article-extractorSkill
- docs-convert-gdoc-mdSkill
- docs-orchestratorSkill
- docs-review-content-qualitySkill
- docs-review-modular-docsSkill
- docs-review-securitySkill
- docs-review-styleSkill
- docs-review-technicalSkill
- docs-ticket-readinessSkill
- docs-workflow-code-analysisSkill
- docs-workflow-create-jiraSkill
- docs-workflow-create-merge-requestSkill
- docs-workflow-jira-readySkill
- docs-workflow-pipeline-diagnosticsSkill
- docs-workflow-planningSkill
- docs-workflow-pr-analysisSkill
- docs-workflow-quality-gateSkill
- docs-workflow-requirementsSkill
- docs-workflow-scope-req-auditSkill
- docs-workflow-security-reviewSkill
- docs-workflow-startSkill
- docs-workflow-style-reviewSkill
- docs-workflow-tech-reviewSkill
- docs-workflow-writingSkill
- git-pr-readerSkill
- ibm-sg-audience-and-mediumSkill
- ibm-sg-language-and-grammarSkill
- ibm-sg-legal-informationSkill
- ibm-sg-numbers-and-measurementSkill
- ibm-sg-punctuationSkill
- ibm-sg-structure-and-formatSkill
- ibm-sg-technical-elementsSkill
- jira-readerSkill
- jira-writerSkill
- learn-codeSkill
- lint-with-valeSkill
- mdita-writeSkill
- query-codeSkill
- redhat-docs-tocSkill
- rh-ssg-accessibilitySkill
- rh-ssg-formattingSkill
- rh-ssg-grammar-and-languageSkill
- rh-ssg-gui-and-linksSkill
- rh-ssg-legal-and-supportSkill
- rh-ssg-release-notesSkill
- rh-ssg-structureSkill
- rh-ssg-technical-examplesSkill
- rn-known-issuesSkill
- understand-pull-requestSkill
- validate-plugin-prereqsSkill
The file
Files
IBM Style Guide: References review skill
Review documentation for reference issues: citations, footnotes, geographic locations, names, product and service names, trademarks, and product versions.
Precedence: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules where guidance conflicts.
Checklist
Citations and references
- Sources are cited for all statistics, quotes, and external claims
- Citation format is consistent throughout the document
- Full URLs are provided for online references (no shortened URLs)
- Access dates are included for web citations that may change
- Links point to the most specific page, not the homepage
Footnotes
- Footnotes are used sparingly; inline explanations or links are preferred
- Essential information is not placed in footnotes
- Footnotes are numbered sequentially
- Procedures and code examples are not in footnotes
Geographic locations
- "Domestic" and "foreign" are not used; specific countries or regions are named
- Official, current names are used for countries and regions
- Reader's location is not assumed ("here," "local," "our country")
- Countries and regions are listed alphabetically unless logically ordered
Names and titles
- Full official names are used on first reference; shortened forms afterward
- Courtesy titles (Mr., Ms., Dr.) are avoided unless relevant
- Preferred spelling and capitalization of names are followed
Product and service names
- Full official product name is used on first reference in each topic
- Product names are not abbreviated without an official abbreviation
- Product names are not used as verbs: "search by using Google" not "Google it"
- Product names are not used as generic terms: "container" not "Docker" (when generic)
- Trademark symbols (™, ®) appear only on the first prominent use, not every instance
- Vendor's exact capitalization is followed: "macOS," "iOS," "GitHub," "PostgreSQL"
Product versions
- Full version format is used: "Version 4.12" or "v4.12"
- Versions are specific: "version 4.12 and later" not "recent versions"
- "Current version" and "latest version" are not used (they become outdated)
- Minimum required versions are specified: "requires version 2.1 or later"
- Version formatting is consistent throughout
How to use
- Review only changed content and necessary context
- For each issue found, cite the relevant IBM Style Guide section
- Mark issues as required (incorrect product names, missing citations) or [SUGGESTION] (formatting preferences)
Example invocations
- "Review this file for reference and naming issues"
- "Check product names and versions in the release notes"
- "Do an IBM references review on modules/overview.adoc"
References
For detailed guidance, consult:
- IBM Style Guide: References sections
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.