Quickstart — get SKEIN useful in one project

GET GOING

SKEIN is a local record for project work with coding agents. It preserves useful findings, issues, ideas, frictions, and handoffs so the next session does not have to reconstruct everything from chat history. Its footprint in a project is a .skein/ directory, analogous to Git's .git/. Nothing is published merely because you use SKEIN.

You need Python 3.10 or newer, Git, uv, and an authenticated interactive coding-agent CLI such as Claude Code or Codex.

Install SKEIN:

uv tool install interskein
skein --version

Start its local service in one terminal and leave it running:

skein-server

In a second terminal, open the project you want to work on:

cd /absolute/path/to/project

If this is a new project, initialize Git first. If the project does not already contain .skein/, initialize SKEIN once:

git init
skein init --project NAME

You can now give the following work order to the interactive coding agent already working in that project.

PASTE THIS TO YOUR AGENT

Help me bring the project open in this session into SKEIN while making useful progress on what I care about now.

SKEIN is the project's durable local record for findings, issues, frictions, useful ideas, and handoffs between agent sessions. Use it naturally as working memory while you work. Nothing should be published merely because we use it.

First identify the project from the working directory, repository, documentation, and Git state. If its identity or intended scope is ambiguous, ask me instead of guessing. Then ask what I am trying to get done in it right now. Accept a short answer and preserve my words; do not infer my impetus from the repository.

Check the project's agent instructions and current state. Check whether SKEIN is initialized. If it is not, initialize it with an appropriate project name. Begin the SKEIN lifecycle with `skein ignite --message "Get SKEIN useful through real work on this project"`. Read its complete output, finish orienting, and run the exact `skein --agent NAME ready` command it gives you.

Work toward what I told you. Get hands on the real system and observe meaningful behavior through its normal operating path. For a web application, actually open and use the page. For an interactive application, use whatever interface harness is needed to operate it as a person would. Tests can support this contact but do not replace it.

Notice foundations that determine whether an agent can work effectively: repository state, the documented run path, dependencies, tests, and access to important interfaces. Improve missing foundations when that follows from my request and your authority. Do not manufacture cleanup merely to demonstrate activity.

Use `skein find` before posting. Record useful findings, issues, notions, and frictions as they arise, including friction caused by SKEIN itself. There is no quota, and not every record belongs in the next handoff. Use `skein post --help` when you need the exact posting form. Close a completed issue or friction with a note saying what happened.

Use normal judgment for safe, reversible local work. Ask before publishing, pushing, causing external side effects, performing destructive actions, or making material changes outside my request.

This first session may lead naturally into more work. Before the session actually ends, run `skein torch`, write a self-contained handoff brief preserving my words, what happened, the real-system boundary reached, the evidence, and the justified next action. Close completed work, then run `skein complete`. Tell me the brief ID. A fresh agent should be able to continue with `skein ignite BRIEF_ID` without relying on this conversation.

WHAT THIS DOES

The agent begins with your project and your reason for working on it, then uses SKEIN while doing real work. Useful evidence becomes part of the project record instead of disappearing with the session. The final brief gives the next agent a concrete starting point.

To inspect the record yourself:

skein sites
skein find "WORDS"
skein folio FOLIO_ID

OPTIONAL: SEVERAL BACKGROUND AGENTS

Spindle can run installed coding-agent harnesses in the background and preserve their results as spools. It is useful after the interactive agent leading the work has a clear reason to delegate; it is not required to get started with SKEIN.

uv tool install spindle-mcp
spindle install-service
spindle doctor

spindle doctor --smoke --harness codex spends one real agent run verifying the selected harness. The interactive lead agent remains responsible for the conversation with you, use of the real system, synthesis, SKEIN records, and the handoff.