1"""
2SkillGenerator: Converts optimization insights into shareable Agent Skills.
3 
4Transforms the learnings from optimization loops into reusable skills
5following the Agent Skills template format.
6"""
7 
8import json
9import os
10from datetime import datetime
11from pathlib import Path
12from typing import Any
13 
14import anthropic
15 
16from reasoning_trace_optimizer.models import (
17    AnalysisResult,
18    LoopResult,
19    Pattern,
20    PatternType,
21)
22 
23 
24SKILL_TEMPLATE = '''---
25name: {skill_name}
26description: "{description}"
27---
28 
29# {title}
30 
31{intro}
32 
33## When to Activate
34 
35{activation}
36 
37## Core Concepts
38 
39{concepts}
40 
41## Patterns to Avoid
42 
43{anti_patterns}
44 
45## Recommended Practices
46 
47{practices}
48 
49## Guidelines
50 
51{guidelines}
52 
53## Examples
54 
55{examples}
56 
57---
58 
59## Skill Metadata
60 
61**Generated**: {date}
62**Source**: Reasoning Trace Optimizer
63**Optimization Iterations**: {iterations}
64**Score Improvement**: {initial_score:.1f} → {final_score:.1f} (+{improvement:.1f}%)
65'''
66 
67 
68GENERATOR_SYSTEM_PROMPT = """You are an expert at converting agent optimization insights into reusable skills.
69 
70Your task is to analyze optimization results and generate a shareable Agent Skill that
71captures the learnings so other developers can benefit.
72 
73The skill should:
741. Describe WHEN to use these learnings (activation triggers)
752. Explain the PATTERNS to avoid (anti-patterns found)
763. Provide CONCRETE practices that improved performance
774. Give VERIFIABLE guidelines (things that can be checked)
785. Include EXAMPLES showing before/after improvements
79 
80Write in a clear, direct style. Focus on actionable guidance, not theory."""
81 
82 
83def _format_list_to_markdown(items: list | str) -> str:
84    """Convert a list to markdown bullet points."""
85    if isinstance(items, str):
86        return items
87    if not items:
88        return ""
89 
90    import re
91    formatted = []
92    for item in items:
93        # Strip any existing leading bullet points/dashes to avoid duplication
94        cleaned = re.sub(r'^[-*•]\s*', '', str(item).strip())
95        formatted.append(f"- {cleaned}")
96    return "\n".join(formatted)
97 
98 
99def _format_numbered_list_to_markdown(items: list | str) -> str:
100    """Convert a list to markdown numbered list."""
101    if isinstance(items, str):
102        return items
103    if not items:
104        return ""
105 
106    import re
107    formatted = []
108    for i, item in enumerate(items):
109        # Strip any existing leading numbers (e.g., "1. ", "2. ") to avoid duplication
110        cleaned = re.sub(r'^\d+\.\s*', '', str(item).strip())
111        formatted.append(f"{i+1}. {cleaned}")
112    return "\n".join(formatted)
113 
114 
115def _format_examples_to_markdown(examples: list | str) -> str:
116    """Convert example dicts to markdown format."""
117    if isinstance(examples, str):
118        return examples
119    if not examples:
120        return ""
121 
122    parts = []
123    for i, ex in enumerate(examples):
124        if isinstance(ex, dict):
125            parts.append(f"### Example {i+1}: {ex.get('context', 'Scenario')}")
126            if ex.get('before'):
127                parts.append(f"\n**Before:**\n```\n{ex['before']}\n```")
128            if ex.get('after'):
129                parts.append(f"\n**After:**\n```\n{ex['after']}\n```")
130            if ex.get('improvement'):
131                parts.append(f"\n**Improvement:** {ex['improvement']}")
132            parts.append("")
133        else:
134            parts.append(f"- {ex}")
135    return "\n".join(parts)
136 
137 
138class SkillGenerator:
139    """
140    Generates shareable Agent Skills from optimization results.
141 
142    Converts the learnings from optimization loops into the standard
143    Agent Skills format for sharing with other developers.
144 
145    Example:
146        ```python
147        generator = SkillGenerator()
148        skill_path = generator.generate(
149            result=loop_result,
150            skill_name="web-search-agent",
151            output_dir="./generated_skills"
152        )
153        print(f"Generated skill at: {skill_path}")
154        ```
155    """
156 
157    def __init__(
158        self,
159        api_key: str | None = None,
160        base_url: str = "https://api.minimax.io/anthropic",
161        model: str = "MiniMax-M2.1",
162    ):
163        """
164        Initialize SkillGenerator.
165 
166        Args:
167            api_key: MiniMax API key
168            base_url: API endpoint
169            model: Model for skill generation
170        """
171        self.model = model
172        self.client = anthropic.Anthropic(
173            api_key=api_key or os.environ.get("ANTHROPIC_API_KEY"),
174            base_url=base_url,
175        )
176 
177    def generate(
178        self,
179        result: LoopResult,
180        skill_name: str,
181        output_dir: str = "./generated_skills",
182        title: str | None = None,
183    ) -> str:
184        """
185        Generate an Agent Skill from optimization results.
186 
187        Args:
188            result: The optimization loop result
189            skill_name: Name for the skill (lowercase-with-hyphens)
190            output_dir: Directory to save the skill
191            title: Optional human-readable title
192 
193        Returns:
194            Path to the generated SKILL.md file
195        """
196        # Extract insights from all iterations
197        all_patterns = self._collect_patterns(result)
198        all_recommendations = self._collect_recommendations(result)
199        key_changes = self._collect_key_changes(result)
200 
201        # Generate skill content using M2.1
202        content = self._generate_skill_content(
203            task=result.task,
204            patterns=all_patterns,
205            recommendations=all_recommendations,
206            key_changes=key_changes,
207            initial_prompt=result.iterations[0].trace.system_prompt if result.iterations else "",
208            final_prompt=result.final_prompt,
209        )
210 
211        # Format content - convert lists to markdown
212        formatted_content = {
213            "activation": _format_list_to_markdown(content.get("activation", "")),
214            "concepts": _format_list_to_markdown(content.get("concepts", "")),
215            "anti_patterns": _format_list_to_markdown(content.get("anti_patterns", "")),
216            "practices": _format_list_to_markdown(content.get("practices", "")),
217            "guidelines": _format_numbered_list_to_markdown(content.get("guidelines", "")),
218            "examples": _format_examples_to_markdown(content.get("examples", "")),
219        }
220 
221        # Format using template
222        skill_content = SKILL_TEMPLATE.format(
223            skill_name=skill_name,
224            description=content.get("description", f"Optimized practices for {skill_name}"),
225            title=title or content.get("title", skill_name.replace("-", " ").title()),
226            intro=content.get("intro", ""),
227            activation=formatted_content["activation"],
228            concepts=formatted_content["concepts"],
229            anti_patterns=formatted_content["anti_patterns"],
230            practices=formatted_content["practices"],
231            guidelines=formatted_content["guidelines"],
232            examples=formatted_content["examples"],
233            date=datetime.now().strftime("%Y-%m-%d"),
234            iterations=result.total_iterations,
235            initial_score=result.initial_score,
236            final_score=result.final_score,
237            improvement=result.improvement_percentage,
238        )
239 
240        # Save skill
241        skill_dir = Path(output_dir) / skill_name
242        skill_dir.mkdir(parents=True, exist_ok=True)
243 
244        skill_path = skill_dir / "SKILL.md"
245        with open(skill_path, "w") as f:
246            f.write(skill_content)
247 
248        # Save optimization data as reference
249        self._save_references(skill_dir, result, content)
250 
251        return str(skill_path)
252 
253    def generate_from_analysis(
254        self,
255        analyses: list[AnalysisResult],
256        skill_name: str,
257        task_description: str,
258        output_dir: str = "./generated_skills",
259    ) -> str:
260        """
261        Generate a skill from multiple analysis results (without full loop).
262 
263        Useful when you have analysis data but didn't run the full optimization loop.
264 
265        Args:
266            analyses: List of analysis results
267            skill_name: Name for the skill
268            task_description: Description of the task context
269            output_dir: Output directory
270 
271        Returns:
272            Path to generated skill
273        """
274        # Aggregate patterns and recommendations
275        all_patterns = []
276        all_recommendations = []
277 
278        for analysis in analyses:
279            all_patterns.extend(analysis.patterns)
280            all_recommendations.extend(analysis.recommendations)
281 
282        content = self._generate_skill_content(
283            task=task_description,
284            patterns=all_patterns,
285            recommendations=list(set(all_recommendations)),
286            key_changes=[],
287            initial_prompt="",
288            final_prompt="",
289        )
290 
291        # Calculate average score
292        avg_score = sum(a.overall_score for a in analyses) / len(analyses) if analyses else 0
293 
294        skill_content = SKILL_TEMPLATE.format(
295            skill_name=skill_name,
296            description=content.get("description", f"Learnings for {skill_name}"),
297            title=content.get("title", skill_name.replace("-", " ").title()),
298            intro=content.get("intro", ""),
299            activation=content.get("activation", ""),
300            concepts=content.get("concepts", ""),
301            anti_patterns=content.get("anti_patterns", ""),
302            practices=content.get("practices", ""),
303            guidelines=content.get("guidelines", ""),
304            examples=content.get("examples", ""),
305            date=datetime.now().strftime("%Y-%m-%d"),
306            iterations=len(analyses),
307            initial_score=avg_score,
308            final_score=avg_score,
309            improvement=0,
310        )
311 
312        skill_dir = Path(output_dir) / skill_name
313        skill_dir.mkdir(parents=True, exist_ok=True)
314 
315        skill_path = skill_dir / "SKILL.md"
316        with open(skill_path, "w") as f:
317            f.write(skill_content)
318 
319        return str(skill_path)
320 
321    def _collect_patterns(self, result: LoopResult) -> list[Pattern]:
322        """Collect all unique patterns from iterations."""
323        patterns = []
324        seen = set()
325 
326        for iteration in result.iterations:
327            for pattern in iteration.analysis.patterns:
328                key = (pattern.type, pattern.description[:50])
329                if key not in seen:
330                    patterns.append(pattern)
331                    seen.add(key)
332 
333        return patterns
334 
335    def _collect_recommendations(self, result: LoopResult) -> list[str]:
336        """Collect all unique recommendations."""
337        recommendations = []
338        seen = set()
339 
340        for iteration in result.iterations:
341            for rec in iteration.analysis.recommendations:
342                if rec not in seen:
343                    recommendations.append(rec)
344                    seen.add(rec)
345 
346        return recommendations
347 
348    def _collect_key_changes(self, result: LoopResult) -> list[str]:
349        """Collect all key changes from optimizations."""
350        changes = []
351 
352        for iteration in result.iterations:
353            if iteration.optimization:
354                changes.extend(iteration.optimization.key_changes)
355 
356        return changes
357 
358    def _generate_skill_content(
359        self,
360        task: str,
361        patterns: list[Pattern],
362        recommendations: list[str],
363        key_changes: list[str],
364        initial_prompt: str,
365        final_prompt: str,
366    ) -> dict[str, str]:
367        """Use M2.1 to generate skill content sections."""
368        patterns_text = "\n".join(
369            f"- [{p.severity.value}] {p.type.value}: {p.description}"
370            for p in patterns
371        )
372 
373        recommendations_text = "\n".join(f"- {r}" for r in recommendations)
374        changes_text = "\n".join(f"- {c}" for c in key_changes)
375 
376        prompt = f"""Generate an Agent Skill based on these optimization insights:
377 
378## Task Context
379{task}
380 
381## Patterns Detected (Anti-patterns to avoid)
382{patterns_text or "No significant patterns detected"}
383 
384## Recommendations from Analysis
385{recommendations_text or "No specific recommendations"}
386 
387## Key Changes That Improved Performance
388{changes_text or "No recorded changes"}
389 
390## Prompt Evolution
391Initial: {initial_prompt[:500] if initial_prompt else "N/A"}...
392Final: {final_prompt[:500] if final_prompt else "N/A"}...
393 
394---
395 
396Generate skill content as JSON:
397```json
398{{
399    "title": "Human-readable skill title",
400    "description": "One-line description for skill discovery (what triggers this skill)",
401    "intro": "2-3 sentence introduction explaining what this skill teaches",
402    "activation": "Bullet points of when to activate this skill (specific keywords, task types)",
403    "concepts": "Core concepts this skill covers (3-5 key ideas)",
404    "anti_patterns": "Patterns to AVOID - formatted as markdown list with descriptions",
405    "practices": "Recommended practices - formatted as markdown list",
406    "guidelines": "Numbered verifiable guidelines (things that can be checked)",
407    "examples": "1-2 concrete before/after examples showing improvement"
408}}
409```"""
410 
411        response = self.client.messages.create(
412            model=self.model,
413            max_tokens=4096,
414            system=GENERATOR_SYSTEM_PROMPT,
415            messages=[{"role": "user", "content": prompt}],
416        )
417 
418        # Parse response
419        for block in response.content:
420            if block.type == "text":
421                try:
422                    text = block.text
423                    if "```json" in text:
424                        text = text.split("```json")[1].split("```")[0]
425                    return json.loads(text)
426                except json.JSONDecodeError:
427                    pass
428 
429        # Return defaults if parsing fails
430        return {
431            "title": "Generated Agent Skill",
432            "description": f"Optimized practices for {task}",
433            "intro": "This skill contains learnings from automated prompt optimization.",
434            "activation": "- When working on similar tasks\n- When debugging agent failures",
435            "concepts": "See recommendations section.",
436            "anti_patterns": patterns_text or "No patterns identified.",
437            "practices": recommendations_text or "No specific practices.",
438            "guidelines": "1. Review the anti-patterns before implementation\n2. Apply recommended practices",
439            "examples": "See optimization artifacts for detailed examples.",
440        }
441 
442    def _save_references(
443        self,
444        skill_dir: Path,
445        result: LoopResult,
446        content: dict[str, str],
447    ) -> None:
448        """Save reference materials alongside the skill."""
449        refs_dir = skill_dir / "references"
450        refs_dir.mkdir(exist_ok=True)
451 
452        # Save optimization summary
453        summary = {
454            "task": result.task,
455            "iterations": result.total_iterations,
456            "initial_score": result.initial_score,
457            "final_score": result.final_score,
458            "improvement": result.improvement_percentage,
459            "converged": result.converged,
460            "generated_at": datetime.now().isoformat(),
461        }
462        with open(refs_dir / "optimization_summary.json", "w") as f:
463            json.dump(summary, f, indent=2)
464 
465        # Save final optimized prompt
466        with open(refs_dir / "optimized_prompt.txt", "w") as f:
467            f.write(result.final_prompt)
468 
469        # Save all patterns found
470        patterns_data = []
471        for iteration in result.iterations:
472            for p in iteration.analysis.patterns:
473                patterns_data.append({
474                    "type": p.type.value,
475                    "severity": p.severity.value,
476                    "description": p.description,
477                    "suggestion": p.suggestion,
478                    "iteration": iteration.iteration,
479                })
480 
481        with open(refs_dir / "patterns_found.json", "w") as f:
482            json.dump(patterns_data, f, indent=2)
483 
484 
485def generate_skill_from_loop(
486    result: LoopResult,
487    skill_name: str,
488    output_dir: str = "./generated_skills",
489) -> str:
490    """
491    Quick helper to generate a skill from optimization results.
492 
493    Args:
494        result: Optimization loop result
495        skill_name: Name for the skill
496        output_dir: Output directory
497 
498    Returns:
499        Path to generated skill
500    """
501    generator = SkillGenerator()
502    return generator.generate(result, skill_name, output_dir)
503