perf-skill 0.2.0 → 0.3.0

package/.claude-plugin/README.md

@@ -0,0 +1,53 @@
+# perf-skill for Claude Marketplace
+
+This directory contains the Claude Marketplace plugin configuration for perf-skill.
+
+## Files
+
+- `plugin.json` - Main plugin manifest defining skills, installation, and compatibility
+- `marketplace.json` - Marketplace listing metadata (description, category, triggers)
+
+## Publishing to Claude Marketplace
+
+### Prerequisites
+
+1. Ensure the npm package is published: `npm publish`
+2. Verify the SKILL.md is included in the npm package
+3. Test the installation: `npx perf-skill init --ai claude`
+
+### Submission
+
+1. Visit [Claude Marketplace Developer Portal](https://claude.ai/marketplace/developer)
+2. Submit this repository for review
+3. The marketplace will validate:
+   - Plugin manifest schema
+   - Installation process
+   - Skill file structure
+   - Documentation quality
+
+### Local Testing
+
+```bash
+# Install locally for testing
+npx perf-skill init --ai claude --scope project
+
+# Verify skill installation
+cat .claude/skills/perf-skill/SKILL.md
+```
+
+## Trigger Configuration
+
+The `marketplace.json` defines when Claude should suggest this skill:
+
+- **File patterns**: `*.pb.gz`, `*.pprof`
+- **Keywords**: profile, pprof, cpu, heap, memory, performance, slow, bottleneck
+- **Intents**: "analyze profile", "why is my app slow", "compare performance"
+
+## Version Sync
+
+Keep `version` in `plugin.json` synchronized with `package.json` version.
+
+## Support
+
+- Issues: https://github.com/skillsland/perf-skill/issues
+- Documentation: https://github.com/skillsland/perf-skill#readme

package/.claude-plugin/marketplace.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://claude.ai/plugins/v1/marketplace.schema.json",
+  "listing": {
+    "name": "perf-skill",
+    "tagline": "AI-powered pprof profile analysis",
+    "shortDescription": "Convert CPU and heap profiles to structured evidence for performance optimization",
+    "longDescription": "perf-skill is a deterministic evidence generator for pprof profiles. It converts .pb.gz CPU and heap profiles into structured Markdown and JSON, enabling AI agents to provide optimization recommendations based on factual evidence.\n\n## Features\n\n- **Analyze** - Convert profiles to structured hotspot reports\n- **Diff** - Compare two profiles to find regressions\n- **Profile** - Capture CPU and heap profiles from Node.js apps\n- **Evidence-first** - Produces structured data for AI agents to interpret\n\n## Use Cases\n\n- Identify CPU bottlenecks in Node.js applications\n- Find memory leaks and allocation hotspots\n- Compare before/after profiles to verify optimizations\n- Generate evidence for performance code reviews",
+    "category": "developer-tools",
+    "subcategory": "performance",
+    "icon": "chart-line",
+    "screenshots": [],
+    "documentation": "https://github.com/skillsland/perf-skill#readme",
+    "support": {
+      "url": "https://github.com/skillsland/perf-skill/issues",
+      "email": null
+    },
+    "pricing": {
+      "type": "free"
+    },
+    "stats": {
+      "installs": 0,
+      "rating": null,
+      "reviews": 0
+    }
+  },
+  "triggers": {
+    "filePatterns": [
+      "*.pb.gz",
+      "*.pprof"
+    ],
+    "keywords": [
+      "profile",
+      "pprof",
+      "cpu",
+      "heap",
+      "memory",
+      "performance",
+      "slow",
+      "bottleneck",
+      "hotspot",
+      "optimize",
+      "regression"
+    ],
+    "intents": [
+      "analyze profile",
+      "why is my app slow",
+      "compare performance",
+      "find memory leak",
+      "cpu profiling",
+      "heap analysis"
+    ]
+  },
+  "requirements": {
+    "runtime": "node",
+    "minVersion": "20.0.0",
+    "dependencies": []
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://claude.ai/plugins/v1/plugin.schema.json",
+  "name": "perf-skill",
+  "version": "0.3.0",
+  "description": "Performance profile evidence extractor - Convert pprof CPU and heap profiles to structured Markdown and JSON for AI-powered performance analysis",
+  "author": "skillsland",
+  "license": "MIT",
+  "homepage": "https://github.com/skillsland/perf-skill",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skillsland/perf-skill.git"
+  },
+  "keywords": [
+    "performance",
+    "profiling",
+    "pprof",
+    "cpu",
+    "heap",
+    "memory",
+    "optimization",
+    "analysis",
+    "node.js",
+    "evidence"
+  ],
+  "skills": [
+    {
+      "name": "perf-skill",
+      "path": ".claude/skills/perf-skill/SKILL.md",
+      "description": "Analyze pprof CPU and heap profiles to identify performance bottlenecks"
+    }
+  ],
+  "install": {
+    "type": "npm",
+    "package": "perf-skill",
+    "postInstall": "npx perf-skill init --ai claude"
+  },
+  "compatibility": {
+    "claude": ">=1.0.0"
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,164 @@
+# CLAUDE.md - Developer Guide for perf-skill
+
+This document provides guidelines for AI agents and developers working with the perf-skill codebase.
+
+## Project Overview
+
+perf-skill is an AI skill that converts pprof CPU and heap profiles (.pb.gz) into structured Markdown and JSON evidence. It follows a **deterministic, evidence-first** design philosophy - the tool produces factual data without AI dependencies, while AI agents can optionally enhance the output with recommendations.
+
+## Repository Structure
+
+```
+perf-skill/
+├── src/
+│   ├── cli/              # CLI implementation
+│   │   ├── main.ts       # CLI entry point
+│   │   ├── init.ts       # Skill installation logic
+│   │   ├── platforms.ts  # Multi-platform configurations
+│   │   └── template.ts   # Template rendering engine
+│   ├── parser/           # pprof parsing logic
+│   ├── renderer/         # Markdown/JSON output
+│   ├── profile/          # Node.js profiling
+│   └── index.ts          # Library exports
+├── test/                 # Test files
+├── SKILL.md              # Main skill definition
+├── .claude-plugin/       # Claude Marketplace configs
+├── package.json
+└── README.md
+```
+
+## Key Commands
+
+### Development
+
+```bash
+# Build
+npm run build
+
+# Run CLI in development
+npm run cli -- analyze profile.pb.gz
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+### CLI Usage
+
+```bash
+# Analyze a profile
+npx perf-skill analyze cpu.pb.gz -o report.md
+
+# Compare profiles
+npx perf-skill diff base.pb.gz current.pb.gz
+
+# Profile and analyze a Node.js app
+npx perf-skill run app.js --duration 10s
+
+# Install skill for a platform
+npx perf-skill init --ai cursor
+npx perf-skill init --ai claude
+npx perf-skill init --ai all
+```
+
+## Architecture Decisions
+
+### Evidence-First Design
+
+- The core analyzer produces structured data without AI
+- LLM integration is optional (via `--ai` flag)
+- All outputs are reproducible and deterministic
+
+### Multi-Platform Support
+
+The `init` command supports 13+ AI platforms:
+- Claude, Cursor, Windsurf, Copilot, Kiro
+- Codex, Qoder, Roo Code, Gemini, Trae
+- OpenCode, Continue, CodeBuddy
+
+Each platform has its own configuration in `src/cli/platforms.ts`.
+
+### Template System
+
+Platform-specific skill files are generated from:
+1. Base `SKILL.md` content
+2. Platform configuration (frontmatter, sections)
+3. Template engine in `src/cli/template.ts`
+
+## Contributing Guidelines
+
+### Code Style
+
+- Use TypeScript strict mode
+- Follow existing patterns for error handling
+- Add tests for new features
+- Update SKILL.md for user-facing changes
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+node --test --import tsx test/parser.test.ts
+```
+
+### Pull Request Process
+
+1. Create feature branch from `main`
+2. Make changes with descriptive commits
+3. Ensure tests pass: `npm test`
+4. Ensure lint passes: `npm run lint`
+5. Update documentation if needed
+6. Submit PR with clear description
+
+## Common Tasks
+
+### Adding a New Platform
+
+1. Add platform to `AI_PLATFORMS` array in `src/cli/platforms.ts`
+2. Add configuration to `PLATFORM_CONFIGS` object
+3. Test installation: `npm run cli -- init --ai <platform>`
+
+### Updating SKILL.md
+
+1. Edit the root `SKILL.md` file
+2. Test rendering: `npm run cli -- init --ai claude --dry-run`
+3. Verify frontmatter is valid YAML
+
+### Publishing
+
+```bash
+# Bump version
+npm version patch|minor|major
+
+# Publish to npm
+npm publish
+
+# Sync Claude Marketplace
+# - Update version in .claude-plugin/plugin.json
+# - Submit to marketplace for review
+```
+
+## Debugging
+
+### Common Issues
+
+1. **Profile parsing fails**: Check file is valid gzip-compressed protobuf
+2. **Source code not included**: Verify `--source-dir` path exists
+3. **Platform install fails**: Check directory permissions
+
+### Verbose Mode
+
+```bash
+npx perf-skill analyze profile.pb.gz --verbose
+```
+
+## Security Considerations
+
+- Profile data may contain sensitive information
+- Use `--redact` (default) to sanitize paths
+- Never commit real profiles to the repository