Create and Refine a MiniMax Code Skill

Last checked and updated: August 25, 2026

This lesson was checked against the MiniMax Code v3.0.67 skill-creator and skill-refiner bundles.

Do not turn a vague ambition into a skill. First complete the job manually, record the decisions that mattered, and run it again on a different input. Only then do you know what should be reusable.

The dependable loop is:

Manual run → second example → scope → draft → lint → with-skill vs baseline eval → evidence → minimal refinement

The v3.0.67 bundle deliberately separates two built-in skills:

• skill-creator makes a new skill, checks for overlap, chooses its scope, lints it, and runs an eval.
• skill-refiner changes an existing skill only when concrete evidence shows the instructions are wrong, outdated, or missing a real edge case.

By the end of this lesson, you will design a harmless practice-task-handoff skill and use one failed edge case to make a precise improvement.

What a useful skill contains

A skill needs five parts, even if its file is short:

Part	Question it answers
Trigger	Which user request should activate this workflow?
Boundary	Which nearby request should not activate it?
Procedure	What sequence and decision rules produce the result?
Output contract	What exact artifact or response proves completion?
Failure handling	What happens when evidence, access, or a required input is missing?

Long background material belongs in references loaded only when needed. Deterministic repeated work may justify a script. A skill does not need a README, changelog, installer, environment file, empty folders, or a pile of examples by default.

Step-by-step scenario: prove a workflow, then encode it

Step 1: prove the workflow manually

Our scenario is a handoff report for a completed practice task. It must include:

1. requested outcome;
2. changed paths;
3. checks actually run and their evidence;
4. known limits;
5. rollback method.

Run the workflow manually on one completed practice task:

Create a handoff report for this completed practice task.

Use only the current conversation, visible Changes panel, and actual check output.
Return Outcome, Changed paths, Checks, Limits, and Rollback.
Do not mark a check passed unless its output is present.
Do not run new commands, edit files, commit, push, deploy, or invent a rollback.
If evidence is missing, label the item "not verified."

Read the result and note what required judgment. Then run the same manual prompt on a second task with different files. If the process changes completely, you do not yet have one stable workflow.

Manual success checklist

• Output uses the five named sections.
• Changed paths match the visible diff.
• A test is “passed” only when output supports it.
• Missing evidence is explicit.
• Rollback is appropriate to the actual state; it is not a destructive guess.

Step 2: choose where the skill belongs

The audited skill-creator uses this scope test:

1. If the answer or procedure changes for a different user, choose a user skill.
2. If it holds across projects for one Agent, choose an Agent skill.
3. If it is meaningful only in the current repository, choose a project skill.

The corresponding locations in the current bundle are:

User:    [MiniMax data directory]/skills/<skill-name>/
Agent:   [MiniMax data directory]/agents/<agent-name>/skills/<skill-name>/
Project: <repository>/.minimax/skills/<skill-name>/

For this exercise, choose a user skill because the reporting preference is yours and can follow you across small practice tasks. Name it by responsibility: practice-task-handoff.

Do not put a team-wide project convention only in a personal skill. If everyone must follow it, keep the authoritative rule in version-controlled project documentation and let the skill point to it.

Step 3: ask skill-creator to build and test it

The creation request should include goal, triggers, boundaries, and a success bar. Use this copyable creator prompt:

Use the skill-creator skill to create a new user-scoped skill named
practice-task-handoff.

Goal
Turn evidence from a completed local practice task into a compact handoff report.

Triggers
Use when I ask for a task handoff, completion evidence log, or checked task summary.

Boundaries
Do not use for doing the task, reviewing code for defects, committing, pushing,
deploying, or writing a general project status report. Do not run extra checks unless
the request separately authorizes them.

Output contract
Return Outcome, Changed paths, Checks, Limits, and Rollback. For each check, include
the command or observation and its result. Label missing evidence "not verified."
Never infer a passed check from the Agent's claim alone.

Creation requirements
1. Check the current skill catalog for an overlap before creating anything.
2. Show the proposed scope and concise SKILL.md design.
3. Do not include secrets, fixed project paths, current logs, or one-off task facts.
4. Use the platform-specific workflow for this computer.
5. Lint the skill.
6. Evaluate one real prompt with the skill and the same prompt without it.
7. Report whether the skill is better, equal, mixed, or worse, with evidence.
8. Stop if an existing skill already owns this exact job.

The creator should check the currently available skills first. code-review is nearby, but it finds defects; it does not produce a general completion handoff. That distinction should appear in the new skill’s boundary.

Step 4: understand the eval

The current creator workflow compares two runs on the same real prompt:

• with-skill: the producer loads the new skill;
• baseline: another worker answers without the skill.

The comparison should judge:

1. whether the skill is actually better;
2. which procedure or output-contract rule made the difference;
3. why it is equal or worse if no gain appears;
4. three to five concrete improvements;
5. whether a deterministic script would help or merely add complexity.

A passing eval does not mean “the skill won every stylistic preference.” The minimum bar in the audited creator is that at least one evaluation round shows the skill is not worse than baseline without a major regression. If it adds twice the work for no quality gain, delete or simplify it.

Use this eval prompt:

Create a handoff report from this supplied evidence:

