home / skills / simhacker / moollm / sister-script

sister-script skill

safe

This skill helps you translate proven procedures into automated sister scripts, grounding automation in documented patterns.

npx playbooks add skill simhacker/moollm --skill sister-script

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

Files (7)

SKILL.md

3.4 KB

---
name: sister-script
description: Document-first automation — the doc is the source of truth
license: MIT
tier: 1
allowed-tools:
  - read_file
  - write_file
  - run_terminal_cmd
related: [moollm, play-learn-lift, skill, sniffable-python, plain-text, yaml-jazz, constructionism, postel, debugging]
tags: [moollm, automation, documentation, methodology, development]
---

# Sister Script

> **Document-first development. Automate only what's proven.**

The document is the source of truth. Scripts are its children.

> [!TIP]
> **LIFT stage of [play-learn-lift](../play-learn-lift/).** Proven procedures become automation.

## The Pattern

```mermaid
graph TD
    D[📄 Document] -->|manual test| C[💻 Commands]
    C -->|document| P[📋 Procedure]
    P -->|automate| S[🤖 Sister Script]
    S -->|improve| D
```

1. Start with natural language (PLAY)
2. Add manual commands (PLAY/LEARN)  
3. Document working procedures (LEARN)
4. Generate automation (LIFT)

## Bidirectional Evolution

- Document → Script: Proven procedures become automated
- Script → Document: Automation insights improve docs

## Contents

| File | Purpose |
|------|---------|
| [SKILL.md](./SKILL.md) | Full methodology documentation |
| [PROCEDURE.md.tmpl](./PROCEDURE.md.tmpl) | Procedure template |
| [SISTER.yml.tmpl](./SISTER.yml.tmpl) | Sister relationship template |

## The Intertwingularity

Sister-script is the LIFT stage of [play-learn-lift](../play-learn-lift/) — automate proven patterns.

```mermaid
graph LR
    SS[👯 sister-script] -->|LIFT stage of| PLL[🎮📚🚀 play-learn-lift]
    SS -->|automates| DOC[📄 documents]
    SS -->|produces| CODE[🤖 scripts]
    
    RN[📓 research-notebook] -->|feeds| SS
    SL[📜 session-log] -->|source for| SS
```

---

## Sniffable Python: The Structure

Sister scripts should follow [sniffable-python/](../sniffable-python/) conventions:

```python
#!/usr/bin/env python3
"""tool-name: One-line description.

Docstring becomes --help AND is visible to LLM.
"""

import argparse

def main():
    """CLI structure — sniff this to understand the tool."""
    parser = argparse.ArgumentParser(description=__doc__.split('\n')[0])
    # ... CLI tree here ...
    args = parser.parse_args()
    _dispatch(args)

# Implementation below the fold
```

**Why sniffable Python for sister scripts?**
- LLM can read `main()` and understand the CLI
- Human can run `--help` for the same info
- Single source of truth for documentation
- One sniff and you smell success

---

## Dovetails With

### Sister Skills
| Skill | Relationship |
|-------|--------------|
| [sniffable-python/](../sniffable-python/) | **The structure** sister scripts should follow |
| [play-learn-lift/](../play-learn-lift/) | Sister-script IS the LIFT stage |
| [session-log/](../session-log/) | Source material for patterns |
| [research-notebook/](../research-notebook/) | Documented procedures |
| [plan-then-execute/](../plan-then-execute/) | Scripts can become plans |

### Protocol Symbols
| Symbol | Link |
|--------|------|
| `SISTER-SCRIPT` | [PROTOCOLS.yml](../../PROTOCOLS.yml#SISTER-SCRIPT) |
| `BUILD-COMMAND` | [PROTOCOLS.yml](../../PROTOCOLS.yml#BUILD-COMMAND) |
| `PLAY-LEARN-LIFT` | [PROTOCOLS.yml](../../PROTOCOLS.yml#PLAY-LEARN-LIFT) |

### Navigation
| Direction | Destination |
|-----------|-------------|
| ⬆️ Up | [skills/](../) |
| ⬆️⬆️ Root | [Project Root](../../) |
| 🎮 Sister | [play-learn-lift/](../play-learn-lift/) |

Overview

This skill implements a document-first automation pattern where the human-written document is the source of truth and scripts are generated only for proven procedures. It encourages iterating from natural language exploration to documented procedures and then to small, sniffable Python scripts that mirror the documented intent. The goal is safer, maintainable automation that evolves bidirectionally between docs and code.

How this skill works

You start by writing natural-language play notes and capturing manual commands. Once a procedure is verified, you formalize it into a document procedure template and generate a small Python script that follows a sniffable CLI structure. The resulting script both automates the proven steps and feeds insights back into the original document so documentation and automation stay synchronized.

When to use it

When tasks are new and require experimentation before automation.
When you want automation to be traceable to a human-readable procedure.
When you need small, maintainable CLI tools that are discoverable by humans and LLMs.
When you want automation to drive documentation improvements rather than replace them.

Best practices

Keep the document as the single source of truth; only automate steps that are well-tested.
Write scripts in a sniffable Python layout: clear main(), argparse, and a concise docstring.
Make docstrings identical to user-facing help text to avoid drift between help and docs.
Iterate bidirectionally: let automation surface improvements and update the document accordingly.
Limit automation scope to repeatable, low-risk procedures and keep complex logic explicit in docs.

Example use cases

Capturing an exploratory workflow, documenting the successful procedure, then generating a CLI script to repeat it reliably.
Turning frequent manual deployment steps into a small tool that exposes a clear --help and mirrors the documented procedure.
Extracting a repeatable data-prep pipeline from session notes and creating a sniffable script for teammates to run.
Converting an ops checklist into automation while preserving the checklist as the authoritative documentation.

FAQ

Why treat the document as the source of truth?

Documents capture human intent, edge cases, and rationale; automating only verified steps reduces accidental complexity and keeps behavior explainable.

What is sniffable Python and why use it?

Sniffable Python uses a predictable CLI structure (main(), argparse, and a clear docstring) so both humans and language models can quickly understand the tool's behavior.