From 6221197670934b5045d437f9fd1b965e68ac3321 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Thu, 27 Aug 2026 13:36:35 -0400
Subject: [PATCH] Add ingest skill contract

---
 docs/ingest-skill-contract.md | 64 +++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 docs/ingest-skill-contract.md

diff --git a/docs/ingest-skill-contract.md b/docs/ingest-skill-contract.md
new file mode 100644
index 0000000..0036d5a
--- /dev/null
+++ b/docs/ingest-skill-contract.md
@@ -0,0 +1,64 @@
+# Ingest skill contract
+
+## Contract
+
+An ingest skill transforms an input into source understanding.
+
+The general flow is:
+
+```text
+input -> source understanding -> response, optionally durable output
+```
+
+## Terms
+
+### Input
+
+Input is the source-specific content that the skill ingests.
+Each ingest skill defines its accepted input shapes.
+
+Examples include URLs, file paths, pasted text, active agent context, issue numbers, transcripts, and exported conversations.
+
+### Source understanding
+
+Source understanding is the main result of ingestion.
+The agent can reason about the input.
+The agent can answer questions about it.
+The agent can use it in the current task.
+
+Source understanding does not require writing files to disk.
+A chat-only ingest satisfies the contract when the agent understands the source and gives a useful response.
+
+### Response
+
+Response is the agent message to the user.
+The contract does not define a strict response format.
+
+When the agent creates durable output, the response must say so and identify it.
+When the agent creates temporary scratch files, the response must state their location.
+
+### Durable output
+
+Durable output is persisted output for longer-term use.
+A source-specific skill or project convention chooses the artifact type.
+Examples include Markdown files, other file formats, and database records.
+
+## Write behavior
+
+The agent creates durable output only in two cases:
+
+1. The user requests durable output.
+2. Active project or source-specific conventions require durable output.
+
+When the user asks a chat-only question about a source, the ingest skill answers in chat.
+When the user asks to save, write, create, or add an output, the ingest skill creates durable output.
+When active project or source-specific conventions define durable output behavior, the ingest skill follows those conventions.
+
+When no durable output convention exists, default to chat-only.
+The user can ask for durable output afterward.
+
+## Scope boundaries
+
+This contract defines only the shared ingest flow.
+Source-specific skills define extraction and analysis details for their source type.
+Projects define their persistence conventions.
-- 
2.47.3