SupaViber

Your personal vibe coding toolkit - custom skills, agents, and commands for an optimized development environment

SupaViber is a Claude Code plugin that helps you manage and share your custom development workflows, automation, and AI-powered tools. Build your ideal coding environment with reusable components.

What is SupaViber?

SupaViber provides a structured way to organize and share:

• Skills - AI workflows that Claude automatically uses based on context
• Agents - Specialized subagents for specific tasks
• Commands - User-invoked slash commands for common operations
• Hooks - Event-driven automation that runs automatically

Whether you're setting up a new machine or sharing your workflows with a team, SupaViber makes it easy to package and deploy your development environment.

Dual Compatibility: Claude Code + OpenAI Codex

SupaViber skills follow the Agent Skills open standard, making them fully compatible with both:

• Claude Code - Anthropic's AI coding assistant
• OpenAI Codex - OpenAI's developer CLI

Write skills once, use them everywhere. All SupaViber skills are validated against the agent skills specification to ensure cross-platform compatibility.

Using SupaViber with Codex

In OpenAI Codex, skills can be:

• User-scoped: ~/.codex/skills/ (available globally)
• Repo-scoped: .codex/skills/ (project-specific)

Install all skills for Codex:

# Link skills (recommended - stays in sync)
mkdir -p ~/.codex/skills
for skill in /path/to/supaviber/skills/*/; do
  skill_name=$(basename "$skill")
  if [ -f "$skill/SKILL.md" ]; then
    ln -s "$skill" ~/.codex/skills/"$skill_name"
  fi
done

# Or copy skills
cp -r /path/to/supaviber/skills/* ~/.codex/skills/

Codex will automatically discover and use these skills based on context.

Included Skills

SupaViber comes with built-in skills ready to use:

Git Safety

git-safety - Comprehensive git safety protocols for collaborative environments

✓ Compatible with Claude Code and OpenAI Codex

• 🛡️ Prevents destructive operations (hard resets, force pushes) without explicit approval
• 🚫 Protects environment files (.env) from accidental modification
• ⚠️ Enforces safe commit practices with verification checklists
• 🤝 Coordinates file deletions and changes in team environments
• ✅ Ensures explicit file paths and atomic commits

Claude automatically applies these safety protocols when working with git commands and file operations.

Coding Standards

coding-standards - Guide for writing clean, maintainable code following industry best practices

✓ Compatible with Claude Code and OpenAI Codex

• 🎯 Applies SOLID principles and design patterns (DRY, composition over inheritance)
• 📏 Enforces single responsibility and clear function boundaries
• 🏗️ Promotes testable, extensible code architecture
• 📝 Ensures meaningful naming conventions and documentation
• ✨ Includes self-review checklist and refactoring guidance
• 🌐 Language-specific best practices for Python, TypeScript, Java, Go, Rust

Claude uses this skill when writing or reviewing code to ensure consistency, readability, and long-term maintainability.

Installation

Install from Marketplace (Recommended)

Add the SupaViber marketplace and install the plugin:

/plugin marketplace add yzlin/supaviber
/plugin install supaviber@supaviber-marketplace

Install from GitHub

Direct installation without marketplace:

claude plugin install https://github.com/yzlin/supaviber

Install Locally

Clone this repository and load it as a local plugin:

git clone https://github.com/yzlin/supaviber.git
claude --plugin-dir ./supaviber

Verify Installation

Check that the plugin is loaded:

claude plugin list

You should see supaviber in the list of active plugins.

Quick Start

1. Add Your First Skill

Create a new skill directory with a SKILL.md file:

mkdir -p skills/my-workflow

Create skills/my-workflow/SKILL.md:

---
name: my-workflow
description: Describe when Claude should use this skill
---

Your skill instructions here...

2. Create a Slash Command

Add a command file to commands/:

echo "---
description: Example command
---

Do something useful!" > commands/example.md

Use it with: /supaviber:example

3. Define a Custom Agent

Create agents/my-agent.md:

---
description: Specialized agent for X
capabilities: ["capability1", "capability2"]
---

# My Agent

This agent specializes in...

Components

Skills (skills/)

Agent Skills that Claude automatically invokes based on task context. Each skill is a subdirectory containing a SKILL.md file.

Structure:

skills/
└── skill-name/
    ├── SKILL.md       # Required: skill definition
    └── reference.md   # Optional: additional context

See skills/README.md for detailed documentation.

Agents (agents/)

Custom subagents with specialized capabilities. Each agent is defined in a markdown file.

Structure:

agents/
└── agent-name.md

See agents/README.md for detailed documentation.

Commands (commands/)

User-invoked slash commands. Filename becomes the command name (prefixed with supaviber:).

Structure:

commands/
└── command-name.md    # Creates /supaviber:command-name

See commands/README.md for detailed documentation.

Hooks (hooks/)

Event-driven automation that triggers on Claude Code events like file changes, session start, etc.

Structure:

hooks/
└── hooks.json         # Hook configuration

See hooks/README.md for detailed documentation.

Development

Adding Components

1. Skills: Create a directory in skills/ with a SKILL.md file
2. Agents: Add a .md file to agents/
3. Commands: Add a .md file to commands/
4. Hooks: Edit hooks/hooks.json or create individual hook files

Testing Locally

Load the plugin in development mode:

cd supaviber
claude --plugin-dir .

Validating Skills

Ensure skills comply with the agent skills specification:

# Install dependencies (one-time)
uv sync

# Validate all skills
./scripts/validate-skills.sh

# Validate a specific skill
uv run skills-ref validate ./skills/git-safety

All skills are automatically validated against the Agent Skills specification to ensure cross-platform compatibility.

Project Structure

supaviber/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── skills/                   # Agent Skills
├── agents/                   # Custom subagents
├── commands/                 # Slash commands
├── hooks/                    # Event automation
├── scripts/                  # Utility scripts
├── README.md                 # This file
├── CHANGELOG.md              # Version history
├── LICENSE                   # MIT license
└── .gitignore               # Git ignore rules

Contributing

Contributions are welcome! Here's how you can help:

1. Fork this repository
2. Create a feature branch: git checkout -b feat/my-skill
3. Add your skill, agent, or command
4. Test it works: claude --plugin-dir .
5. Commit your changes: git commit -m "feat: add my awesome skill"
6. Push to your fork: git push origin feat/my-skill
7. Submit a pull request

Commit Convention

We use Conventional Commits:

• feat: - New skills, agents, or commands
• fix: - Bug fixes in existing components
• docs: - Documentation updates
• chore: - Maintenance tasks

Examples

Example: Code Review Skill

# skills/code-review/SKILL.md
---
name: code-review
description: Review code for best practices and potential issues
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage
5. Performance optimizations

Provide specific feedback with line numbers.

Example: Deploy Command

# commands/deploy.md
---
description: Deploy the current project
---

Check the deployment status and run the deployment process.
Provide clear feedback on success or failure.

License

MIT License - see LICENSE file for details.

Links

• Claude Code Documentation
• Plugin Development Guide
• Report Issues

---

Built with vibe ✨