tachikoma-schema
Analyze a Context Lake workspace and propose schema improvements. Use when asked to run schema cleanup, analyze workspace structure, create or update schema.yaml, or identify entity types.
When & Why to Use This Skill
This Claude skill provides automated analysis and structural optimization for Context Lake workspaces. It streamlines the management of complex knowledge bases by identifying entity types, validating frontmatter metadata, and proposing standardized schema improvements. By ensuring data consistency and clear workspace organization, it significantly enhances the efficiency of agentic context retrieval and long-term memory management.
Use Cases
- Automated Schema Generation: Scan an unorganized workspace to identify recurring patterns and automatically generate a comprehensive schema.yaml file for better data governance.
- Metadata Consistency Auditing: Detect missing required fields, inconsistent naming patterns, or optional field trends across large sets of Markdown-based entity files.
- Workspace Structure Optimization: Analyze existing directory structures to propose new entity types and consolidate disparate metadata into a unified, actionable decision log.
- Context Lake Maintenance: Periodically update workspace summaries and observations to ensure AI agents maintain a clear and structured understanding of the evolving knowledge base.
| name | tachikoma-schema |
|---|---|
| description | Analyze a Context Lake workspace and propose schema improvements. Use when asked to run schema cleanup, analyze workspace structure, create or update schema.yaml, or identify entity types. |
| allowed-tools | Read, Write, Glob, Grep |
Tachikoma Schema Cleanup
You are running schema cleanup on a Context Lake workspace. Your job is to analyze the workspace structure and propose schema improvements by creating decision files.
Context Lake Structure
The workspace IS the Context Lake. Entity directories live at the workspace root:
.claude/schema.yaml- Entity type definitions (may not exist yet).claude/tachikoma-summary.yaml- Previous observations{entity_type}/- Entity directories (tasks/, notes/, roles/, etc.)decisions/- Where you write proposals
There is NO lake/ subdirectory.
Schema Format
Motoko uses this exact schema format:
entities:
{entity_type}:
directory: {entity_type} # Relative to workspace root
naming: "{slug}.md" # Filename pattern
frontmatter:
required: [field1, field2] # Must be present
optional: [field3, field4] # May be present
defaults: # Defaults for new entities
status: open
DO NOT add fields like description, structure, sections, types, or taxonomy - these are not part of the schema format.
What to Look For
- Missing entity types: Directories without schema definitions (need 3+ files with consistent patterns)
- Missing required fields: Frontmatter fields in ALL entities of a type
- Missing optional fields: Frontmatter fields in SOME entities (multiple files, not just one)
- Naming patterns: How files are named (date-based, slug-based, etc.)
Process
- Read
.claude/schema.yamlif it exists - Read
.claude/tachikoma-summary.yamlfor previous observations - List workspace root directories (ignore .claude, .git, node_modules, etc.)
- For each directory with 3+ .md files, sample files to identify patterns
- Create ONE consolidated decision file in
decisions/ - Update
.claude/tachikoma-summary.yamlwith findings
Decision Format
Write decisions to decisions/ directory with frontmatter:
---
title: "schema: create initial schema.yaml"
status: pending
decision_type: schema_update
confidence: 0.9
created_at: {ISO timestamp}
---
## Current State
No schema.yaml exists. Found N entity types.
## Suggested Change
Create .claude/schema.yaml:
```yaml
entities:
tasks:
directory: tasks
naming: "{slug}.md"
frontmatter:
required: [title, status]
optional: [priority, due]
defaults:
status: open
Reasoning
Analyzed X files across Y directories. Patterns observed: ...
## Guidelines
- **CONSOLIDATE**: One decision per schema file, not per entity type
- **BE CONSERVATIVE**: Don't infer from single examples
- **SAMPLE ADEQUATELY**: Read at least 3 files per entity type
- When in doubt, make fields optional rather than required
## Output
When done, update `.claude/tachikoma-summary.yaml`:
```yaml
last_scan: {ISO timestamp}
cleanup_mode: schema
entity_counts:
tasks: 10
notes: 5
observations:
- Schema exists with 3 entity types
- Found 2 directories without definitions
pending_decisions:
- schema-add-companies.md