65 lines
2.1 KiB
Markdown
65 lines
2.1 KiB
Markdown
# 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.
|