Skip to content

Commit 20a42af

Browse files
committed
Refresh README with hero, skills map and how-it-works images
1 parent c6ee606 commit 20a42af

9 files changed

Lines changed: 205 additions & 137 deletions

File tree

‎README.md‎

Lines changed: 111 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,59 @@
1-
# MCode Stack
1+
<p align="center">
2+
<img src="docs/assets/hero.png" alt="MCode Stack: the workflows and skills the MiniMax Code team uses to build MiniMax Code" width="100%">
3+
</p>
24

3-
[中文](README_ZH.md)
5+
<p align="center">
6+
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
7+
<a href="https://github.com/MiniMax-AI/mcode-stack/actions/workflows/validate.yml"><img alt="validate" src="https://github.com/MiniMax-AI/mcode-stack/actions/workflows/validate.yml/badge.svg"></a>
8+
<a href="stacks/ronny/skills/"><img alt="skills: 15" src="https://img.shields.io/badge/skills-15-ff7a59.svg"></a>
9+
<a href="https://github.com/MiniMax-AI/minimax-code"><img alt="for MiniMax Code" src="https://img.shields.io/badge/for-MiniMax%20Code-5b6cff.svg"></a>
10+
</p>
11+
12+
<p align="center"><b>English</b> · <a href="README_ZH.md">中文</a></p>
413

514
**The workflows and skills the MiniMax Code team uses to build MiniMax Code. Open source, install and use.**
615

