Create Your Own AI Coding Skills: A Guide to the MiniMax Skills Structure

Mar 27, 2026

I use AI coding assistants for my projects, but sometimes I find myself repeating the same instructions. I want the AI to follow my team’s conventions, use specific libraries, or apply domain-specific patterns consistently.

Generic AI assistance works for common tasks, but for specialized work—like my company’s internal frameworks or niche technologies—I need custom guidance that persists across sessions.

The Solution: Custom Skills for AI Agents

MiniMax Skills allows me to create custom skills that extend AI coding agents with domain-specific knowledge. A skill is essentially a structured guide that the AI loads when triggered.

Generic AI Assistant + Custom Skill = Domain Expert

Before: "I think you should use..."
After:  "According to the skill pattern..."

Skill Directory Structure

A skill has a simple structure:

skills/
├── my-skill/              # lowercase kebab-case directory name
│   ├── SKILL.md          # Required — entry point with YAML frontmatter
│   ├── references/       # Optional — detailed documentation
│   │   ├── api-guide.md
│   │   └── best-practices.md
│   └── scripts/          # Optional — helper scripts
│       ├── generate.py
│       └── requirements.txt  # Required if scripts/ exists

The SKILL.md file is the only required component. References and scripts are optional.

SKILL.md Frontmatter

The YAML frontmatter defines metadata:

---
name: my-skill                    # Required — must match directory name
description: >                    # Required — what it does and when to trigger
  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                      # Optional — defaults to MIT
metadata:                         # Optional
  version: "1.0"
  category: productivity           # e.g., frontend, mobile, productivity, creative
  sources:
    - Relevant documentation or standards
---

The Description is Critical

The description tells the AI agent when to activate your skill. This is the most important field.

# Good: Clear trigger conditions
description: |
  React Native and Expo development guide covering components, styling, animations.
  Use when: building React Native or Expo apps, implementing animations,
  managing state, fetching data, optimizing performance.

# Bad: Vague, no triggers
description: A guide for React Native development.

Without clear triggers, the AI won’t know when your skill is relevant.

A Minimal Complete Example

Here’s a complete minimal SKILL.md:

---
name: date-formatter
description: |
  Format dates and times across multiple locales and formats.
  Use when: formatting dates, parsing date strings, converting timezones.
license: MIT
metadata:
  version: "1.0"
  category: productivity
---

# Date Formatter

Format dates according to ISO 8601, locale-specific formats, and custom patterns.

## Usage

```javascript
formatDate(new Date(), 'YYYY-MM-DD'); // 2024-01-15
formatDate(new Date(), 'en-US');      // January 15, 2024

## Adding Scripts with Error Handling

If your skill includes scripts, handle missing configuration gracefully:

```python title="script-template.py"
#!/usr/bin/env python3
"""Generate a formatted document."""

import sys
import os

def main():
    api_key = os.getenv("MY_API_KEY")
    if not api_key:
        print("ERROR: MY_API_KEY environment variable is not set", file=sys.stderr)
        print("  export MY_API_KEY='your-key-here'", file=sys.stderr)
        sys.exit(1)

    # Rest of script...

if __name__ == "__main__":
    main()

Include a requirements.txt:

requests>=2.28.0
click>=8.0.0

PR Requirements

When contributing to MiniMax Skills:

Title Format

Use Conventional Commits:

feat(my-skill): add new skill for X
fix(my-skill): fix YAML parsing error
docs: update README skill table

PR Description Must Include

What — what you added or changed
Why — the motivation or use case

One PR, One Purpose

Add a new skill
Fix a bug
Improve an existing skill

Don’t mix multiple purposes in one PR.

Validation

Run the validation script locally before submitting:

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

This catches common issues like name mismatches or missing required fields.

Common Mistakes to Avoid

Mistake	Problem	Fix
Name mismatch	Directory ≠ frontmatter name	Ensure both match exactly
Missing triggers	AI doesn’t know when to use	Add “Use when:” conditions
Hardcoded secrets	Security risk	Use environment variables
Missing requirements.txt	Scripts fail to run	Add dependencies file
Large files	Context window bloat	Split into multiple files

File Size Awareness

Skills load into the AI agent’s context window. Keep them focused:

Split large references into parts
Avoid embedding large data blobs
Prefer linking over inlining

A bloated skill reduces the AI’s capacity for actual work.

Updating the README

When adding a skill, update the skill table in README.md:

| `my-skill` | Brief description of what it does | Community |

This helps users discover your skill.

Summary

In this post, I explained how to create custom skills for AI coding agents. The key points are: a skill requires only a SKILL.md with YAML frontmatter, the description must include trigger conditions, scripts need proper error handling and requirements.txt, PRs should follow the conventional commit format, and skills should be focused to avoid context window bloat.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 MiniMax Skills Contributing Guide
👨‍💻 MiniMax Skills GitHub Repository

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!