panopticon-cli 0.4.6 → 0.4.7

package/skills/session-health/scripts/check_sessions.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+Session Health Checker - Detects stuck/corrupted Claude Code sessions
+
+Usage:
+    python check_sessions.py [--fix] [--path PATH]
+
+Detects:
+    - Warmup sidechain loops (tool calls returning "Warmup" errors)
+    - Excessive message counts (>500 messages)
+    - Infinite retry patterns (same command repeated >10 times)
+"""
+
+import argparse
+import json
+import os
+import sys
+from collections import Counter
+from pathlib import Path
+from datetime import datetime
+
+
+def analyze_session(jsonl_path: Path) -> dict:
+    """Analyze a single session file for health issues."""
+    issues = []
+    stats = {
+        "path": str(jsonl_path),
+        "name": jsonl_path.name,
+        "size_kb": jsonl_path.stat().st_size / 1024,
+        "message_count": 0,
+        "warmup_errors": 0,
+        "tool_calls": Counter(),
+        "is_sidechain": False,
+        "issues": [],
+    }
+
+    try:
+        with open(jsonl_path, 'r') as f:
+            for line in f:
+                stats["message_count"] += 1
+                try:
+                    msg = json.loads(line)
+
+                    # Check if sidechain
+                    if msg.get("isSidechain"):
+                        stats["is_sidechain"] = True
+
+                    # Check for warmup errors
+                    if msg.get("type") == "user":
+                        content = msg.get("message", {}).get("content", [])
+                        if isinstance(content, list):
+                            for item in content:
+                                if isinstance(item, dict):
+                                    if item.get("content") == "Warmup" and item.get("is_error"):
+                                        stats["warmup_errors"] += 1
+
+                    # Track tool calls
+                    if msg.get("type") == "assistant":
+                        content = msg.get("message", {}).get("content", [])
+                        if isinstance(content, list):
+                            for item in content:
+                                if isinstance(item, dict) and item.get("type") == "tool_use":
+                                    tool_input = item.get("input", {})
+                                    if isinstance(tool_input, dict):
+                                        cmd = tool_input.get("command", item.get("name", "unknown"))
+                                        stats["tool_calls"][cmd] += 1
+
+                except json.JSONDecodeError:
+                    continue
+
+    except Exception as e:
+        stats["issues"].append(f"Error reading file: {e}")
+        return stats
+
+    # Detect issues
+    if stats["warmup_errors"] > 10:
+        stats["issues"].append(f"CRITICAL: Warmup loop detected ({stats['warmup_errors']} warmup errors)")
+
+    if stats["message_count"] > 500:
+        stats["issues"].append(f"WARNING: Excessive messages ({stats['message_count']})")
+
+    # Check for repeated commands
+    for cmd, count in stats["tool_calls"].most_common(5):
+        if count > 50:
+            stats["issues"].append(f"WARNING: Command repeated {count}x: {cmd[:50]}...")
+
+    if stats["size_kb"] > 2000:  # > 2MB
+        stats["issues"].append(f"WARNING: Large session file ({stats['size_kb']:.0f}KB)")
+
+    return stats
+
+
+def find_sessions(base_path: Path) -> list:
+    """Find all session files."""
+    sessions = []
+    for jsonl in base_path.rglob("*.jsonl"):
+        sessions.append(jsonl)
+    return sessions
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Check Claude Code session health")
+    parser.add_argument("--fix", action="store_true", help="Remove problematic sessions")
+    parser.add_argument("--path", default=os.path.expanduser("~/.claude/projects"),
+                        help="Path to projects directory")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    base_path = Path(args.path)
+    if not base_path.exists():
+        print(f"Path not found: {base_path}")
+        sys.exit(1)
+
+    sessions = find_sessions(base_path)
+    results = []
+    problematic = []
+
+    for session_path in sessions:
+        stats = analyze_session(session_path)
+        results.append(stats)
+        if stats["issues"]:
+            problematic.append(stats)
+
+    if args.json:
+        print(json.dumps(results, indent=2, default=str))
+        return
+
+    # Summary
+    print(f"\n{'='*60}")
+    print(f"SESSION HEALTH CHECK")
+    print(f"{'='*60}")
+    print(f"Total sessions: {len(sessions)}")
+    print(f"Problematic: {len(problematic)}")
+
+    if problematic:
+        print(f"\n{'='*60}")
+        print("ISSUES FOUND:")
+        print(f"{'='*60}")
+
+        for stats in problematic:
+            print(f"\n{stats['name']}")
+            print(f"  Size: {stats['size_kb']:.0f}KB | Messages: {stats['message_count']}")
+            print(f"  Warmup errors: {stats['warmup_errors']}")
+            print(f"  Sidechain: {stats['is_sidechain']}")
+            for issue in stats["issues"]:
+                print(f"  -> {issue}")
+
+        if args.fix:
+            print(f"\n{'='*60}")
+            print("CLEANING UP...")
+            print(f"{'='*60}")
+            for stats in problematic:
+                if any("CRITICAL" in i for i in stats["issues"]):
+                    try:
+                        os.remove(stats["path"])
+                        print(f"Removed: {stats['name']}")
+                    except Exception as e:
+                        print(f"Failed to remove {stats['name']}: {e}")
+    else:
+        print("\nAll sessions healthy!")
+
+    return len(problematic)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: skill-creator
+description: Guide for creating effective Claude Code skills. Use when users want to create a new skill, update an existing skill, or need guidance on skill best practices. Triggers on requests like "create a skill", "make a new skill", "help me build a skill", "skill development", or "extend Claude's capabilities".
+license: Apache 2.0 (based on Anthropic's skills repo)
+---
+
+# Skill Creator
+
+Create effective skills that extend Claude's capabilities with specialized knowledge, workflows, and tools.
+
+## Core Principles
+
+### Concise is Key
+The context window is shared. Only add what Claude doesn't already know. Challenge each piece: "Does this justify its token cost?"
+
+### Degrees of Freedom
+- **High freedom** (text instructions): Multiple valid approaches, context-dependent decisions
+- **Medium freedom** (pseudocode/parameterized scripts): Preferred pattern exists, some variation OK
+- **Low freedom** (specific scripts): Fragile operations, consistency critical
+
+## Skill Anatomy
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description - REQUIRED)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/     - Executable code (deterministic, reusable)
+    ├── references/  - Documentation loaded into context as needed
+    └── assets/      - Files used in output (templates, images)
+```
+
+### Frontmatter (Critical)
+```yaml
+---
+name: my-skill
+description: What it does AND when to use it. This is the ONLY thing Claude sees to decide if the skill triggers. Be comprehensive.
+---
+```
+
+### Progressive Disclosure
+1. **Metadata** (~100 words) - Always in context
+2. **SKILL.md body** (<5k words) - When skill triggers
+3. **Bundled resources** - As needed
+
+Keep SKILL.md under 500 lines. Split into references when approaching limit.
+
+## Creation Process
+
+### Step 1: Understand with Examples
+- What functionality should this skill support?
+- What would users say to trigger it?
+- Can you give concrete usage examples?
+
+### Step 2: Plan Reusable Contents
+For each example, identify:
+- Scripts for repetitive code
+- References for documentation/schemas
+- Assets for templates/boilerplate
+
+### Step 3: Initialize
+```bash
+python scripts/init_skill.py <skill-name> --path <output-directory>
+```
+
+### Step 4: Implement
+1. Create scripts/, references/, assets/ files
+2. Test scripts by actually running them
+3. Write SKILL.md with:
+   - Comprehensive description in frontmatter
+   - Instructions referencing bundled resources
+   - Use imperative form ("Do X", not "You should do X")
+
+### Step 5: Package
+```bash
+python scripts/package_skill.py <path/to/skill-folder> [output-dir]
+```
+
+### Step 6: Iterate
+Use skill on real tasks → Notice struggles → Update → Test again
+
+## What NOT to Include
+- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
+- Setup/testing procedures
+- User-facing documentation
+- Anything not needed by the AI agent
+
+## Reference Files
+
+- See `references/workflows.md` for multi-step process patterns
+- See `references/output-patterns.md` for output format patterns

package/skills/skill-creator/scripts/init_skill.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    python init_skill.py <skill-name> --path <output-directory>
+
+Example:
+    python init_skill.py pdf-editor --path ./skills
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SKILL_MD_TEMPLATE = '''---
+name: {skill_name}
+description: TODO - Describe what this skill does AND when to use it. Include trigger phrases.
+---
+
+# {skill_title}
+
+TODO: Write instructions for using this skill.
+
+## Overview
+
+TODO: Brief description of what this skill does.
+
+## Usage
+
+TODO: How to use this skill.
+
+## Resources
+
+- `scripts/` - Executable automation scripts
+- `references/` - Documentation loaded as needed
+- `assets/` - Templates and files for output
+'''
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example script - replace with your actual script.
+"""
+
+def main():
+    print("Hello from {skill_name}!")
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = '''# {skill_title} Reference
+
+This is an example reference file. Replace with actual documentation.
+
+## Section 1
+
+TODO: Add reference content here.
+'''
+
+
+def validate_skill_name(name: str) -> bool:
+    """Validate skill name follows conventions."""
+    if not re.match(r'^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$', name):
+        return False
+    if len(name) > 40:
+        return False
+    if '--' in name:
+        return False
+    return True
+
+
+def to_title(skill_name: str) -> str:
+    """Convert skill-name to Skill Name."""
+    return ' '.join(word.capitalize() for word in skill_name.split('-'))
+
+
+def init_skill(skill_name: str, output_path: Path) -> bool:
+    """Initialize a new skill directory structure."""
+
+    if not validate_skill_name(skill_name):
+        print(f"Error: Invalid skill name '{skill_name}'")
+        print("  - Use lowercase letters, digits, and hyphens only")
+        print("  - Must start and end with letter or digit")
+        print("  - Maximum 40 characters")
+        print("  - No consecutive hyphens")
+        return False
+
+    skill_dir = output_path / skill_name
+
+    if skill_dir.exists():
+        print(f"Error: Directory already exists: {skill_dir}")
+        return False
+
+    skill_title = to_title(skill_name)
+
+    # Create directories
+    skill_dir.mkdir(parents=True)
+    (skill_dir / 'scripts').mkdir()
+    (skill_dir / 'references').mkdir()
+    (skill_dir / 'assets').mkdir()
+
+    # Create SKILL.md
+    skill_md = skill_dir / 'SKILL.md'
+    skill_md.write_text(SKILL_MD_TEMPLATE.format(
+        skill_name=skill_name,
+        skill_title=skill_title
+    ))
+
+    # Create example script
+    example_script = skill_dir / 'scripts' / 'example.py'
+    example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+    example_script.chmod(0o755)
+
+    # Create example reference
+    example_ref = skill_dir / 'references' / 'example.md'
+    example_ref.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+
+    # Create .gitkeep in assets
+    (skill_dir / 'assets' / '.gitkeep').touch()
+
+    print(f"Created skill: {skill_dir}")
+    print()
+    print("Next steps:")
+    print(f"  1. Edit {skill_dir}/SKILL.md")
+    print(f"  2. Add scripts to {skill_dir}/scripts/")
+    print(f"  3. Add references to {skill_dir}/references/")
+    print(f"  4. Add assets to {skill_dir}/assets/")
+    print(f"  5. Delete example files you don't need")
+
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Initialize a new skill')
+    parser.add_argument('skill_name', help='Name of the skill (hyphen-case)')
+    parser.add_argument('--path', required=True, help='Output directory')
+
+    args = parser.parse_args()
+
+    output_path = Path(args.path).resolve()
+
+    if not output_path.exists():
+        output_path.mkdir(parents=True)
+
+    success = init_skill(args.skill_name, output_path)
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/skill-creator/scripts/package_skill.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file
+
+Usage:
+    python package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python package_skill.py ./my-skill
+    python package_skill.py ./my-skill ./dist
+"""
+
+import sys
+import zipfile
+import re
+from pathlib import Path
+
+
+def validate_skill(skill_path: Path) -> tuple[bool, str]:
+    """Validate skill structure and contents."""
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    content = skill_md.read_text()
+
+    # Check frontmatter
+    if not content.startswith('---'):
+        return False, "SKILL.md must start with YAML frontmatter (---)"
+
+    # Extract frontmatter
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return False, "Invalid frontmatter format"
+
+    frontmatter = parts[1]
+
+    # Check required fields
+    if 'name:' not in frontmatter:
+        return False, "Frontmatter missing 'name' field"
+    if 'description:' not in frontmatter:
+        return False, "Frontmatter missing 'description' field"
+
+    # Check description isn't a TODO
+    if 'TODO' in frontmatter:
+        return False, "Frontmatter contains TODO - please complete the description"
+
+    # Check for body content
+    body = parts[2].strip()
+    if len(body) < 50:
+        return False, "SKILL.md body is too short"
+
+    return True, "Skill is valid"
+
+
+def package_skill(skill_path: Path, output_dir: Path = None) -> Path:
+    """Package a skill folder into a .skill file."""
+
+    if not skill_path.exists():
+        print(f"Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"Error: Path is not a directory: {skill_path}")
+        return None
+
+    # Validate
+    print("Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"Validation failed: {message}")
+        return None
+    print(f"  {message}")
+
+    # Determine output
+    skill_name = skill_path.name
+    if output_dir:
+        output_dir = Path(output_dir).resolve()
+        output_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        output_dir = Path.cwd()
+
+    skill_filename = output_dir / f"{skill_name}.skill"
+
+    # Create zip
+    try:
+        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            for file_path in skill_path.rglob('*'):
+                if file_path.is_file():
+                    # Skip common exclusions
+                    if file_path.name.startswith('.') and file_path.name != '.gitkeep':
+                        continue
+                    if '__pycache__' in str(file_path):
+                        continue
+
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\nPackaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        print(f"Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python package_skill.py <path/to/skill-folder> [output-directory]")
+        sys.exit(1)
+
+    skill_path = Path(sys.argv[1]).resolve()
+    output_dir = Path(sys.argv[2]).resolve() if len(sys.argv) > 2 else None
+
+    print(f"Packaging skill: {skill_path}")
+    result = package_skill(skill_path, output_dir)
+    sys.exit(0 if result else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/stitch-design-md/README.md

@@ -0,0 +1,34 @@
+# Stitch Design System Documentation Skill
+
+## Install
+
+```bash
+npx add-skill google-labs-code/stitch-skills --skill design-md --global
+```
+
+## Example Prompt
+
+```text
+Analyze my Furniture Collection project's Home screen and generate a comprehensive DESIGN.md file documenting the design system.
+```
+
+## Skill Structure
+
+This repository follows the **Agent Skills** open standard. Each skill is self-contained with its own logic, workflow, and reference materials.
+
+```text
+design-md/
+├── SKILL.md           — Core instructions & workflow
+├── examples/          — Sample DESIGN.md outputs
+└── README.md          — This file
+```
+
+## How it Works
+
+When activated, the agent follows a structured design analysis pipeline:
+
+1. **Retrieval**: Uses the Stitch MCP Server to fetch project screens, HTML code, and design metadata.
+2. **Extraction**: Identifies design tokens including colors, typography, spacing, and component patterns.
+3. **Translation**: Converts technical CSS/Tailwind values into descriptive, natural design language.
+4. **Synthesis**: Generates a comprehensive DESIGN.md following the semantic design system format.
+5. **Alignment**: Ensures output follows Stitch Effective Prompting Guide principles for optimal screen generation.