716
This is not a prompt collection or a list of "best practices". It is what
817
people on the team actually use every day: how to keep AI-written code at a
918
high bar, how to decide whether a task should go to a subagent, how long to
1019
wait on a long command, how to keep long sessions from going dull, and what
11-
goes into context on every turn. Everything here installs straight into
20+
goes into context on every turn. Each piece is a `SKILL.md` skill or
21+
checklist that installs straight into
1222
[MiniMax Code](https://github.com/MiniMax-AI/minimax-code).
1323

14-
## Why
24+
- [Quick start](#quick-start)
25+
- [What's inside](#whats-inside)
26+
- [How it works](#how-it-works)
27+
- [Articles](#articles)
28+
- [Stacks](#stacks)
29+
- [Contribute your own stack](#contribute-your-own-stack)
1530

16-
AI writes code faster every month. What separates results now is the layer
17-
of engineering habits around the agent: when to make it stop and check its
18-
own work, who reviews, where state lives, what counts as a real experiment.
19-
Those habits are hard to follow from an article, so we turned them into
20-
skills and checklists. They pair one to one with our *MCode Engineering
21-
Notes* column: the article explains the idea, this repository makes it
22-
runnable.
31+
## Quick start
2332

24-
We also believe harness engineering is a craft that moves forward by
25-
experiment. Everything here will keep changing as we learn. Take it, change
26-
it, and send your version back.
33+
**One skill, for all your projects:**
2734

28-
## What's inside
29-
30-
```text
31-
stacks/ronny/ Ronny's stack (MiniMax Code R&D lead), the first and most complete one
32-
stacks/<name>/ Other team members' stacks (on the way)
33-
notes/ Which runnable piece goes with each Engineering Notes article
34-
community/ Stacks contributed by developers outside the team
35-
templates/stack-template/ Start here to write your own stack
35+
```bash
36+
git clone https://github.com/MiniMax-AI/mcode-stack.git ~/mcode-stack
37+
mkdir -p ~/.agents/skills
38+
cp -R ~/mcode-stack/stacks/ronny/skills/long-command-check ~/.agents/skills/
3639
```
3740

38-
A stack usually has three kinds of things:
39-
40-
| Kind | What it is | How to use it |
41-
| --- | --- | --- |
42-
| Skill | A directory with a `SKILL.md` | Invoke it in MiniMax Code with `/<skill-name>`, or let the agent load it from its description |
43-
| Checklist | Also a skill: the agent walks your project item by item. A plain-text copy lives in `checklists/` | Same as above, or just read it |
44-
| Workflow | A `WORKFLOW.md` describing how this person works with MiniMax Code every day | Read it |
41+
Open a new session and type `/skills` in MiniMax Code to see it. Run it with
42+
`/long-command-check`, or let the agent load it from its description.
4543

46-
### First batch in `stacks/ronny`
47-
48-
| Skill | What it does | Notes |
49-
| --- | --- | --- |
50-
| `independent-review` | Review a diff from a clean context: only diff, requirement and test results | 01 |
51-
| `subagent-split-check` | Decide whether work goes to a subagent or stays in the main loop | 01 |
52-
| `harness-experiment` | Small eval, one change at a time, repeated runs, look at flipped tasks | 01, 02, 06 |
53-
| `tool-budget-audit` | Measure what tools cost in context; trim, tool search or programmatic tool calling | 02 |
54-
| `long-session-check` | Drop, summarize or write to file; compact or start fresh; memory scoping | 03 |
55-
| `handoff-doc` | A hand-off doc so a new session can pick up the work | 01, 03 |
56-
| `long-command-check` | Ten-point audit of long shell commands and background tasks | 04 |
57-
| `context-tax-audit` | What gets injected into every request, and what it does to the prompt cache | 06 |
58-
| `trajectory-review` | Look at how the agent got its result, not only whether it passed | - |
59-
| `engineering-code-review` | Review a change for code health: design, functionality, complexity, tests, approval risk | - |
60-
| `engineering-review-comments` | Write clear, severity-labeled review comments that explain the reasoning | - |
61-
| `engineering-review-feedback` | Handle reviewer comments as the author: fix, clarify, resolve disagreements | - |
62-
| `engineering-small-prs` | Split large features, refactors and migrations into small reviewable PRs | - |
63-
| `engineering-change-descriptions` | Write PR and commit descriptions that say what changed and why | - |
64-
| `engineering-emergency-changes` | Decide whether a hotfix is a real emergency and run expedited review safely | - |
65-
66-
## Install
67-
68-
Clone the repository first:
44+
**The whole stack, as a plugin:**
6945

7046
```bash
71-
git clone https://github.com/MiniMax-AI/mcode-stack.git ~/mcode-stack
47+
mcode plugin marketplace list # shows your local plugin directory
7248
```
7349

74-
### Install a single skill
50+
Copy the whole `stacks/ronny` directory into that directory, then open
51+
`/plugins` in MiniMax Code and press `Ctrl+R` to refresh. A local plugin is
52+
installed as soon as it is in that directory; press Space in the panel to
53+
enable or disable it.
54+
55+
<details>
56+
<summary>More install options</summary>
7557

7658
MiniMax Code discovers skills in these directories (one subdirectory per
7759
skill, containing `SKILL.md`):
@@ -81,34 +63,86 @@ skill, containing `SKILL.md`):
8163
- For all projects: `~/.agents/skills/` (`~/.claude/skills/` and
8264
`~/.codex/skills/` are read too)
8365

84-
For example, to install the long-command checklist globally:
85-
86-
```bash
87-
mkdir -p ~/.agents/skills
88-
cp -R ~/mcode-stack/stacks/ronny/skills/long-command-check ~/.agents/skills/
89-
```
90-
91-
Open a new session and type `/skills` in MiniMax Code to see it.
66+
`mcode plugin add` installs from the official catalog only; it does not take
67+
a GitHub URL or a local path.
9268

9369
The skills use the common `SKILL.md` format, so most of them also work in
9470
other agents that support skills.
9571

96-
### Install a whole stack as a plugin
72+
</details>
9773

98-
Every stack is also a MiniMax Code plugin package. Find your local plugin
99-
directory:
74+
## What's inside
10075

101-
```bash
102-
mcode plugin marketplace list
103-
```
76+
<p align="center">
77+
<img src="docs/assets/skills-map.png" alt="The 15 skills in stacks/ronny, grouped by moment in the day" width="100%">
78+
</p>
10479

105-
Copy the whole `stacks/ronny` directory into that directory, then open
106-
`/plugins` in MiniMax Code and press `Ctrl+R` to refresh. A local plugin is
107-
installed as soon as it is in that directory; press Space in the panel to
108-
enable or disable it.
80+
| When | Skill | What it does |
81+
| --- | --- | --- |
82+
| Plan & split | [`subagent-split-check`](stacks/ronny/skills/subagent-split-check/SKILL.md) | Decide whether work goes to a subagent or stays in the main loop |
83+
| | [`engineering-small-prs`](stacks/ronny/skills/engineering-small-prs/SKILL.md) | Split large features, refactors and migrations into small reviewable PRs |
84+
| | [`engineering-change-descriptions`](stacks/ronny/skills/engineering-change-descriptions/SKILL.md) | Write PR and commit descriptions that say what changed and why |
85+
| Context & tools | [`tool-budget-audit`](stacks/ronny/skills/tool-budget-audit/SKILL.md) | Measure what tools cost in context; trim, tool search or programmatic tool calling |
86+
| | [`context-tax-audit`](stacks/ronny/skills/context-tax-audit/SKILL.md) | What gets injected into every request, and what it does to the prompt cache |
87+
| Long sessions & commands | [`long-session-check`](stacks/ronny/skills/long-session-check/SKILL.md) | Drop, summarize or write to file; compact or start fresh; memory scoping |
88+
| | [`handoff-doc`](stacks/ronny/skills/handoff-doc/SKILL.md) | A hand-off doc so a new session can pick up the work |
89+
| | [`long-command-check`](stacks/ronny/skills/long-command-check/SKILL.md) | Ten-point audit of long shell commands and background tasks |
90+
| Review | [`independent-review`](stacks/ronny/skills/independent-review/SKILL.md) | Review a diff from a clean context: only diff, requirement and test results |
91+
| | [`engineering-code-review`](stacks/ronny/skills/engineering-code-review/SKILL.md) | Review a change for code health: design, functionality, complexity, tests, approval risk |
92+
| | [`engineering-review-comments`](stacks/ronny/skills/engineering-review-comments/SKILL.md) | Write clear, severity-labeled review comments that explain the reasoning |
93+
| | [`engineering-review-feedback`](stacks/ronny/skills/engineering-review-feedback/SKILL.md) | Handle reviewer comments as the author: fix, clarify, resolve disagreements |
94+
| Experiments & hotfixes | [`harness-experiment`](stacks/ronny/skills/harness-experiment/SKILL.md) | Small eval, one change at a time, repeated runs, look at flipped tasks |
95+
| | [`trajectory-review`](stacks/ronny/skills/trajectory-review/SKILL.md) | Look at how the agent got its result, not only whether it passed |
96+
| | [`engineering-emergency-changes`](stacks/ronny/skills/engineering-emergency-changes/SKILL.md) | Decide whether a hotfix is a real emergency and run expedited review safely |
10997

110-
`mcode plugin add` installs from the official catalog only; it does not take
111-
a GitHub URL or a local path.
98+
A stack usually has three kinds of things:
99+
100+
| Kind | What it is | How to use it |
101+
| --- | --- | --- |
102+
| Skill | A directory with a `SKILL.md` | Invoke it in MiniMax Code with `/<skill-name>`, or let the agent load it from its description |
103+
| Checklist | Also a skill: the agent walks your project item by item. A plain-text copy lives in `checklists/` | Same as above, or just read it |
104+
| Workflow | A `WORKFLOW.md` describing how this person works with MiniMax Code every day | Read it |
105+
106+
## How it works
107+
108+
<p align="center">
109+
<img src="docs/assets/how-it-works.png" alt="From an Engineering Notes article to a skill, installed into MiniMax Code and run on your project" width="100%">
110+
</p>
111+
112+
AI writes code faster every month. What separates results now is the layer
113+
of engineering habits around the agent: when to make it stop and check its
114+
own work, who reviews, where state lives, what counts as a real experiment.
115+
Those habits are hard to follow from an article, so we turned them into
116+
skills and checklists. They pair with our *MCode Engineering Notes* column:
117+
the article explains the idea, this repository makes it runnable.
118+
119+
We also believe harness engineering is a craft that moves forward by
120+
experiment. Everything here will keep changing as we learn. Take it, change
121+
it, and send your version back.
122+
123+
## Articles
124+
125+
| # | MCode Engineering Notes | Companion skills |
126+
| --- | --- | --- |
127+
| 01 | [More subagents isn't better: manage context first, then parallelize](notes/01-subagent.md) | `independent-review`, `subagent-split-check`, `harness-experiment` |
128+
| 02 | [Too many tools will eat your context: from tool search to PTC](notes/02-tool-context.md) | `tool-budget-audit` |
129+
| 03 | [Keeping long sessions sharp: compaction vs. memory](notes/03-compaction-memory.md) | `long-session-check`, `handoff-doc` |
130+
| 04 | [How long should one bash command wait: from foreground blocking to background tasks](notes/04-bash-background.md) | `long-command-check` |
131+
| 06 | [The hidden tax on every turn: what an agent puts into context](notes/06-context-tax.md) *(upcoming)* | `context-tax-audit` |
132+
133+
## Stacks
134+
135+
```text
136+
stacks/ronny/ Ronny's stack (MiniMax Code R&D lead), the first and most complete one
137+
stacks/<name>/ Other team members' stacks (on the way)
138+
notes/ Which runnable piece goes with each Engineering Notes article
139+
community/ Stacks contributed by developers outside the team
140+
templates/stack-template/ Start here to write your own stack
141+
```
142+
143+
Every stack is also a MiniMax Code plugin package. See
144+
[`stacks/ronny`](stacks/ronny/) for its skills, checklists and
145+
[`WORKFLOW.md`](stacks/ronny/WORKFLOW.md).
112146

113147
## Contribute your own stack
114148

@@ -133,4 +167,6 @@ repository only holds workflows and skills, no MiniMax Code source code.
133167

134168
## License
135169

136-
[MIT](LICENSE)
170+
[MIT](LICENSE). The six `engineering-*` skills are adapted from Google
171+
Engineering Practices (CC-BY 3.0); see
172+
[`stacks/ronny/NOTICE.md`](stacks/ronny/NOTICE.md).

0 commit comments

Comments
 (0)