{"id":51558875,"url":"https://github.com/caomengxuan666/perf-skills","last_synced_at":"2026-07-10T08:32:40.224Z","repository":{"id":352183667,"uuid":"1214192674","full_name":"caomengxuan666/perf-skills","owner":"caomengxuan666","description":"Linux perf performance analysis skills for AI assistants (Claude, OpenCode, etc.)","archived":false,"fork":false,"pushed_at":"2026-04-18T09:29:25.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-18T10:29:52.994Z","etag":null,"topics":["ai-agent","claude-code","linux","opencode","perf","performance-analysis","skills"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caomengxuan666.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T08:32:56.000Z","updated_at":"2026-04-18T09:29:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/caomengxuan666/perf-skills","commit_stats":null,"previous_names":["caomengxuan666/perf-skills"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/caomengxuan666/perf-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caomengxuan666%2Fperf-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caomengxuan666%2Fperf-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caomengxuan666%2Fperf-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caomengxuan666%2Fperf-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caomengxuan666","download_url":"https://codeload.github.com/caomengxuan666/perf-skills/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caomengxuan666%2Fperf-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35326962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude-code","linux","opencode","perf","performance-analysis","skills"],"created_at":"2026-07-10T08:32:38.775Z","updated_at":"2026-07-10T08:32:40.215Z","avatar_url":"https://github.com/caomengxuan666.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linux Perf Performance Analysis Skills\n\nA comprehensive set of AI assistant skills for Linux `perf` performance analysis, based on real-world experience from the AstraDB project. These skills enable AI assistants to guide you through the complete workflow of profiling, analyzing, and optimizing application performance using Linux perf tools.\n\n## Features\n\n- ✅ Complete 5-phase workflow (Setup → Record → Analyze → Diagnose → Optimize)\n- ✅ Non-sudo workflow after one-time setup\n- ✅ CPU hotspot identification and optimization\n- ✅ System call analysis and bottleneck diagnosis\n- ✅ Comparative analysis (before/after, ASAN/no-ASAN)\n- ✅ Practical examples based on AstraDB project experience\n- ✅ Compatible with Claude Code, OpenCode, Cursor, and other AI agents\n\n## Skills Structure\n\n```\nperf-skills/\n├── linux-perf.skill.md              # Main skill file (load this first)\n└── linux-perf/\n    └── references/topics/\n        ├── cpu-hotspots.md          # CPU hotspot analysis guide\n        └── syscalls.md           # System call analysis guide\n```\n\n## Installation (One-line Install)\n\n### Method 1: Vercel skills CLI (Recommended for Multiple Agents)\n```bash\n# Install globally to all agents\nnpx -y skills add https://github.com/caomengxuan666/perf-skills --global --yes\n\n# Or install to specific agents\nnpx -y skills add https://github.com/caomengxuan666/perf-skills --agent opencode,claude-code --yes\n```\n\n### Method 2: Claude Code\n```bash\n/plugin marketplace add caomengxuan666/perf-skills\n/plugin install linux-perf@caomengxuan666/perf-skills\n```\n\n### Method 3: Manual\n```bash\ngit clone https://github.com/caomengxuan666/perf-skills.git /tmp/perf-skills\ncp -r /tmp/perf-skills/.claude/skills/linux-perf your-project/.claude/skills/\n# OR using git submodule\ngit submodule add https://github.com/caomengxuan666/perf-skills.git .claude/skills/linux-perf\n```\n\n## Quick Start\n\n### 1. Load the Skill\n\nWhen using an AI assistant that supports skills, load the main skill file:\n\n```\n/skill linux-perf/linux-perf.skill.md\n```\n\n### 2. Ask for Help\n\nExamples of questions to ask:\n\n- \"Help me profile my C++ application with perf\"\n- \"How do I find the CPU hotspots in my application?\"\n- \"Why is my application spending 50% of time in kernel mode?\"\n- \"How can I reduce system call overhead?\"\n- \"My application is slow, where should I start investigating?\"\n\n### 3. Get Step-by-Step Guidance\n\nThe skill will guide you through:\n1. Environment setup and permissions\n2. Data collection with perf record\n3. Data analysis with perf report\n4. Bottleneck diagnosis\n5. Optimization strategies\n6. Validation and verification\n\n## Skill Features\n\n### No-Sudo Workflow\n\nThe skill emphasizes non-sudo workflows:\n- One-time `setcap` setup for capabilities\n- No need for sudo in daily usage\n- Works in CI/CD environments\n- Portable across different systems\n\n### Complete Coverage\n\nEach phase of performance analysis is covered:\n- **Phase 1: Environment Preparation** - Setup, permissions, builds\n- **Phase 2: Data Collection** - Recording options, sampling strategies\n- **Phase 3: Data Analysis** - Interactive and command-line analysis\n- **Phase 4: Bottleneck Diagnosis** - Pattern recognition, root cause analysis\n- **Phase 5: Comparative Analysis** - Before/after comparisons\n\n### Practical Examples\n\nThe skills include:\n- Real-world command examples\n- Code optimization patterns (C++, Rust, Go)\n- Common mistakes and how to avoid them\n- Checklists for validation\n\n## Integration with AI Assistants\n\n### OpenCode\n\nTo use with OpenCode, create the skill file in your project:\n\n```bash\nmkdir -p skills\ncp linux-perf.skill.md skills/\n```\n\n### Claude\n\nFor Claude Desktop, place in the project directory:\n```\nyour-project/\n├── linux-perf.skill.md\n└── ...\n```\n\n### Other Tools\n\nMost AI coding assistants that support custom instructions or skill files can use these. Consult your tool's documentation for specific integration steps.\n\n## Workflow Example\n\n### User: \"My Rust application is slow, help me profile it\"\n\n**AI Assistant (with skill loaded):**\n\n1. **Setup Phase:**\n   ```bash\n   # Check permissions\n   cat /proc/sys/kernel/perf_event_paranoid\n\n   # One-time setup (if needed)\n   sudo setcap \"cap_perfmon,cap_sys_admin,cap_sys_ptrace+ep\" /usr/bin/perf\n   ```\n\n2. **Build with Debug Info:**\n   ```bash\n   # Cargo.toml\n   [profile.release]\n   debug = true\n   ```\n\n3. **Record Data:**\n   ```bash\n   # Find PID\n   pidof my_app\n\n   # Record during load\n   perf record -p \u003cPID\u003e -g -o perf.data -- sleep 30 \u0026\n   # Run your load test here\n   ```\n\n4. **Analyze:**\n   ```bash\n   # Interactive analysis\n   perf report -i perf.data -g graph\n\n   # Top hotspots\n   perf report --stdio -i perf.data -g none | head -50\n   ```\n\n5. **Diagnose \u0026 Optimize:**\n   The skill will help you interpret results and suggest specific optimizations based on the patterns found.\n\n## Reference Files\n\n### cpu-hotspots.md\n\nDeep dive into CPU hotspot analysis:\n- Understanding perf report output\n- Hotspot investigation steps\n- Common performance patterns and solutions\n- Algorithmic improvements\n- Compiler optimizations\n- Validation checklist\n\n### syscalls.md\n\nFocus on system call analysis:\n- Recording syscall-specific data\n- Common syscall bottlenecks (write, read, epoll, futex, mmap)\n- Optimization strategies for each syscall type\n- Measuring syscall performance\n- Advanced tools (strace, bpftrace)\n\n## Best Practices\n\n### 1. Always Profile Optimized Builds\n\n- Use `-O2` or `-O3` (not `-O0`)\n- Use `RelWithDebInfo` for CMake\n- Profile release builds, not debug builds\n\n### 2. Disable Sanitizers\n\n- ASAN adds 2-5x overhead\n- Valgrind adds 10-20x overhead\n- Profile clean builds for accurate data\n\n### 3. Record During Real Workload\n\n- Don't profile idle processes\n- Use representative load tests\n- Record for 10-30 seconds minimum\n\n### 4. Focus on Self%, Not Children%\n\n- Self% = actual CPU time in function\n- Children% = includes callee cost (misleading)\n- Prioritize by Self% for optimization\n\n### 5. User Space is the Cause\n\n- High kernel overhead is a symptom\n- Find user-space caller making syscalls\n- Optimize the caller, not the kernel\n\n## Common Scenarios\n\n### Scenario 1: High CPU Usage\n\n**Symptoms:** Application using 100% CPU, slow response\n\n**Investigation:**\n```bash\nperf record -p \u003cPID\u003e -g -o perf.data -- sleep 30\nperf report -i perf.data -g graph\n```\n\n**Look for:** High Self% functions, algorithmic complexity\n\n### Scenario 2: High System Time\n\n**Symptoms:** 50%+ time in kernel mode\n\n**Investigation:**\n```bash\nperf report --stdio -i perf.data --sort dso -g none\nperf report --stdio -i perf.data -g graph | grep syscalls\n```\n\n**Look for:** Frequent syscalls (write, read, futex, epoll)\n\n### Scenario 3: Memory Issues\n\n**Symptoms:** High memory usage, GC pauses\n\n**Investigation:**\n```bash\nperf record -p \u003cPID\u003e -g -e 'syscalls:sys_enter_mmap,syscalls:sys_enter_brk' -o mem.data -- sleep 30\n```\n\n**Look for:** Frequent allocations, memory copies\n\n### Scenario 4: Lock Contention\n\n**Symptoms:** Multi-threaded app, not scaling with cores\n\n**Investigation:**\n```bash\nperf record -p \u003cPID\u003e -g -e 'syscalls:sys_enter_futex' -o futex.data -- sleep 30\n```\n\n**Look for:** futex_wait/futex_wake, high futex% in perf report\n\n## Advanced Topics\n\n### Flame Graphs\n\n```bash\n# Generate flame graph\nperf script -i perf.data | stackcollapse-perf.pl | flamegraph.pl \u003e flamegraph.svg\n```\n\n### Instruction-Level Analysis\n\n```bash\n# Record cycles vs instructions\nperf record -p \u003cPID\u003e -g -e cycles,instructions -o ipc.data -- sleep 30\n\n# Analyze IPC\nperf report --stdio -i ipc.data -g none\n```\n\n### Cache Analysis\n\n```bash\n# Record cache misses\nperf record -p \u003cPID\u003e -g -e cache-misses,cache-references -o cache.data -- sleep 15\n\n# Analyze cache efficiency\nperf report --stdio -i cache.data -g none\n```\n\n## Contributing\n\nThese skills are based on real-world performance analysis experience, particularly from the AstraDB project. Contributions, corrections, and improvements are welcome.\n\n## Publishing to Skill Marketplaces\n\n### Option 1: Claude Code Plugin Marketplace\n\nCreate a `marketplace.json` in a new branch and submit to marketplaces like:\n\n- **SkillsMP** (https://www.skillsmp.com/) - Open skill marketplace\n- **Claude Market** (https://github.com/claude-market/marketplace) - Community marketplace\n\n### Option 2: Direct GitHub Distribution\n\nUsers can install directly from GitHub:\n\n```bash\n# For Claude Code\n/plugin marketplace add caomengxuan666/perf-skills\n\n# For OpenCode - copy skill to project\ncp -r perf-skills/.claude/skills/linux-perf your-project/.claude/skills/\n```\n\n### Option 3: Git Submodule\n\nAdd as a submodule in any project:\n\n```bash\ngit submodule add https://github.com/caomengxuan666/perf-skills.git .claude/skills/linux-perf\n```\n\n## License\n\nThis skills package is provided as-is for educational and commercial use.\n\n## Acknowledgments\n\n- Inspired by the AstraDB project and the perf-skills project (https://github.com/QAInsights/perf-skills)\n- Based on real-world Linux performance analysis experience\n- Community best practices\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaomengxuan666%2Fperf-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaomengxuan666%2Fperf-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaomengxuan666%2Fperf-skills/lists"}