Outcome requested: Change README status from draft to reviewed.
Visible changed paths: README.md
Conversation claim: "npm test passed."
Available command output: none
Preview observation: README heading and status render correctly.
Known limit: No automated test output was captured.
Rollback evidence: Revert the one-line README change in the Changes panel.

Do not run commands or edit files. Distinguish claims from verified evidence.

This prompt contains a trap: a conversation says the test passed, but no output proves it. A useful skill must label that check not verified.

Step 5: refine only what the evidence supports

Suppose the with-skill run writes npm test — passed. That is concrete evidence of a skill problem only if the skill’s own instructions allowed the mistake. If the skill already clearly says that unsupported checks are not verified and the Agent ignored it, that is an Agent execution error; do not keep bloating the skill.

If the output contract is genuinely ambiguous, invoke skill-refiner:

Use skill-refiner on practice-task-handoff.

Problem
The eval marked "npm test" as passed even though the only evidence was a
conversation claim and no command output existed.

Evidence
Eval prompt: "Conversation claim: npm test passed. Available command output: none."
With-skill output: "npm test — passed."

Requested minimal correction
Require every check to be labeled verified, reported-only, or not run.
"Verified" requires command output or a named direct observation available to the task.
Do not rewrite unrelated sections or add generic safety prose.

Before editing, confirm whether the fault is in the skill text or the Agent's execution.
If it is the skill, show problem, evidence, rationale, and the minimal patch.
Re-read the skill after applying the patch and rerun the failing eval case.

The refiner should preserve frontmatter, stay below its size limit, avoid secrets, and make the smallest evidence-backed change. Its bundle explicitly rejects style-only revisions and self-modification.

Step 6: run an edge case and a regression case

After refinement, run two tests:

Test	Input	Passing behavior
Edge case	A check is claimed but has no output	Labels it reported-only or not verified, never passed
Regression	A real command output shows success	Labels it verified and names the evidence without hiding it

Also run a trigger test: ask for a normal code review. practice-task-handoff should not activate. Better output on the happy path is not enough if the skill hijacks neighboring tasks.

When to bundle a script

Bundle a script only when the same deterministic operation repeats and code is safer than prose—for example validating that every report has the five required headings. Do not write a script to decide whether evidence is trustworthy; that needs judgment.

The current creator explicitly asks whether a repeated deterministic action appeared in the producer’s process. “A script could exist” is not sufficient justification.

Safety boundary

• Never place credentials, private keys, personal access tokens, cookies, customer data, or temporary private logs inside a skill or its eval artifacts.
• Do not encode approval for sending, publishing, purchasing, deleting, deploying, or account changes. Final actions need current, exact confirmation.
• Evals can run concurrently. Keep their scratch outputs isolated and forbid production files, external actions, and shared mutable targets.
• Do not create overlapping skills merely to change wording. Refine an existing owner when evidence supports it.
• Built-in skill runtime copies are not a beginner editing surface. Propose changes in the source-controlled project/worktree path and review them normally.

Public reports: signals, not prevalence

One user reported local permission-store corruption during concurrent work. This individual report does not establish frequency, and it is not specifically a skill-creator defect. It matters to eval design because creator evals may run workers in parallel: keep them read-only or isolated, stop if permission errors appear, inspect current state, and do not “fix” the problem by granting broader access.

Troubleshooting

Symptom	Likely cause	Recovery
Creator refuses to make the skill	An existing skill already covers the trigger	Use that skill or refine it with concrete evidence; do not create a duplicate
Lint fails repeatedly	Frontmatter, name, links, size, or unnecessary scaffolding is wrong	Simplify the skill and follow the current platform-specific creator route
With-skill output is no better than baseline	The workflow is obvious, too broad, or burdened with instructions	Narrow it, reduce body size, or remove the skill
Skill works only on the original example	Fixed values leaked into the procedure	Replace project names, paths, and outputs with explicit inputs and decision rules
Refiner wants to rewrite the whole skill	The evidence points to one small defect but the request is broad	Restate the exact failure trace and demand the minimal patch plus regression check
Parallel eval hits permission errors	Workers share a mutable runtime or target	Stop, inspect permissions and outputs, isolate targets, and rerun safely rather than widening access

FAQ

How many manual runs should I complete first?

At least two different inputs: one ordinary example and one awkward case. The point is to separate the reusable method from the first task’s values.

Is a good prompt automatically a skill?

No. A skill needs triggers, neighboring exclusions, execution rules, an output contract, failure handling, and evidence that loading it improves or at least does not harm a real run.

Should every skill include scripts?

No. Add a script only for repeated deterministic work. Most workflow judgment belongs in concise instructions.

Can I refine a skill because I prefer different wording?

Not with skill-refiner. Its audited boundary requires a concrete functional problem supported by evidence.

What if the Agent ignored correct skill instructions?

Treat that as an execution failure, not proof that the skill needs more text. Preserve the clean instruction and rerun or diagnose the Agent behavior.

Official sources

• MiniMax-AI Skills repository
• MiniMax Code overview
• Permissions and safety
• Custom Agents
• MiniMax Code changelog

What’s next

Give repeatable work a clear owner—and decide whether it needs one Agent or a team—in L10: Custom Agents and Agent Team.