atomism

name	atomism
description	This skill should be used when working with the Atomism framework for schema-first agent orchestration. Use for creating, registering, and running atoms, managing capabilities, executing workflows, and extracting atoms from existing code or skills.

Atomism Framework

Atomism is a schema-first agent swarm orchestration framework. It provides a CLI (atomic) for defining, registering, and executing "atoms" - small, verifiable, schema-validated units of work.

When to Use This Skill

• Creating new atoms for repeatable tasks
• Running registered atoms with input validation
• Extracting atoms from existing skills, code, or workflows
• Managing capability registrations
• Executing multi-step workflows
• Checking project status and history

Prerequisites

Ensure the project has been initialized:

atomic init --json

This creates the .atomic/ directory with storage and registry.

Core Workflows

Creating and Registering an Atom

To create a new atom:

atomic create atom <name> --json

This scaffolds atoms/<name>.ts and atoms/<name>.test.ts. Edit the atom file to implement the handler, then register:

atomic register atoms/<name>.ts --json

Running an Atom

To execute a registered atom:

atomic run <atom_name> --input '{"key": "value"}' --yes --json

Always use --json for structured output that can be parsed. Use --yes to skip confirmation for idempotent atoms.

Extracting from Existing Sources

To create an atom from an existing skill:

atomic extract --skill ./path/to/skill.md --output ./atoms --yes --json

To extract from code:

atomic extract --code ./path/to/file.ts --output ./atoms --yes --json

Checking Status

To see registered atoms and capabilities:

atomic status --json
atomic list --json

Atom File Structure

Atoms use Zod schemas for input/output validation:

import { z } from 'zod';
import { defineAtom, success, error } from 'atomic';

export default defineAtom({
  name: 'my_atom',
  description: 'What this atom does',
  input: z.object({
    param: z.string().describe('Parameter description'),
  }),
  output: z.object({
    result: z.string().describe('Result description'),
  }),
  tests: {
    path: './my_atom.test.ts',
  },
  idempotent: true,
  handler: async ({ param }) => {
    // Implementation
    return success({ result: 'done' });
    // Or: return error('Failed', { recoverable: true });
  },
});

Best Practices

1. Always use --json flag for machine-readable output
2. Always use --yes flag when running idempotent atoms to avoid prompts
3. Keep atoms small and focused - one clear purpose per atom
4. Use descriptive names - snake_case naming convention
5. Define clear schemas - input/output validation catches errors early

Reference

For complete CLI documentation, see references/cli_reference.md.