alexion/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Define generic ingest skill contract #24

New Issue
Closed
opened 2026-08-27 00:17:26 -04:00 by alexion · 1 comment
alexion commented 2026-08-27 00:17:26 -04:00
Owner
Copy Link

Define generic ingest skill contract

Goal

Define a shared contract for source-specific ingest skills in ~/wrk/skills.

The contract should shape implementations such as ingest-youtube-transcript, ingest-youtube-video, PDF ingest, article ingest, and Markdown/artifact ingest.
It should not necessarily be linked from each runtime SKILL.md.
It is an implementation/design reference for building consistent ingest skills.

Core contract

An ingest skill turns one external input into one Obsidian-ready source note plus a loose final chat report.

external input -> one source note + final chat report

Examples:

YouTube URL -> 01 sources/<title>.md + final chat report
PDF path -> 01 sources/<title>.md + final chat report
article URL -> 01 sources/<title>.md + final chat report
Markdown artifact -> 01 sources/<title>.md + final chat report

Write policy

Explicitly invoking an ingest skill is approval to create one final source note in 01 sources/.

The skill should not require a redundant preview/approval step before writing the source note.
The vault is Git-tracked, so review happens through the normal diff/revert workflow.

The skill should not create 02 notes/ files by default.
Durable note creation is a separate review/promotion activity.

Scratch policy

Raw scratch assets should default to /tmp or another non-vault temporary directory.

Examples:

/tmp/<skill>/<source-id>/metadata.json
/tmp/<skill>/<source-id>/captions.json3
/tmp/<skill>/<source-id>/video.webm
/tmp/<skill>/<source-id>/frames/

Provisional Markdown scratch may be written inside the AI boundary when useful for user inspection:

00 INBOX/ai/<source-id>/

Raw assets should not be copied into the vault automatically unless they are useful as attachments in the final source note.

Source note structure

The default source note structure should match the structure recovered from the YouTube summary workflow we inspected.

---
date-created: YYYY-MM-DD
source: <source-type>
url: <url if any>
---

# <source title>

## Summary

## Structure

## Key concepts

## Key points

## Argument structures

Source-specific skills may rename Structure when it improves clarity.
For example:

## Video structure

or:

## Chapter structure

But the generic contract should remain the same.

Metadata policy

Keep frontmatter minimal.

Required or expected fields:

date-created: YYYY-MM-DD
source: <source-type>
url: <url if any>

Do not add generic ceremony such as:

ingested-by: ai
status: ai-generated
reviewed: false

The note's location in 01 sources/ is enough to indicate that it is a source note.
Review state and AI provenance should not be encoded by default.

Do not add tags by default.
Tags and tag notes are intentionally deferred.

Final chat report

The final report is the agent's response in chat, not a separate report file.

It should be loose rather than rigidly standardized.
It should include, when relevant:

  • what was ingested
  • source URL/path
  • created source note path
  • scratch path, if any
  • important caveats
  • follow-up ideas, if any

Follow-up ideas belong in the final chat report, not in the source note by default.

Caveats should be included naturally when relevant.
Do not create a formal confidence system by default.

Example final report:

Ingested: Second brain setup for doing
Source: https://www.youtube.com/watch?v=Y1xO9OsCBC4
Created: 01 sources/second brain setup for doing.md
Scratch: /tmp/ingest-youtube-transcript/Y1xO9OsCBC4/
Caveats: Used automatic English captions.
Follow-up ideas:
- Consider promoting "temporal contract" into a durable note.

Skill naming direction

Prefer source-specific ingest skills.
Do not implement generic quick or deep modes in one skill if separate skills make the behavior clearer.

For YouTube, the intended split is:

ingest-youtube-transcript
ingest-youtube-video

ingest-youtube-transcript should replace or rename the existing youtube-transcript user-facing skill.
It should match the ingest contract and create one source note.

The current structured JSON behavior should remain available as a helper/tool interface because structured JSON is useful and consistent for downstream workflows.
The exact JSON field shape is intentionally undecided for now.

ingest-youtube-video should represent the richer workflow involving timestamped captions, candidate visual moments, frame extraction, and visual evidence.
That workflow is already described separately in issue #23.

Non-goals

  • Do not create atomic notes by default.
  • Do not add tags by default.
  • Do not require exact final report wording.
  • Do not require every runtime skill to link to the contract doc.
  • Do not add reviewed/unreviewed metadata by default.
  • Do not copy raw scratch assets into the vault by default.

Acceptance criteria

  • A generic ingest contract is documented in the skills repository.
  • The contract defines the default input/output shape.
  • The contract defines the default source note section list.
  • The contract defines the write policy for 01 sources/.
  • The contract defines scratch handling for /tmp and 00 INBOX/ai/.
  • The contract says final reports are loose chat reports, not required report files.
  • The contract says follow-up ideas belong in the final chat report by default.
  • The contract says ingest skills do not create 02 notes/ files by default.
  • The contract records that ingest-youtube-transcript should replace/rename the current youtube-transcript user-facing skill while preserving structured JSON as a helper interface.
