Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
149 lines (100 loc) · 5.36 KB

CONTRIBUTING.md

File metadata and controls

149 lines (100 loc) · 5.36 KB

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 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

---
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:

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:

python .claude/skills/pr-review/scripts/validate_skills.py

You can also use the pr-review skill 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.