Organize knowledge base intake files โ analyze content, assign lifecycle/domain tags, generate YAML frontmatter, move to destination folders. Use when user triggers AI Librarian from KB UI or CLI. Triggers on requests like "organize knowledge base intake files with AI Librarian", "run AI Librarian", "organize intake".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Organize knowledge base intake files โ analyze content, assign lifecycle/domain tags, generate YAML frontmatter, move to destination folders. Use when user triggers AI Librarian from KB UI or CLI. Triggers on requests like "organize knowledge base intake files with AI Librarian", "run AI Librarian", "organize intake".
KB AI Librarian
Purpose
AI Agents follow this skill to organize knowledge base intake files by:
Reading pending files from the .intake/ folder
Analyzing content to determine the best destination folder and tags
Generating YAML frontmatter for markdown files
Moving files to their destination and updating intake status
Important Notes
BLOCKING: Process ALL pending files in one batch. Do not prompt for file selection.
BLOCKING: Respect pre-assigned destinations from the UI. Only use AI folder selection for files without a destination.
CRITICAL: Non-markdown files (PDF, images, etc.) are moved and status-tracked but do NOT receive frontmatter injection.
CRITICAL: Existing frontmatter in markdown files MUST be preserved. Only merge missing fields โ never overwrite existing values.
About
The KB AI Librarian automates the organization of files dropped into the knowledge base intake folder. When a user clicks "โจ Run AI Librarian" in the KB Browse Modal or triggers the command via CLI, this skill processes all pending intake files: analyzing their content, assigning appropriate tags from the project's tag taxonomy, generating metadata index entries for ALL file types, and moving them to the correct destination folder.
Key Concepts:
Intake Folder โ The .intake/ directory under the KB root where new files are dropped for processing
Intake Status โ Tracked in .intake-status.json: โ โ
pending
processing
filed
Tag Taxonomy โ Lifecycle tags (7) and domain tags (10) defined in knowledgebase-config.json
Metadata Index โ Per-folder .kb-index.json registry storing metadata (title, description, tags, author, type) for ALL file types (replaces YAML frontmatter)
Destination Folder โ Target folder within the KB where a file should live, determined by UI assignment or AI analysis
When to Use
triggers:-"organize knowledge base intake files with AI Librarian"-"run AI Librarian"-"organize intake"-"process intake files"not_for:-"Browsing KB files or managing intake UI โ use KB Browse Modal frontend"-"Configuring KB settings โ edit knowledgebase-config.json directly"-"Creating new KB articles from scratch โ use KB editor"
<input_init><fieldname="operation"source="Always 'organize_intake' โ single-operation skill"><validation>MUST equal 'organize_intake'</validation></field><fieldname="kb_root"source="Auto-detected from project structure"><steps>
1. Look for x-ipe-docs/knowledge-base/ in the project root
2. IF not found, check knowledgebase-config.json for configured root
3. IF still not found, fail with KB_ROOT_NOT_FOUND
</steps></field></input_init>
Definition of Ready
<definition_of_ready><checkpointrequired="true"><name>KB root folder exists</name><verification>x-ipe-docs/knowledge-base/ directory exists in the project</verification></checkpoint><checkpointrequired="true"><name>Intake folder exists</name><verification>.intake/ subdirectory exists under KB root</verification></checkpoint><checkpointrequired="true"><name>KB config readable</name><verification>knowledgebase-config.json exists and contains tag taxonomy (tags.lifecycle, tags.domain)</verification></checkpoint></definition_of_ready>
Skill Dependencies
Dependency
Required?
Purpose
x-ipe-tool-ontology
Optional
Creates ontology entities for filed knowledge items. If ontology tooling is not available, files are moved and tagged normally (no entity creation).
Ontology Contract:
After filing each file, invoke ontology.py create to create a KnowledgeNode entity
If entity creation fails, set status to filed-untagged (not filed) and continue
filed-untagged files can be re-tagged later via ontology.py retag
The .intake-status.json supports statuses: pending, processing, filed, filed-untagged
Operations
Operation: organize_intake
When: User triggers AI Librarian to process pending intake files.
<operationname="organize_intake"><action>
1. Read KB configuration:
- Load knowledgebase-config.json from KB root
- Extract tag taxonomy: tags.lifecycle[] and tags.domain[]
- Extract folder structure for destination matching
2. Get intake files:
- Call GET /api/kb/intake (or read .intake/ directory + .intake-status.json directly)
- Filter to files with status == "pending" (or no status entry = pending by default)
- IF no pending files found โ print "No pending files to process" and exit with success
3. For each pending file, process sequentially:
a. Set status to "processing":
- Call PUT /api/kb/intake/status with {filename, status: "processing"}
b. Read file content:
- Read the full file content from .intake/{filename}
c. Determine destination folder:
- IF file has a pre-assigned destination in .intake-status.json โ use it
- ELSE analyze content to determine the best matching KB folder:
* Scan existing KB folder structure (folder names and any README descriptions)
* Match file content topics/keywords to folder purposes
* Select the single best-matching folder
- IF destination folder does not exist โ create it
d. Assign tags:
- Analyze content against the tag taxonomy from knowledgebase-config.json
- Select 1-2 lifecycle tags (e.g., "Design", "Implementation")
- Select 1-3 domain tags (e.g., "API", "Security")
- Use conservative tagging โ only assign tags with clear evidence in content
e. Generate metadata index entry for ALL file types:
- Generate entry: title, description (< 100 words), tags (lifecycle + domain), author, created, type, auto_generated: true
- IF markdown (.md) file:
* Analyze content for title, description, tags
* Parse existing frontmatter (if any) as hints โ DO NOT inject new frontmatter into file
- IF non-markdown file (images, PDFs, videos, etc.):
* Derive title from filename
* Generate description from context/filename
* type field set automatically from file extension
- Run via bash: `python3 .github/skills/x-ipe-tool-x-ipe-app-interactor/scripts/kb_set_entry.py --name {name} --entry '{json}' --folder {folder}`
f. Move file to destination:
- Move file from .intake/{filename} to {destination_folder}/{filename}
- Use KB service move capability (POST /api/kb/files/move or filesystem move)
g. Update status to "filed":
- Call PUT /api/kb/intake/status with {filename, status: "filed", destination: "{destination_path}"}
h. Ontology tagging (Phase 2 โ optional):
- IF ontology tooling is available (.ontology/ directory exists under KB root):
* Run via bash: `python3 .github/skills/x-ipe-tool-ontology/scripts/ontology.py create \
--type KnowledgeNode \
--props '{"label":"<derivedfromtitle>","node_type":"document","source_files":["<destination_path>"]}' \
--graph {kb_root}/.ontology/_entities.jsonl`
* IF creation succeeds โ entity_id recorded (no status change needed, already "filed")
* IF creation fails โ update status to "filed-untagged" and record error:
Call PUT /api/kb/intake/status with {filename, status: "filed-untagged", error: "<errormessage>"}
- IF ontology tooling NOT available โ skip (file remains with status "filed")
4. After ontology tagging completes, IF at least one entity was successfully created in step 3h,
trigger graph rebuild:
- Run via bash: `python3 .github/skills/x-ipe-tool-ontology/scripts/graph_ops.py build \
--scope {kb_root} --output {kb_root}/.ontology --entities {kb_root}/.ontology/_entities.jsonl`
5. Print terminal summary:
- Format: "{N} files processed โ {folder1}/ ({count1}), {folder2}/ ({count2})"
- If any files filed-untagged: ", {M} filed-untagged (retag with: ontology.py retag)"
- If any errors occurred: also print "{E} files failed: {error details}"
</action><constraints>
- BLOCKING: Must set status to "processing" BEFORE analyzing each file
- BLOCKING: Must respect pre-assigned destinations โ do NOT override with AI suggestion
- CRITICAL: Continue processing remaining files if one file fails
- CRITICAL: Only generate frontmatter for markdown files
- CRITICAL: Never overwrite existing frontmatter fields โ merge only
</constraints><output>operation_output with files_processed, destinations, errors, summary</output></operation>
<definition_of_done><checkpointrequired="true"><name>All pending files processed</name><verification>Every file with status "pending" was attempted (status changed from pending)</verification></checkpoint><checkpointrequired="true"><name>All files have index entries</name><verification>All processed files (markdown AND non-markdown) have entries in destination folder's .kb-index.json with title, description, tags, author, type, auto_generated</verification></checkpoint><checkpointrequired="true"><name>Files moved to destinations</name><verification>Processed files no longer in .intake/ โ moved to destination folders</verification></checkpoint><checkpointrequired="true"><name>Status updated to filed</name><verification>.intake-status.json shows status="filed" with destination for each processed file</verification></checkpoint><checkpointrequired="true"><name>Terminal summary printed</name><verification>Summary line shows count of files processed and destination folders</verification></checkpoint></definition_of_done>
Error Handling
Error
Cause
Resolution
KB_ROOT_NOT_FOUND
No knowledge-base/ folder in project
Verify KB is initialized; check project structure
INTAKE_FOLDER_NOT_FOUND
No .intake/ directory under KB root
Create .intake/ folder or check KB config
CONFIG_MISSING_TAGS
knowledgebase-config.json missing tag taxonomy
Add tags.lifecycle and tags.domain arrays to config
FILE_READ_ERROR
Cannot read file from .intake/
Check file permissions; skip file and continue
MOVE_FAILED
File move operation failed
Check destination path validity and permissions; retry once
NO_PENDING_FILES
All intake files already processed
Not an error โ print message and exit with success
ONTOLOGY_TAG_FAILED
Entity creation failed during ontology tagging
Set status to filed-untagged, record error, continue processing. Use ontology.py retag later to retry.
ONTOLOGY_NOT_AVAILABLE
.ontology/ directory not found under KB root
Not an error โ skip ontology tagging entirely, file remains filed
Templates
File
Purpose
None
This skill produces no template files โ it operates on existing files
Examples
See .github/skills/x-ipe-tool-kb-librarian/references/examples.md for usage examples.
