swarm
Skill1 starsChanged 52 days agoMITView on GitHub
Dispatches many independent items in parallel: create a table, fan out to subagents, aggregate results. One row = one unit of work.
101 other projects use a version of this; 0 new projects in the last 4 weeks, against 1 the 4 before.
Adopted by
Cooling: 0 new projects took it in the last 4 weeks, 0× the 4 weeks before.thin data
Most recently taken up by
- TencentBlueKing/bk-litetheir own version, first seen Nov 16, 2026
- GoBeromsu/craft-skillstheir own version, first seen Nov 16, 2026
- gmunaro/claude-skillstheir own version, first seen Nov 16, 2026
- gfunc/skillstheir own version, first seen Nov 16, 2026
- AlexanderTar/swarmruntheir own version, first seen Nov 16, 2026
- niksavis/handilytheir own version, first seen Nov 16, 2026
Used with
Projects with it also use poteto-help, setup-pstack and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
shiwenbin1617Skillpoteto-help
Guides users through pstack setup, /poteto-mode, and picking the skill, playbook, or principle for a task. Type /poteto-help with a question.
Also in 15 projects that use this
bnemaSkillsetup-pstack
Configure which Pi models pstack uses per role. Detects available provider/model specs and writes pstack's user configuration. Use for /setup-pstack, "configure pstack models", or changing pstack model choices.
Also in 25 projects that use this
shiwenbin1617Skillprinciple-explain-the-number
Apply before you measure, and before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.
Also in 29 projects that use this
eryzerzSkillmake-bot-ui
Use when building a custom UI (page, dashboard, buttons) that should wake a Grok Bot over a webhook, when the user must provide a webhook sender key, or when exposing that UI on Tailscale.
Also in 19 projects that use this
jaydubya818Skillpoteto-mode
Use when non-trivial work should follow the smallest rigorous Jstack workflow.
Also in 29 projects that use this
jaydubya818Skillprinciple-attack-the-premise
Apply when repeated fixes fail and a shared assumption may be wrong.
Also in 34 projects that use this
- +6 more from jaydubya818
Other versions101 projects use a version of this.
Word for word · 3
- langchain-ai/langchain-skills★ 1.3k100% same
- buduan/soul-graph★ 2100% same
- gerald-donkor/poli-intel★ 1100% same
Edited · 0
None found.
Wrote their own version · 98
- backnotprop/pstack★ 4.2ksame name
- moeru-ai/xsai★ 669same name
- zaxbysauce/opencode-swarm★ 532same name
- ZaxbyHub/opencode-swarm★ 531same name
- guaardvark/guaardvark★ 320same name
- iha2/superlite★ 311same name
- apple-ouyang/book-to-skill★ 148same name
- jtaroreh/agystack★ 128same name
- uzairansaruzi/p3-stack★ 126same name
- cj-vana/claude-swarm★ 110same name
88 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- claude-apiSkill
- deep-agents-coreSkill
- deep-agents-memorySkill
- deep-agents-orchestrationSkill
- deepagents-typescript-quickstartSkill
- langchain-dependenciesSkill
- langchain-typescript-quickstartSkill
- langgraph-typescript-quickstartSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 2 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 94 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Aggregate: Use rows() and plain JS to count, filter, or summarize.
- Distinctive: line 26
Do not spawn additional subagents for aggregation.
- Very specific: line 68
When the file is too large to parse and dispatch in one eval call, split across two blocks.
- Very specific: line 204
After run(), use rows() and plain JS — no additional subagents needed.
- Very specific: line 243
When subagents perform actions (write a file, apply a fix) rather than return data, use a simple schema with a status or marker field.
- Distinctive: line 286
Console output is capped at ~5 KB: Never log raw file contents — log only counts and short samples.
- Very specific: line 293
Never write to
.swarm/directly: Always use create(). - Very specific: line 299
Unknown columns fail fast: If instruction references {foo} and no matched row provides foo, run() throws before any subagent is dispatched.
- Very specific: line 307
Create a table. Returns a handle { id, count, columns }.
“Common” is measured: kept by at least 6 in 10 of the 94 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Swarm
Process many independent items in parallel. create builds a table handle;
run fans work out across rows and merges results back. One row = one unit
of work — swarm handles batching automatically.
Flow
- Create. Build a table from a source — files, a glob pattern, or pre-parsed records. One row per item. Returns a handle.
- Run. Dispatch an
instructiontemplate across rows. Results are merged back into the table. Returns{ completed, failed, skipped, failures }. - Aggregate. Use
rows()and plain JS to count, filter, or summarize. Do not spawn additional subagents for aggregation. - Retry. Re-run with
filter: { column: "<col>", exists: false }to reprocess only failed rows.
Choosing a source
glob / filePaths — one file = one row. Use when each file is an
independent unit of work. Each row gets { id, file }; the subagent reads
the file itself via the {file} placeholder.
tasks — pass pre-built records directly. Use when the data lives inside
a file (JSONL, CSV, JSON array). Read and parse the file first inside
eval, then pass the records. One record = one row — do not group
multiple items into a single row.
For small files (under ~500 lines), parse and create in one block:
const { create } = await import("@/skills/swarm");
const raw = await tools.readFile({ file_path: "/data.jsonl" });
const records = raw.trim().split("\n").map(l => JSON.parse(l));
const table = await create({ tasks: records });
console.log(table);For large files, read in chunks of 500 lines to avoid truncation:
const { create } = await import("@/skills/swarm");
let records = [];
let offset = 0;
while (true) {
const chunk = await tools.readFile({ file_path: "/data.txt", offset, limit: 500 });
const lines = chunk.split("\n").filter(l => l.trim());
for (const l of lines) { records.push({ id: `r${records.length}`, text: l }); }
if (lines.length < 500) break;
offset += 500;
}
const table = await create({ tasks: records });
console.log(table);When the file is too large to parse and dispatch in one eval call, split
across two blocks. Only the block that calls swarm functions needs the import:
// eval 1: parse only — no swarm import needed
const raw = await tools.readFile({ file_path: "/data.jsonl" });
globalThis.records = raw.trim().split("\n").map(l => JSON.parse(l));
console.log(`Parsed ${globalThis.records.length} records`);// eval 2: create and dispatch
const { create, run } = await import("@/skills/swarm");
const table = await create({ tasks: globalThis.records });
const result = await run(table.id, {
instruction: "Classify {text}",
responseSchema: {
type: "object",
properties: { label: { type: "string" } },
required: ["label"],
},
});
console.log(result);Passing filePaths: ["/data.jsonl"] would produce a table with one row
pointing at the file — not one row per record inside it.
When to use subagentType
Omit subagentType for classification, extraction, labeling, and any task
where a single model call with structured output is sufficient. This is the
default and is significantly cheaper and faster — each dispatch is a direct
model call, no tools, no iteration.
Set subagentType when the task requires tools, file access, or multi-step
reasoning. Each dispatch runs a full agentic loop with the named subagent.
// Direct model call — classification, no tools needed
await run(table.id, {
instruction: "Classify {text}",
responseSchema: { type: "object", properties: { label: { type: "string" } }, required: ["label"] },
});
// Subagent — needs to read files and reason over multiple steps
await run(table.id, {
subagentType: "reviewer",
instruction: "Review {file} for security issues.",
responseSchema: { type: "object", properties: { finding: { type: "string" } }, required: ["finding"] },
});Instruction + context
instruction is a per-item template with {column} placeholders.
Placeholders are resolved by the framework — your column names appear in
prompts as references to the values listed alongside, never as raw
template syntax. Subagents do the work — do not process items yourself in
JS and write the results into rows.
context is free-form prose prepended to every subagent prompt. Use it for
shared background: domain terms, classification rules, examples, etc.
const { create, run } = await import("@/skills/swarm");
const table = await create({ glob: "src/**/*.ts" });
const r = await run(table.id, {
subagentType: "reviewer",
instruction: "Review {file} for security issues. List findings or write 'no issues'.",
context: "TypeScript Express backend using Prisma ORM. Focus on injection, auth bypass, path traversal.",
responseSchema: {
type: "object",
properties: { review: { type: "string" } },
required: ["review"],
},
});
console.log(r);
// → { completed: 45, failed: 2, skipped: 0, failures: [...] }Structured output
responseSchema is required. Schema properties become top-level columns on
each row and constrain what subagents can return.
const { run } = await import("@/skills/swarm");
await run(table.id, {
instruction: "Classify: {text}",
responseSchema: {
type: "object",
properties: {
sentiment: { type: "string", enum: ["positive", "negative", "neutral"] },
},
required: ["sentiment"],
},
});
// Row after: { id: "r1", text: "...", sentiment: "positive" }Batching
By default, swarm auto-batches to keep total dispatches under 10. For small tables (≤10 rows) each row gets its own subagent call. For larger tables, rows are grouped automatically.
Set batchSize to control grouping:
- Number — uniform batch size for all rows.
batchSize: 1forces per-row dispatch;batchSize: 20groups in twenties. - Function —
(row, rowCount) => number. Returns the desired batch size for each row. Rows with the same batch size are grouped together, then chunked. Allows mixed dispatch where some rows go solo and others batch.
const { create, run } = await import("@/skills/swarm");
const table = await create({ tasks: items });
// Complex items get individual attention; simple ones batch together
await run(table.id, {
instruction: "Analyze {text}",
responseSchema: {
type: "object",
properties: { analysis: { type: "string" } },
required: ["analysis"],
},
batchSize: (row) => (row.token_count > 1000 ? 1 : 10),
});Batch sizes are clamped to [1, 50] after evaluation.
Aggregation
After run(), use rows() and plain JS — no additional subagents needed.
const { rows } = await import("@/skills/swarm");
const data = await rows(table.id, { columns: ["sentiment"] });
const counts = {};
data.forEach(r => { counts[r.sentiment] = (counts[r.sentiment] || 0) + 1 });
console.log(counts);
// → { positive: 120, negative: 45, neutral: 35 }Chaining passes
run updates the table in place — chain calls to accumulate columns.
const { create, run } = await import("@/skills/swarm");
const table = await create({ tasks: interviews });
await run(table.id, {
instruction: "Classify sentiment of {text}",
responseSchema: {
type: "object",
properties: { sentiment: { type: "string", enum: ["positive", "negative", "neutral"] } },
required: ["sentiment"],
},
});
await run(table.id, {
filter: { column: "sentiment", equals: "negative" },
instruction: "Summarize why {text} had negative sentiment.",
responseSchema: {
type: "object",
properties: { summary: { type: "string" } },
required: ["summary"],
},
});Action-only tasks
When subagents perform actions (write a file, apply a fix) rather than return
data, use a simple schema with a status or marker field. The exists: false
filter still works for retries.
const { create, run } = await import("@/skills/swarm");
const fixedSchema = {
type: "object",
properties: { fixed: { type: "string" } },
required: ["fixed"],
};
const table = await create({ glob: "src/**/*.ts" });
await run(table.id, {
subagentType: "fixer",
instruction: "Add missing JSDoc to all exported functions in {file}.",
responseSchema: fixedSchema,
});
// retry any that failed
await run(table.id, {
subagentType: "fixer",
instruction: "Add missing JSDoc to all exported functions in {file}.",
responseSchema: fixedSchema,
filter: { column: "fixed", exists: false },
});Filtering
{ column: "status", equals: "done" }
{ column: "status", notEquals: "done" }
{ column: "category", in: ["A", "B"] }
{ column: "result", exists: false } // not yet processed
{ and: [filter1, filter2] }
{ or: [filter1, filter2] }Technical notes
- Only import
@/skills/swarmin blocks where you call swarm functions. Data preparation (reading files, parsing, storing inglobalThis) does not need the import. Destructure only what you use:{ create },{ run },{ create, run }, etc. - Console output is capped at ~5 KB. Never log raw file contents — log only counts and short samples.
readFileinsideevalreturns raw content — no line-number prefixes. Request at most 500 lines per call. For files with more than 500 lines, loop with incrementingoffset.- When building a table from a file, read it inside
eval. Data read inside the sandbox stays there; it never enters the agent's context window. - Never write to
.swarm/directly. Always usecreate(). - Everything the subagent needs must be in
instruction+context. Subagents can't see the agent's context. - Row ids must be unique.
create()rejects sources that produce duplicate ids. Fortasks, that's a caller-side responsibility; forglob/filePaths, ids are auto-disambiguated by parent directory. - Unknown columns fail fast. If
instructionreferences{foo}and no matched row providesfoo,run()throws before any subagent is dispatched.
API Reference
create(source)
Create a table. Returns a handle { id, count, columns }.
| Source | Description |
{ glob: "src/**/*.ts" } or { glob: ["src/**/*.ts", "lib/**/*.ts"] } | Match files by one or more patterns. Columns: id, file |
{ filePaths: ["a.ts", "b.ts"] } | Explicit file list. Columns: id, file |
{ tasks: [{ id: "t1", text: "..." }] } | Custom rows. Each must have id |
run(tableId, options)
Dispatch work across rows. Returns { completed, failed, skipped, failures }.
| Option | Default | Description |
instruction | (required) | Template with {column} placeholders |
responseSchema | (required) | JSON Schema (type: "object") — properties become row columns |
context | — | Prose prepended to every subagent prompt |
filter | — | Only dispatch matching rows |
subagentType | — | Name of subagent to dispatch to. When set, runs a full agentic loop. When omitted, runs a direct model call |
batchSize | auto | Number or (row, rowCount) => number. Auto caps dispatches at 10; 1 = per-row; function = per-row sizing |
concurrency | 10 | Max concurrent subagent dispatches (clamped to 1–10) |
rows(tableId, options?)
Retrieve rows. Use for inspection and JS-based aggregation.
| Option | Description |
filter | Only return matching rows |
columns | Project to specific columns |
limit | Max rows returned |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

