Coverage for little_loops / cli / generate_skill_descriptions.py: 81%

1"""ll-generate-skill-descriptions: Auto-generate concise skill descriptions via Claude CLI. 

2 

3For each skills/*/SKILL.md that does NOT have disable-model-invocation: true, 

4extract trigger keywords and body excerpt, prompt Claude (haiku) to produce a 

5description ≤100 characters, and optionally write it back to the frontmatter. 

6 

7Dry-run by default. Use --apply to write back. 

8""" 

9 

10from __future__ import annotations 

11 

12import argparse 

13import re 

14import sys 

15from pathlib import Path 

16 

17__all__ = ["main_generate_skill_descriptions"] 

18 

19_MAX_DESC_LEN = 100 

20_BODY_EXCERPT_CHARS = 500 

21 

22 

23def _find_plugin_root() -> Path: 

24 from little_loops.skill_expander import _find_plugin_root as _fpr 

25 

26 return _fpr() 

27 

28 

29def _parse_frontmatter(text: str) -> tuple[dict[str, str], str]: 

30 """Return (frontmatter_keys, body_text) from a SKILL.md string.""" 

31 if not text.startswith("---"): 

32 return {}, text 

33 end = text.find("---", 3) 

34 if end == -1: 

35 return {}, text 

36 raw = text[3:end] 

37 body = text[end + 3 :].lstrip("\n") 

38 fm: dict[str, str] = {} 

39 for line in raw.splitlines(): 

40 if ":" in line: 

41 key, _, val = line.partition(":") 

42 fm[key.strip()] = val.strip() 

43 return fm, body 

44 

45 

46def _extract_trigger_keywords(description: str) -> str: 

47 """Pull the 'Trigger keywords:' line from a description field value.""" 

48 for line in description.splitlines(): 

49 if line.strip().lower().startswith("trigger keywords"): 

50 return line.strip() 

51 return "" 

52 

53 

54def _build_prompt(skill_name: str, trigger_keywords: str, body_excerpt: str) -> str: 

55 return ( 

56 f"Generate a single-line skill description for the '{skill_name}' skill.\n" 

57 f"Rules:\n" 

58 f"- Maximum {_MAX_DESC_LEN} characters total\n" 

59 f"- No bullet points or newlines\n" 

60 f"- Start with 'Use when' or a clear trigger phrase\n" 

61 f"- Include the most important trigger keywords\n" 

62 f"\nTrigger keywords: {trigger_keywords or '(none)'}\n" 

63 f"Skill body excerpt:\n{body_excerpt[:_BODY_EXCERPT_CHARS]}\n" 

64 f"\nRespond with ONLY the description text, nothing else." 

65 ) 

66 

67 

68def _write_description_to_frontmatter(skill_md: Path, new_desc: str) -> None: 

69 """Replace the description: field in SKILL.md frontmatter with new_desc.""" 

70 text = skill_md.read_text() 

71 if not text.startswith("---"): 

72 return 

73 end = text.find("---", 3) 

74 if end == -1: 

75 return 

76 fm_block = text[3:end] 

77 after = text[end:] 

78 

79 # Replace existing description line (single-line only) 

80 new_fm_block = re.sub( 

81 r"^description:.*$", 

82 f"description: {new_desc}", 

83 fm_block, 

84 flags=re.MULTILINE, 

85 ) 

86 skill_md.write_text("---" + new_fm_block + after) 

87 

88 

89def _process_skills(skills_dir: Path, apply: bool, quiet: bool) -> tuple[int, int, int]: 

90 """Process all skills; return (processed, skipped, errors).""" 

91 from little_loops.subprocess_utils import run_claude_command 

92 

93 processed = skipped = errors = 0 

94 

95 for skill_md in sorted(skills_dir.glob("*/SKILL.md")): 

96 skill_name = skill_md.parent.name 

97 try: 

98 text = skill_md.read_text() 

99 except OSError as exc: 

100 if not quiet: 

101 print(f" ERROR {skill_name}: cannot read file: {exc}", file=sys.stderr) 

102 errors += 1 

103 continue 

104 

105 fm, body = _parse_frontmatter(text) 

106 

107 if fm.get("disable-model-invocation", "").lower() in ("true", "yes", "1"): 

108 if not quiet: 

109 print(f" SKIP {skill_name} (disable-model-invocation: true)") 

110 skipped += 1 

111 continue 

112 

113 trigger_keywords = _extract_trigger_keywords(fm.get("description", "")) 

114 prompt = _build_prompt(skill_name, trigger_keywords, body) 

115 

116 result = run_claude_command( 

117 command=prompt, 

118 timeout=60, 

119 ) 

120 

121 if result.returncode != 0: 

122 if not quiet: 

123 print( 

124 f" ERROR {skill_name}: Claude returned exit {result.returncode}", 

125 file=sys.stderr, 

126 ) 

127 errors += 1 

128 continue 

129 

130 new_desc = result.stdout.strip().splitlines()[0].strip() if result.stdout.strip() else "" 

131 

132 if len(new_desc) > _MAX_DESC_LEN: 

133 new_desc = new_desc[:_MAX_DESC_LEN] 

134 

135 if not new_desc: 

136 if not quiet: 

137 print(f" ERROR {skill_name}: empty description from Claude", file=sys.stderr) 

138 errors += 1 

139 continue 

140 

141 if apply: 

142 _write_description_to_frontmatter(skill_md, new_desc) 

143 if not quiet: 

144 print(f" APPLY {skill_name}: {new_desc}") 

145 else: 

146 if not quiet: 

147 print(f" DRY {skill_name}: {new_desc}") 

148 

149 processed += 1 

150 

151 return processed, skipped, errors 

152 

153 

154def main_generate_skill_descriptions() -> int: 

155 """Entry point for ll-generate-skill-descriptions CLI.""" 

156 parser = argparse.ArgumentParser( 

157 prog="ll-generate-skill-descriptions", 

158 description=( 

159 "Auto-generate ≤100-char skill descriptions via Claude CLI. " 

160 "Dry-run by default; use --apply to write back to SKILL.md frontmatter." 

161 ), 

162 formatter_class=argparse.RawDescriptionHelpFormatter, 

163 epilog=""" 

164Examples: 

165 ll-generate-skill-descriptions # Dry-run: preview generated descriptions 

166 ll-generate-skill-descriptions --apply # Write descriptions back to SKILL.md files 

167 ll-generate-skill-descriptions --quiet # Suppress per-skill output 

168""", 

169 ) 

170 parser.add_argument( 

171 "--apply", 

172 action="store_true", 

173 default=False, 

174 help="Write generated descriptions back to SKILL.md frontmatter (default: dry-run only)", 

175 ) 

176 parser.add_argument( 

177 "--quiet", 

178 action="store_true", 

179 default=False, 

180 help="Suppress per-skill output; only print final summary", 

181 ) 

182 

183 args = parser.parse_args() 

184 

185 plugin_root = _find_plugin_root() 

186 skills_dir = plugin_root / "skills" 

187 

188 if not skills_dir.exists(): 

189 print(f"ERROR: skills directory not found: {skills_dir}", file=sys.stderr) 

190 return 1 

191 

192 mode = "APPLY" if args.apply else "DRY-RUN" 

193 if not args.quiet: 

194 print(f"ll-generate-skill-descriptions [{mode}]") 

195 print(f"Skills dir: {skills_dir}") 

196 print() 

197 

198 processed, skipped, errors = _process_skills(skills_dir, args.apply, args.quiet) 

199 

200 print(f"\nDone: {processed} generated, {skipped} skipped, {errors} errors") 

201 return 0 if errors == 0 else 1