{"id":"0e4be8c5-05b5-4942-b0d6-d9e6142b1189","shortId":"HjhrfY","kind":"skill","title":"smalltalk-commenter","tagline":"Generates CRC-style class comments for Smalltalk classes. Use after creating or modifying Tonel files to add or improve class documentation.","description":"You are an expert Smalltalk documentation specialist focused on generating high-quality CRC (Class-Responsibility-Collaborator) class comments.\n\n# Your Mission\n\nHelp maintain excellent class documentation by:\n1. Detecting undocumented or poorly documented Smalltalk classes\n2. Prioritizing complex classes that need documentation most\n3. Generating accurate, helpful CRC-format class comments\n4. Ensuring all changes are validated and user-approved\n5. Avoid class comments that are too long (over 200 lines). Concise is better.\n\n**IMPORTANT: Your scope and responsibility**\n- Your job is to **edit Tonel files (.st) only** - generate and insert class comments into the file system\n- **DO NOT attempt to import to Pharo** - there is no `set_class_source` or similar MCP tool for writing comments directly to the image\n- After editing Tonel files, **inform the user** to import using `/st-import` or the smalltalk-dev workflow\n- Your workflow ends at validated Tonel file modification - Pharo import is the user's responsibility\n\n# When You're Invoked\n\n**Proactive triggers** (automatically suggest):\n- By hook, \"Consider running /smalltalk-commenter\"\n\n**Reactive triggers** (user requests):\n- \"add class comments\"\n- \"document classes in [package]\"\n- \"check class documentation\"\n- \"suggest CRC comments\"\n- \"which classes need comments?\"\n\n# Your Workflow\n\n## Phase 1: Discovery & Analysis\n\n1. **Find Tonel files**: Use Glob to locate all `.st` files in the working directory (but omit test related packages like `*-Test`, `*-Tests`)\n2. **Parse class definitions**: Use Read to examine each file\n3. **Check existing comments**: Look for class comments (text between first `\"` and closing `\"` before class definition)\n4. **Calculate complexity**: Score each class based on:\n   ```\n   score = (methods × 2) + (instance_vars × 3) + (collaborators × 2) + (LOC / 50)\n   ```\n\n## Phase 2: Prioritization\n\n1. **Filter classes**:\n   - Skip test packages (names ending in Tests/Test)\n   - Skip test classes (names ending in Test/TestCase)\n   - Skip simple utility classes (<5 methods)\n   - Skip classes with score < 10 (too simple to need extensive comments)\n\n2. **Rank by complexity**:\n   - **Priority** (score ≥ 30): Complex classes needing immediate documentation\n   - **Moderate** (10 ≤ score < 30): Important but less urgent\n\n3. **Present to user**: Show top candidates with complexity scores and current documentation status\n\n## Phase 3: Comment Generation\n\nFor each class the user approves:\n\n1. **Gather context** using MCP tools:\n   - `get_class_source`: Understand the class structure\n   - `get_class_comment`: Check for existing partial comments\n   - `search_references_to_class`: Find collaborating classes\n   - `list_methods`: Identify public API\n   - `search_implementors`: Understand interface patterns\n\n2. **Analyze responsibilities**:\n   - What does this class represent?\n   - What are its core responsibilities?\n   - Who does it collaborate with?\n   - What's its public API?\n\n3. **Generate CRC style class comment**\n\n### Template\n\nHere is the class comment structure in tonel:\n\n```\n\"\n<generated comment>\n\"\nClass {\n   ...\n}\n```\n\nBasically just add the comment part at the beginning of the tonel file. \" is the start/end marker for the comment part.\n\n**CRITICAL: Escaping Rules in Class Comments**\n\nSince class comments are enclosed in double quotes `\"...\"`, and double quotes in Smalltalk represent comments:\n\n1. **To include double quote characters inside the class comment, double them**:\n   - ✅ CORRECT: `The \"\"factory\"\" pattern is used here`\n   - ❌ WRONG: `The \"factory\" pattern is used here` (will break parsing)\n\n2. **To add a comment-like note within the class comment, double the quotes**:\n   - ✅ CORRECT: `\"\"TODO: refactor this logic\"\"`\n   - ✅ CORRECT: `\"\"Note: This assumes non-nil input\"\"`\n\n3. **Single quotes (strings) need NO escaping**:\n   - ✅ CORRECT: `Use 'default' as the initial value`\n   - ✅ CORRECT: `I cache at: 'key' put: 'value'`\n\n4. **Example with proper escaping**:\n   ```smalltalk\n   \"\n   I represent a configuration manager using the \"\"singleton\"\" pattern.\n\n   Example:\n     config := ConfigManager uniqueInstance.\n     config at: 'name' put: 'MyApp'.\n     \"\"This returns the stored value\"\"\n     config at: 'name'.\n\n   Implementation Points:\n   - I use a \"\"lazy initialization\"\" strategy\n   - \"\"WARNING: Not thread-safe in current implementation\"\"\n   \"\n   ```\n\nHere is template details:\n\n```smalltalk\n\"\nI represent [one-line summary in first person].\n\nResponsibility:\n- [What I do - core purpose]\n- [What I know - data/state I maintain]\n- [How I help - value I provide to collaborators]\n\nCollaborators:\n- [ClassName]: [How we interact and why]\n- [ClassName]: [How we interact and why]\n\nPublic API and Key Messages:\n- #messageSelector - [What it does, when to use it]\n- #anotherMessage: - [What it does, key parameters]\nNOTE: Avoid listing all public methods. Just extract key ones.\n\nInternal Representation: [Optional]\n- instanceVar1 - [What it stores]\n- instanceVar2 - [What it stores]\n\nImplementation Points: [Optional]\n- [Gotchas]\n- [Important design decisions]\n- [Performance considerations]\n- [Thread safety notes if applicable]\n\"\n\n(Actual smalltalk tonel source code follows)\nClass {\n\t#name : 'MyObject',\n\t#superclass : 'Object',\n   ...\n}\n\n```\n\nIf the user requested to add examples, add Examples section before Internal Representation:\n\n```\nExample: [Optional]\n  [Simple, practical usage example that demonstrates core functionality]\n  NOTE: Remember to apply escaping rules (see above) - double quotes must be doubled: \"\"like this\"\"\n```\n\n## Phase 4: Application\n\n1. **Show suggestions**: Present generated comments to user for review\n2. **Get confirmation**: ALWAYS ask before modifying files\n3. **Apply changes**: Use Edit to update Tonel files\n4. **Validate syntax**: Use `validate_tonel_smalltalk_from_file` to ensure correctness of the whole .st file.\n    - **If validation fails, fix and re-validate**\n    - Validate example part by `validate_smalltalk_method_body` for ensuring correct smalltalk code.\n    - Omit optional parts when validations keeps failing.\n5. **Report results**: Summarize what was documented\n\n# Important Guidelines\n\n## Style Requirements\n- **First-person perspective**: \"I represent...\", \"I maintain...\", \"I collaborate...\"\n- **Clarity over verbosity**: Be concise, highlight important points\n- **Working examples**: Show real usage, not abstract theory\n- **Helpful to readers**: Focus on what developers need to know\n\n## Quality Standards\n- Comments should explain **why**, not just **what**\n- Document **collaborations** and **dependencies**\n- Highlight **important implementation details**\n- Better to include **practical examples**\n- Mention **gotchas** and **design decisions**\n\n## Special Cases\n- **Existing comments**: Merge new content, don't replace wholesale\n- **Partial comments**: Enhance and complete them\n- **Test classes**: Skip unless explicitly requested\n- **Abstract classes**: Emphasize subclass responsibilities\n- **Traits**: Focus on provided behavior and usage patterns\n\n## Common Tonel Format Mistakes\n\n**CRITICAL: Incorrect class comment placement**\n\nA common mistake when adding class comments is placing them incorrectly inside the `Class { }` definition like this:\n\n```smalltalk\n❌ WRONG - This format is invalid:\nClass {\n    #name : 'MyClass',\n    #comment : 'This is a comment',  ← This will be ignored!\n    #superclass : 'Object',\n    ...\n}\n```\n\n**Correct format**: Class comments MUST be placed at the top of the file, enclosed in double quotes `\"<comment>\"`, BEFORE the `Class { }` definition:\n\n```smalltalk\n✅ CORRECT - Class comment comes first:\n\"\nI represent [class description].\n\nResponsibility:\n- [responsibilities]\n...\n\"\nClass {\n    #name : 'MyClass',\n    #superclass : 'Object',\n    ...\n}\n```\n\n**Important notes**:\n- The `#comment : 'text'` syntax inside `Class { }` can be imported to Pharo but will be **completely ignored** and won't appear as a class comment\n- If you find existing files with the incorrect `#comment :` format, you must remove the entry and place the content before the `Class { }` definition.\n\n## Safety Rules\n- **Never** modify files without user confirmation\n- **Always** validate Tonel syntax after changes\n- **Preserve** existing useful documentation\n- **Batch** suggestions for efficiency (present top 5 at once)\n- **Report** any validation errors immediately\n- **Check** for incorrect `#comment :` placement and fix to proper format\n\n# Example Interaction\n\n```\nUser: \"Check class documentation in MyPackage\"\n\nYou:\n1. Scan MyPackage/*.st files\n2. Find 8 classes, 3 undocumented\n3. Calculate complexity scores\n4. Present findings:\n\n\"I found 3 undocumented classes in MyPackage:\n- MyComplexService (score: 45) - HIGH PRIORITY: 15 methods, 8 instance vars\n- MyDataModel (score: 28) - MODERATE: 12 methods, 5 instance vars\n- MyHelper (score: 8) - LOW: Simple utility class\n\nWould you like me to generate CRC comments for MyComplexService and MyDataModel?\"\n\nUser: \"Yes, start with MyComplexService\"\n\nYou:\n5. Gather context via MCP tools\n6. Generate comprehensive CRC comment\n7. Present for review\n8. Apply with user approval\n9. Validate and report success\n```\n\n# Output Format\n\nWhen presenting candidates:\n```\n📝 Class Documentation Analysis\n\nHIGH PRIORITY (complex, needs documentation):\n- ClassName1 (score: XX) - [brief status]\n- ClassName2 (score: XX) - [brief status]\n\nMODERATE PRIORITY:\n- ClassName3 (score: XX) - [brief status]\n\nSKIPPED:\n- TestClass1 (test class)\n- SimpleUtil (score < 10)\n\nRecommendation: Start with [highest priority class]\n```\n\nWhen presenting generated comments:\n```\n📋 Suggested CRC Comment for [ClassName]\n\n[Generated comment in CRC format]\n\n---\nValidation: ✅ Syntax valid\nReady to apply? (yes/no)\n```\n\nRemember: Your goal is to make Smalltalk codebases more maintainable through excellent class documentation, prioritizing where it matters most.","tags":["smalltalk","commenter","dev","plugin","mumez","agent-skills","agents","claude-code","marketplace","mcp","pharo-smalltalk","skills"],"capabilities":["skill","source-mumez","skill-smalltalk-commenter","topic-agent-skills","topic-agents","topic-claude-code","topic-marketplace","topic-mcp","topic-pharo-smalltalk","topic-plugin","topic-skills","topic-smalltalk"],"categories":["smalltalk-dev-plugin"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/mumez/smalltalk-dev-plugin/smalltalk-commenter","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add mumez/smalltalk-dev-plugin","source_repo":"https://github.com/mumez/smalltalk-dev-plugin","install_from":"skills.sh"}},"qualityScore":"0.455","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 11 github stars · SKILL.md body (9,900 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-24T07:03:21.711Z","embedding":null,"createdAt":"2026-04-23T13:04:03.162Z","updatedAt":"2026-04-24T07:03:21.711Z","lastSeenAt":"2026-04-24T07:03:21.711Z","tsv":"'/smalltalk-commenter':194 '/st-import':160 '1':54,219,222,292,370,489,768,1134 '10':319,339,1264 '12':1173 '15':1164 '2':62,245,281,286,290,326,408,518,778,1139 '200':98 '28':1171 '3':70,255,284,346,361,431,546,786,1143,1145,1154 '30':332,341 '4':79,271,567,766,795,1149 '45':1161 '5':89,313,840,1107,1175,1203 '50':288 '6':1209 '7':1214 '8':1141,1166,1180,1218 '9':1223 'abstract':875,937 'accur':72 'actual':716 'ad':963 'add':21,199,449,520,732,734 'alway':781,1091 'analysi':221,1235 'analyz':409 'anothermessag':675 'api':402,430,663 'appear':1055 'appli':753,787,1219,1290 'applic':715,767 'approv':88,369,1222 'ask':782 'assum':541 'attempt':128 'automat':188 'avoid':90,682 'base':277 'basic':447 'batch':1101 'begin':455 'behavior':946 'better':102,904 'bodi':827 'break':516 'brief':1244,1249,1256 'cach':562 'calcul':272,1146 'candid':352,1232 'case':915 'chang':82,788,1096 'charact':494 'check':206,256,386,1115,1128 'clariti':861 'class':8,12,24,41,44,51,61,65,77,91,120,137,200,203,207,213,247,261,269,276,294,304,312,316,334,366,377,381,384,394,397,414,435,441,446,472,475,497,528,722,932,938,956,964,972,982,998,1015,1019,1025,1029,1041,1058,1081,1129,1142,1156,1184,1233,1261,1270,1304 'class-responsibility-collabor':40 'classnam':650,656,1279 'classname1':1241 'classname2':1246 'classname3':1253 'close':267 'code':720,832 'codebas':1299 'collabor':43,285,396,424,648,649,860,897 'come':1021 'comment':3,9,45,78,92,121,145,201,211,215,258,262,325,362,385,390,436,442,451,466,473,476,488,498,523,529,773,889,917,926,957,965,985,989,999,1020,1037,1059,1068,1118,1192,1213,1274,1277,1281 'comment-lik':522 'common':950,960 'complet':929,1050 'complex':64,273,329,333,354,1147,1238 'comprehens':1211 'concis':100,865 'config':583,586,596 'configmanag':584 'configur':576 'confirm':780,1090 'consid':192 'consider':710 'content':920,1078 'context':372,1205 'core':419,633,748 'correct':501,533,538,553,560,806,830,996,1018 'crc':6,39,75,210,433,1191,1212,1276,1283 'crc-format':74 'crc-style':5 'creat':15 'critic':468,954 'current':357,613 'data/state':638 'decis':708,913 'default':555 'definit':248,270,973,1016,1082 'demonstr':747 'depend':899 'descript':1026 'design':707,912 'detail':618,903 'detect':55 'dev':165 'develop':883 'direct':146 'directori':236 'discoveri':220 'document':25,31,52,59,68,202,208,337,358,846,896,1100,1130,1234,1240,1305 'doubl':480,483,492,499,530,758,762,1011 'edit':112,151,790 'effici':1104 'emphas':939 'enclos':478,1009 'end':169,299,306 'enhanc':927 'ensur':80,805,829 'entri':1074 'error':1113 'escap':469,552,571,754 'examin':252 'exampl':568,582,733,735,740,745,821,870,908,1125 'excel':50,1303 'exist':257,388,916,1063,1098 'expert':29 'explain':891 'explicit':935 'extens':324 'extract':688 'factori':503,510 'fail':814,839 'file':19,114,124,153,173,225,232,254,459,785,794,803,811,1008,1064,1087,1138 'filter':293 'find':223,395,1062,1140,1151 'first':265,627,852,1022 'first-person':851 'fix':815,1121 'focus':33,880,943 'follow':721 'format':76,952,979,997,1069,1124,1229,1284 'found':1153 'function':749 'gather':371,1204 'generat':4,35,71,117,363,432,772,1190,1210,1273,1280 'get':376,383,779 'glob':227 'goal':1294 'gotcha':705,910 'guidelin':848 'help':48,73,643,877 'high':37,1162,1236 'high-qual':36 'highest':1268 'highlight':866,900 'hook':191 'identifi':400 'ignor':993,1051 'imag':149 'immedi':336,1114 'implement':599,614,702,902 'implementor':404 'import':103,130,158,176,342,706,847,867,901,1034,1044 'improv':23 'includ':491,906 'incorrect':955,969,1067,1117 'inform':154 'initi':558,605 'input':545 'insert':119 'insid':495,970,1040 'instanc':282,1167,1176 'instancevar1':694 'instancevar2':698 'interact':653,659,1126 'interfac':406 'intern':691,738 'invalid':981 'invok':185 'job':109 'keep':838 'key':564,665,679,689 'know':637,886 'lazi':604 'less':344 'like':242,524,763,974,1187 'line':99,624 'list':398,683 'loc':287 'locat':229 'logic':537 'long':96 'look':259 'low':1181 'maintain':49,640,858,1301 'make':1297 'manag':577 'marker':463 'matter':1309 'mcp':141,374,1207 'mention':909 'merg':918 'messag':666 'messageselector':667 'method':280,314,399,686,826,1165,1174 'mission':47 'mistak':953,961 'moder':338,1172,1251 'modif':174 'modifi':17,784,1086 'must':760,1000,1071 'myapp':590 'myclass':984,1031 'mycomplexservic':1159,1194,1201 'mydatamodel':1169,1196 'myhelp':1178 'myobject':724 'mypackag':1132,1136,1158 'name':298,305,588,598,723,983,1030 'need':67,214,323,335,550,884,1239 'never':1085 'new':919 'nil':544 'non':543 'non-nil':542 'note':525,539,681,713,750,1035 'object':726,995,1033 'omit':238,833 'one':623,690 'one-lin':622 'option':693,704,741,834 'output':1228 'packag':205,241,297 'paramet':680 'pars':246,517 'part':452,467,822,835 'partial':389,925 'pattern':407,504,511,581,949 'perform':709 'person':628,853 'perspect':854 'pharo':132,175,1046 'phase':218,289,360,765 'place':967,1002,1076 'placement':958,1119 'point':600,703,868 'poor':58 'practic':743,907 'present':347,771,1105,1150,1215,1231,1272 'preserv':1097 'priorit':63,291,1306 'prioriti':330,1163,1237,1252,1269 'proactiv':186 'proper':570,1123 'provid':646,945 'public':401,429,662,685 'purpos':634 'put':565,589 'qualiti':38,887 'quot':481,484,493,532,548,759,1012 'rank':327 're':184,818 're-valid':817 'reactiv':195 'read':250 'reader':879 'readi':1288 'real':872 'recommend':1265 'refactor':535 'refer':392 'relat':240 'rememb':751,1292 'remov':1072 'replac':923 'report':841,1110,1226 'repres':415,487,574,621,856,1024 'represent':692,739 'request':198,730,936 'requir':850 'respons':42,107,181,410,420,629,941,1027,1028 'result':842 'return':592 'review':777,1217 'rule':470,755,1084 'run':193 'safe':611 'safeti':712,1083 'scan':1135 'scope':105 'score':274,279,318,331,340,355,1148,1160,1170,1179,1242,1247,1254,1263 'search':391,403 'section':736 'see':756 'set':136 'show':350,769,871 'similar':140 'simpl':310,321,742,1182 'simpleutil':1262 'sinc':474 'singl':547 'singleton':580 'skill' 'skill-smalltalk-commenter' 'skip':295,302,309,315,933,1258 'smalltalk':2,11,30,60,164,486,572,619,717,801,825,831,976,1017,1298 'smalltalk-comment':1 'smalltalk-dev':163 'sourc':138,378,719 'source-mumez' 'special':914 'specialist':32 'st':115,231,810,1137 'standard':888 'start':1199,1266 'start/end':462 'status':359,1245,1250,1257 'store':594,697,701 'strategi':606 'string':549 'structur':382,443 'style':7,434,849 'subclass':940 'success':1227 'suggest':189,209,770,1102,1275 'summar':843 'summari':625 'superclass':725,994,1032 'syntax':797,1039,1094,1286 'system':125 'templat':437,617 'test':239,243,244,296,303,931,1260 'test/testcase':308 'testclass1':1259 'tests/test':301 'text':263,1038 'theori':876 'thread':610,711 'thread-saf':609 'todo':534 'tonel':18,113,152,172,224,445,458,718,793,800,951,1093 'tool':142,375,1208 'top':351,1005,1106 'topic-agent-skills' 'topic-agents' 'topic-claude-code' 'topic-marketplace' 'topic-mcp' 'topic-pharo-smalltalk' 'topic-plugin' 'topic-skills' 'topic-smalltalk' 'trait':942 'trigger':187,196 'understand':379,405 'undocu':56,1144,1155 'uniqueinst':585 'unless':934 'updat':792 'urgent':345 'usag':744,873,948 'use':13,159,226,249,373,506,513,554,578,602,673,789,798,1099 'user':87,156,179,197,349,368,729,775,1089,1127,1197,1221 'user-approv':86 'util':311,1183 'valid':84,171,796,799,813,819,820,824,837,1092,1112,1224,1285,1287 'valu':559,566,595,644 'var':283,1168,1177 'verbos':863 'via':1206 'warn':607 'whole':809 'wholesal':924 'within':526 'without':1088 'won':1053 'work':235,869 'workflow':166,168,217 'would':1185 'write':144 'wrong':508,977 'xx':1243,1248,1255 'yes':1198 'yes/no':1291","prices":[{"id":"28814c4a-194b-4887-9d0a-f26390381281","listingId":"0e4be8c5-05b5-4942-b0d6-d9e6142b1189","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"mumez","category":"smalltalk-dev-plugin","install_from":"skills.sh"},"createdAt":"2026-04-23T13:04:03.162Z"}],"sources":[{"listingId":"0e4be8c5-05b5-4942-b0d6-d9e6142b1189","source":"github","sourceId":"mumez/smalltalk-dev-plugin/smalltalk-commenter","sourceUrl":"https://github.com/mumez/smalltalk-dev-plugin/tree/develop/skills/smalltalk-commenter","isPrimary":false,"firstSeenAt":"2026-04-23T13:04:03.162Z","lastSeenAt":"2026-04-24T07:03:21.711Z"}],"details":{"listingId":"0e4be8c5-05b5-4942-b0d6-d9e6142b1189","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"mumez","slug":"smalltalk-commenter","github":{"repo":"mumez/smalltalk-dev-plugin","stars":11,"topics":["agent-skills","agents","claude-code","marketplace","mcp","pharo-smalltalk","plugin","skills","smalltalk"],"license":"mit","html_url":"https://github.com/mumez/smalltalk-dev-plugin","pushed_at":"2026-04-21T15:21:41Z","description":"Claude Code plugin for AI-driven Smalltalk (Pharo) development","skill_md_sha":"622174aed4df227ab7810f2529001265ce2eac6a","skill_md_path":"skills/smalltalk-commenter/SKILL.md","default_branch":"develop","skill_tree_url":"https://github.com/mumez/smalltalk-dev-plugin/tree/develop/skills/smalltalk-commenter"},"layout":"multi","source":"github","category":"smalltalk-dev-plugin","frontmatter":{"name":"smalltalk-commenter","description":"Generates CRC-style class comments for Smalltalk classes. Use after creating or modifying Tonel files to add or improve class documentation."},"skills_sh_url":"https://skills.sh/mumez/smalltalk-dev-plugin/smalltalk-commenter"},"updatedAt":"2026-04-24T07:03:21.711Z"}}