playbooks

home / skills / bdambrosio / cognitive_workbench / split

split skill

/src/primitives/split

This skill transforms a Note into a Collection by splitting JSON arrays or plain text into individual notes for better organization.

npx playbooks add skill bdambrosio/cognitive_workbench --skill split

Review the files below or copy the command above to add this skill to your agents.

Files (1)
Skill.md
1.4 KB
---
name: split
type: primitive
description: Transform Note structure into Collection
---

# Split

## INPUT CONTRACT

- `target`: Note (variable or ID)
- `out`: Variable name
- `field`: Optional string (default `"results"`) — for JSON objects with array field
- `delimiter`: Optional string (default `"sentence"`) — for plain text: `"sentence"`, `"paragraph"`, `"line"`, or custom

**REQUIREMENTS:**
- `target` MUST be Note (not Collection)
- Note content MUST be: JSON array, JSON object with array field, JSONL, or plain text

**NOT SUPPORTED:**
- ❌ Collection (Collections already split)
- ❌ Invalid JSON structure

## OUTPUT

Returns Collection of Notes, one per element/segment. Empty segments filtered out.

## FAILURE SEMANTICS

**Returns `failed` when:**
- Target is Collection (not Note)
- Invalid JSON structure
- No items to split

**Empty Collection ≠ error** — indicates no splittable content, not failure.

## REPRESENTATION INVARIANTS

- Note containing JSON array ≠ Collection
- `split` converts: array → Collection, text → Collection
- `flatten` performs inverse (Collection → Note)
- search-web/semantic-scholar return Collections directly — NO split needed

## ANTI-PATTERNS

❌ `split(target=$collection)` → Collections already split, use `display` to view
❌ `split(target=$search_results)` → search-web returns Collections, not Notes
❌ Splitting Collection to "see inside" → Use `display` or `flatten` instead

Overview

This skill transforms a single Note into a Collection by splitting its content into individual Notes. It supports JSON arrays, JSON objects with an array field, JSONL, and plain text segmented by sentence, paragraph, line, or a custom delimiter. The result is a Collection of Notes, one per element or segment, with empty segments filtered out.

How this skill works

You provide a Note (variable or ID) as the target and an output variable name. For JSON objects, specify the array field name; for plain text choose a delimiter mode (sentence, paragraph, line, or custom string). The skill parses the Note, extracts elements or segments, creates one Note per item, and returns those Notes as a Collection. It validates input and returns a failure state for unsupported shapes or when no items can be split.

When to use it

  • You have a Note containing a JSON array and need each element as an individual Note.
  • A Note stores JSONL (newline-delimited JSON) and you want one Note per JSON line.
  • You have a long text Note and want to split it into sentences, paragraphs, or lines for processing.
  • A JSON object Note contains an array under a specific field and you need to operate on each element separately.
  • You need to convert a single aggregated Note into a Collection for batch processing or parallel workflows.

Best practices

  • Ensure the target is a Note, not already a Collection; splitting a Collection is unnecessary.
  • Validate the Note content format before calling split to avoid JSON structure errors.
  • Use the field parameter only for JSON objects that contain the desired array.
  • Prefer sentence/paragraph/line modes for plain text; use a custom delimiter when text uses a specific separator.
  • Handle the failed return state: check for invalid JSON, wrong target type, or no splittable items.

Example use cases

  • Turn a Note containing ['a','b','c'] into a Collection of three Notes for parallel annotation.
  • Split JSONL logs stored in a Note into individual Notes for line-by-line analysis.
  • Break a long research Note into paragraphs so each paragraph can be summarized separately.
  • Extract items from a JSON object field (e.g., comments array) into individual Notes for moderation.
  • Split a transcript Note into sentences for sentence-level NLP pipelines.

FAQ

What input formats are supported?

JSON arrays, JSON objects with an array field, JSONL, and plain text (sentence, paragraph, line, or custom delimiter).

What causes split to fail?

Passing a Collection as target, invalid JSON structure, or finding no items to split will return a failed state.