### CONTRIBUTING # Contributing to MiniMax Skills Thank you for your interest in contributing! This document covers PR requirements, skill structure specifications, and development guidelines. ## Pull Request Requirements ### Title Format Use [Conventional Commits](https://www.conventionalcommits.org/) style: ``` feat(): add new skill for X fix(): fix YAML frontmatter parsing error docs: update README skill table chore: add CI workflow ``` Common prefixes: `feat` (new skill or feature), `fix` (bug fix), `docs` (documentation only), `refactor` (restructure without behavior change), `chore` (tooling, CI, config). ### Scope **One PR, one purpose.** Each PR should do exactly one of: - Add a new skill - Fix a bug in an existing skill - Improve an existing skill Do not bundle unrelated changes together. ### PR Description Every PR must include: 1. **What** — what you added or changed 2. **Why** — the motivation or use case ## Skill Structure ### Directory Layout ``` skills// ├── SKILL.md # Required — entry point with YAML frontmatter ├── references/ # Optional — detailed reference docs │ └── *.md └── scripts/ # Optional — helper scripts ├── *.py └── requirements.txt # Required if scripts/ exists ``` - The directory name is the skill identifier. Use lowercase `kebab-case` (e.g., `gif-sticker-maker`). - `SKILL.md` is the only required file. All other files and directories are optional. ### SKILL.md Frontmatter ```yaml --- name: my-skill # Required — must match directory name description: > # Required — what this skill does and when to trigger it One-paragraph description. Include trigger conditions so the agent knows when to activate this skill (e.g., "Use when the user asks to create, edit, or format Excel files"). license: MIT # Recommended — defaults to MIT if omitted metadata: # Recommended version: "1.0" category: productivity # e.g., frontend, mobile, productivity, creative sources: - Relevant documentation or standards --- ``` **Required fields:** `name`, `description` - `name` must exactly match the directory name - `description` must clearly state trigger conditions — this is what the agent uses to decide whether to load your skill **Recommended fields:** `license`, `metadata` (version, category, sources) ### No Hardcoded Secrets **Never hardcode API keys, tokens, or credentials in any file.** If your skill involves calling an external API, instruct the agent to read credentials from environment variables. Follow the pattern established by existing skills: ```python API_KEY = os.getenv("MINIMAX_API_KEY") if not API_KEY: raise SystemExit("ERROR: MINIMAX_API_KEY is not set.\n export MINIMAX_API_KEY='your-key'") ``` Your `SKILL.md` should document the required environment variables as a prerequisite. See `frontend-dev/references/env-setup.md` for a good example. ### README Sync When adding a new skill, update both `README.md` and `README_zh.md` to include your skill in the skill table. Community-submitted skills should set the Source column to `Community`. ## Guidelines The following are not hard blockers, but PRs that follow these guidelines will be reviewed and merged faster. ### 1. Skill Scope — Avoid Overlap Before creating a new skill, check existing skills for functional overlap. If your feature could be an extension of an existing skill, prefer extending over creating a new one. In your PR description, briefly explain how your skill differs from related existing skills. For example, if you are adding a voice synthesis skill, clarify how it relates to the TTS capabilities already in `frontend-dev`. ### 2. File Size Awareness Skills are loaded into the agent's context window. Every token counts. - Keep individual `.md` files focused and concise - If a reference document grows very large, split it into logical parts (see `minimax-docx/references/openxml_encyclopedia_part{1,2,3}.md` for an example) - Avoid embedding large data blobs (base64 images, full API response dumps) directly in Markdown files - Prefer linking to external resources over inlining lengthy content ### 3. Script Standards If your skill includes helper scripts (typically in a `scripts/` directory): - Include a shebang line (e.g., `#!/usr/bin/env python3`) - Provide a `requirements.txt` listing all dependencies - Handle errors gracefully — fail with a clear message rather than a raw traceback - Document script usage in `SKILL.md` or a reference file ### 4. Language and Encoding - Skill names and file names: ASCII only, `kebab-case` - SKILL.md content and code should be written in English - Reference docs are recommended to be in English - All files must be UTF-8 encoded ## Review Process You can run the validation script locally to check part of the requirements before submitting: ```bash python .claude/skills/pr-review/scripts/validate_skills.py ``` You can also use the [pr-review skill](./.claude/skills/pr-review/SKILL.md) to let your AI coding agent assist with the review. 1. Submit your PR following the requirements above 2. At least one maintainer will review 3. Address review feedback 4. Once approved, a maintainer will merge ## Questions? Open an issue if you have questions about contributing. We're happy to help. --- ### README # MiniMax Skills [中文版](./README_zh.md) > **Beta** — This project is under active development. Skills, APIs, and configuration formats may change without notice. We welcome feedback and contributions. Development skills for AI coding agents. Plug into your favorite AI coding tool and get structured, production-quality guidance for frontend, fullstack, Android, iOS, and shader development. ## Skills | Skill                               | Description | Source | |---------------------------------------|-------------|--------| | `frontend-dev` | Full-stack frontend development combining premium UI design, cinematic animations (Framer Motion, GSAP), AI-generated media assets via MiniMax API (image, video, audio, music, TTS), persuasive copywriting (AIDA framework), and generative art (p5.js, Three.js, Canvas). Tech stack: React / Next.js, Tailwind CSS. | Official | | `fullstack-dev` | Full-stack backend architecture and frontend-backend integration. REST API design, auth flows (JWT, session, OAuth), real-time features (SSE, WebSocket), database integration (SQL / NoSQL), production hardening, and release checklist. Guided workflow: requirements → architecture → implementation. | Official | | `android-native-dev` | Android native application development with Material Design 3. Kotlin / Jetpack Compose, adaptive layouts, Gradle configuration, accessibility (WCAG), build troubleshooting, performance optimization, and motion system. | Official | | `ios-application-dev` | iOS application development guide covering UIKit, SnapKit, and SwiftUI. Touch targets, safe areas, navigation patterns, Dynamic Type, Dark Mode, accessibility, collection views, and Apple HIG compliance. | Official | | `flutter-dev` | Flutter cross-platform development covering widget patterns, Riverpod/Bloc state management, GoRouter navigation, performance optimization, and testing strategies. | Official | | `react-native-dev` | React Native and Expo development guide covering components, styling, animations, navigation, state management, forms, networking, performance optimization, testing, native capabilities, and engineering (project structure, deployment, SDK upgrades, CI/CD). | Official | | `shader-dev` | Comprehensive GLSL shader techniques for creating stunning visual effects — ray marching, SDF modeling, fluid simulation, particle systems, procedural generation, lighting, post-processing, and more. ShaderToy-compatible. | Official | | `gif-sticker-maker` | Convert photos (people, pets, objects, logos) into 4 animated GIF stickers with captions. Funko Pop / Pop Mart style, powered by MiniMax Image & Video Generation API. | Official | | `minimax-pdf` | Generate, fill, and reformat PDF documents with a token-based design system. CREATE polished PDFs from scratch (15 cover styles), FILL existing form fields, or REFORMAT documents into a new design. Print-ready output with typography and color derived from document type. | Official | | `pptx-generator` | Generate, edit, and read PowerPoint presentations. Create from scratch with PptxGenJS (cover, TOC, content, section divider, summary slides), edit existing PPTX via XML workflows, or extract text with markitdown. | Official | | `minimax-xlsx` | Open, create, read, analyze, edit, or validate Excel/spreadsheet files (.xlsx, .xlsm, .csv, .tsv). Covers creating new xlsx from scratch via XML templates, reading and analyzing with pandas, editing existing files with zero format loss, formula recalculation, validation, and professional financial formatting. | Official | | `minimax-docx` | Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: create new documents from scratch, fill/edit content in existing documents, or apply template formatting with XSD validation gate-check. | Official | | `vision-analysis` | Analyze, describe, and extract information from images using vision AI models. Supports describe, OCR, UI mockup review, chart data extraction, and object detection. Powered by MiniMax VL API with OpenAI GPT-4V fallback. | Community | | `minimax-multimodal-toolkit` | Generate voice, music, video, and image content via MiniMax APIs — the unified entry for MiniMax multimodal use cases. Covers TTS (text-to-speech, voice cloning, voice design, multi-segment), music (songs, instrumentals), video (text-to-video, image-to-video, start-end frame, subject reference, templates, long-form multi-scene), image (text-to-image, image-to-image with character reference), and media processing (convert, concat, trim, extract) via FFmpeg. | Official | | `minimax-music-gen` | Generate vocal songs, instrumentals, and covers using MiniMax Music API. Two modes: Basic (one-liner in, song out) and Advanced Control (edit lyrics, refine prompt, plan structure). Supports lyrics generation, style vocabulary, streaming playback, and iterative feedback. | Official | | `buddy-sings` | Let your Claude Code pet (/buddy) sing a personalized song. Interprets the pet's name and personality into a unique cached vocal identity, auto-gathers context (conversation, memory, git history) for themed lyrics, and generates music via minimax-music-gen. | Official | | `minimax-music-playlist` | Generate personalized playlists by analyzing your music taste. Builds a taste profile (genre, mood, language, vocal preferences), plans a themed tracklist, generates songs with album cover art, and refines the profile from feedback. | Official | ## Installation ### Claude Code ```bash claude plugin marketplace add https://github.com/MiniMax-AI/skills claude plugin install minimax-skills ``` ### Cursor ```bash git clone https://github.com/MiniMax-AI/skills.git ~/.cursor/minimax-skills ``` Add to your Cursor settings — point the skills path to `~/.cursor/minimax-skills/skills/`. For Windows setup and verification, see [`.cursor-plugin/INSTALL.md`](.cursor-plugin/INSTALL.md). ### Codex ```bash git clone https://github.com/MiniMax-AI/skills.git ~/.codex/minimax-skills mkdir -p ~/.agents/skills ln -s ~/.codex/minimax-skills/skills ~/.agents/skills/minimax-skills ``` Restart Codex to discover the skills. See [`.codex/INSTALL.md`](.codex/INSTALL.md) for Windows instructions and details. ### OpenCode ```bash git clone https://github.com/MiniMax-AI/skills.git ~/.minimax-skills mkdir -p ~/.config/opencode/skills ln -s ~/.minimax-skills/skills/* ~/.config/opencode/skills/ ``` Restart OpenCode to discover the skills. See [`.opencode/INSTALL.md`](.opencode/INSTALL.md) for details. ### VS Code This repository does not currently ship a standalone VS Code extension. If you use VS Code, the supported approach is to run one of the supported CLI tools inside the integrated terminal: - Codex - Claude Code - OpenCode If you want native local-skills configuration from this repo, use Cursor and follow [`.cursor-plugin/INSTALL.md`](.cursor-plugin/INSTALL.md). ## Contributing We welcome contributions! Before submitting a PR, please read: - [CONTRIBUTING.md](./CONTRIBUTING.md) — PR format, skill structure requirements, and development guidelines - [PR Review Rules](./.claude/skills/pr-review/SKILL.md) — automated validation checks and quality review criteria You can run the validation script locally before submitting: ```bash python .claude/skills/pr-review/scripts/validate_skills.py ``` ## ⭐ Star History [](https://star-history.com/#MiniMax-AI/skills&Date) ## Credits Some skills in this repository are inspired by or derived from work by the open-source community. See [CREDITS.md](./CREDITS.md) for full acknowledgments. ## License [MIT](./LICENSE) ---