149 lines
5.4 KiB
Markdown
149 lines
5.4 KiB
Markdown
# 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(<skill-name>): add new skill for X
|
|
fix(<skill-name>): 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-name>/
|
|
├── 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`
|
|
- Markdown content may be in English, Chinese, or bilingual — match the target audience of your skill
|
|
- 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.
|