# Define generic ingest skill contract ## Goal Define a shared contract for source-specific ingest skills in `~/wrk/skills`. The contract should shape implementations such as `ingest-youtube-transcript`, `ingest-youtube-video`, PDF ingest, article ingest, and Markdown/artifact ingest. It should not necessarily be linked from each runtime `SKILL.md`. It is an implementation/design reference for building consistent ingest skills. ## Core contract An ingest skill turns one external input into one Obsidian-ready source note plus a loose final chat report. ```text external input -> one source note + final chat report ``` Examples: ```text YouTube URL -> 01 sources/<title>.md + final chat report PDF path -> 01 sources/<title>.md + final chat report article URL -> 01 sources/<title>.md + final chat report Markdown artifact -> 01 sources/<title>.md + final chat report ``` ## Write policy Explicitly invoking an ingest skill is approval to create one final source note in `01 sources/`. The skill should not require a redundant preview/approval step before writing the source note. The vault is Git-tracked, so review happens through the normal diff/revert workflow. The skill should not create `02 notes/` files by default. Durable note creation is a separate review/promotion activity. ## Scratch policy Raw scratch assets should default to `/tmp` or another non-vault temporary directory. Examples: ```text /tmp/<skill>/<source-id>/metadata.json /tmp/<skill>/<source-id>/captions.json3 /tmp/<skill>/<source-id>/video.webm /tmp/<skill>/<source-id>/frames/ ``` Provisional Markdown scratch may be written inside the AI boundary when useful for user inspection: ```text 00 INBOX/ai/<source-id>/ ``` Raw assets should not be copied into the vault automatically unless they are useful as attachments in the final source note. ## Source note structure The default source note structure should match the structure recovered from the YouTube summary workflow we inspected. ```markdown --- date-created: YYYY-MM-DD source: <source-type> url: <url if any> --- # <source title> ## Summary ## Structure ## Key concepts ## Key points ## Argument structures ``` Source-specific skills may rename `Structure` when it improves clarity. For example: ```markdown ## Video structure ``` or: ```markdown ## Chapter structure ``` But the generic contract should remain the same. ## Metadata policy Keep frontmatter minimal. Required or expected fields: ```yaml date-created: YYYY-MM-DD source: <source-type> url: <url if any> ``` Do not add generic ceremony such as: ```yaml ingested-by: ai status: ai-generated reviewed: false ``` The note's location in `01 sources/` is enough to indicate that it is a source note. Review state and AI provenance should not be encoded by default. Do not add tags by default. Tags and tag notes are intentionally deferred. ## Final chat report The final report is the agent's response in chat, not a separate report file. It should be loose rather than rigidly standardized. It should include, when relevant: - what was ingested - source URL/path - created source note path - scratch path, if any - important caveats - follow-up ideas, if any Follow-up ideas belong in the final chat report, not in the source note by default. Caveats should be included naturally when relevant. Do not create a formal confidence system by default. Example final report: ```text Ingested: Second brain setup for doing Source: https://www.youtube.com/watch?v=Y1xO9OsCBC4 Created: 01 sources/second brain setup for doing.md Scratch: /tmp/ingest-youtube-transcript/Y1xO9OsCBC4/ Caveats: Used automatic English captions. Follow-up ideas: - Consider promoting "temporal contract" into a durable note. ``` ## Skill naming direction Prefer source-specific ingest skills. Do not implement generic `quick` or `deep` modes in one skill if separate skills make the behavior clearer. For YouTube, the intended split is: ```text ingest-youtube-transcript ingest-youtube-video ``` `ingest-youtube-transcript` should replace or rename the existing `youtube-transcript` user-facing skill. It should match the ingest contract and create one source note. The current structured JSON behavior should remain available as a helper/tool interface because structured JSON is useful and consistent for downstream workflows. The exact JSON field shape is intentionally undecided for now. `ingest-youtube-video` should represent the richer workflow involving timestamped captions, candidate visual moments, frame extraction, and visual evidence. That workflow is already described separately in issue #23. ## Non-goals - Do not create atomic notes by default. - Do not add tags by default. - Do not require exact final report wording. - Do not require every runtime skill to link to the contract doc. - Do not add reviewed/unreviewed metadata by default. - Do not copy raw scratch assets into the vault by default. ## Acceptance criteria - A generic ingest contract is documented in the skills repository. - The contract defines the default input/output shape. - The contract defines the default source note section list. - The contract defines the write policy for `01 sources/`. - The contract defines scratch handling for `/tmp` and `00 INBOX/ai/`. - The contract says final reports are loose chat reports, not required report files. - The contract says follow-up ideas belong in the final chat report by default. - The contract says ingest skills do not create `02 notes/` files by default. - The contract records that `ingest-youtube-transcript` should replace/rename the current `youtube-transcript` user-facing skill while preserving structured JSON as a helper interface.
alexion commented 2026-08-27 13:37:44 -04:00
Author
Owner
Copy Link

See #25

See #25
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
alexion
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: alexion/skills#24
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?