Skip to content

Book Metadata System - Summary

What Was Created

A comprehensive metadata management system for intelligent textbook creation workflows with Claude Code skills.

Files Created

1. Core Metadata File

book-metadata.yml - Central configuration file containing: - Dublin Core bibliographic metadata (ISO 15836) - Book characteristics (intelligence level, academic level, etc.) - Skill execution status and dependencies - Workflow phase tracking - Content inventory - Validation rules

2. Python Helper Library

src/book_metadata_helper.py - Python API and CLI tool for: - Checking skill dependencies - Updating skill status - Querying workflow state - Generating status reports - Validating prerequisites

Command-line interface: 

1
2
3
python src/book_metadata_helper.py status         # Full status report
python src/book_metadata_helper.py check --skill NAME   # Check dependencies
python src/book_metadata_helper.py update --skill NAME --status STATUS --score SCORE

3. Documentation

docs/book-metadata-guide.md - Complete guide covering: - File structure and organization - Dublin Core metadata fields - Skill dependency system - Workflow phases - Python API usage - Best practices - Troubleshooting

docs/book-metadata-quickstart.md - Quick start guide with: - 5-minute getting started - Common workflows - Integration examples - Quick reference - Troubleshooting tips

docs/skills/metadata-integration-example.md - Detailed integration example: - Complete quiz generator skill example - Step-by-step integration pattern - Quality scoring examples - Claude Code integration

Key Features

1. Dependency Management

Skills declare dependencies with quality score requirements: 

1
2
3
4
5
dependencies:
  - skill: learning_graph_generator
    min_quality_score: 70
  - skill: chapter_generator
    min_completion_percentage: 30

The helper checks these before allowing skills to run.

2. Quality Tracking

Each skill execution records: - Status (not_started, in_progress, completed, failed, needs_update) - Quality score (0-100) - Execution timestamp - Output metrics (file paths, counts, validation results)

3. Workflow Phases

Six phases guide the creation process: 1. Planning 2. Foundation 3. Content Generation 4. Enhancement 5. Quality Assurance 6. Deployment

4. Status Reporting

Visual status reports show: - ✓ Completed skills with scores - → In-progress skills - ○ Not started skills - Dependency blockers for each skill

Example output: 

1
2
3
4
5
SKILLS STATUS:
  ✓ course_description_analyzer: completed (score: 85)
  ✓ learning_graph_generator: completed (score: 92)
  ○ glossary_generator: not_started
      └─ Blocked: Dependency 'learning_graph_generator' requires quality score >= 70

5. Dublin Core Integration

Standard bibliographic metadata: - Title, Creator, Subject, Description - Publisher, Date, Type, Format - Identifier (ISBN/DOI), Language - Rights/License information

Skills Tracked

The system tracks these Claude Code skills:

Foundation: - course_description_analyzer - Validates/creates course description

Content Generation: - learning_graph_generator - Creates concept dependency graph - glossary_generator - Generates terminology definitions - chapter_generator - Generates chapter content - microsim_p5 - Creates interactive p5.js simulations

Enhancement: - quiz_generator - Creates assessment quizzes - faq_generator - Generates FAQ content - reference_generator - Curates bibliography

Quality Assurance: - concept_validator - Validates concept completeness - quality_metrics_analyzer - Overall quality analysis

Deployment: - social_media_generator - Creates social media assets

Integration Pattern

For Skills (Minimal Integration)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from src.book_metadata_helper import BookMetadata

metadata = BookMetadata()

# 1. Check prerequisites
can_run, reasons = metadata.can_skill_run('skill_name')
if not can_run:
    print("Cannot run:", reasons)
    exit(1)

# 2. Mark as in progress
metadata.update_skill_status('skill_name', 'in_progress')

# 3. Do work...
result = do_skill_work()

# 4. Update with results
metadata.update_skill_status(
    skill_name='skill_name',
    status='completed',
    quality_score=result.score,
    outputs=result.metrics
)

For Authors

1
2
3
4
5
6
7
8
# Check what's ready to run
python src/book_metadata_helper.py status

# Verify prerequisites
python src/book_metadata_helper.py check --skill quiz_generator

# Run skills (they auto-update metadata)
# Check status again

Benefits

1. Prevents Errors

Skills can't run until dependencies are met, preventing: - Running quizzes before chapters exist - Generating glossary before learning graph - Creating FAQs with insufficient content

2. Tracks Progress

Clear visibility into: - What's been completed - What's currently running - What's blocked and why - Overall workflow progress

3. Quality Assurance

  • Minimum quality thresholds prevent low-quality outputs from propagating
  • Quality scores guide improvement efforts
  • Validation rules ensure completeness

4. Communication Between Skills

Skills can query results from other skills: 

1
2
3
# Get learning graph data
lg_status = metadata.get_skill_status('learning_graph_generator')
concept_count = lg_status['outputs']['concept_count']

5. Workflow Guidance

Status report shows exactly what to do next, reducing decision paralysis.

Example Workflow

  1. Start new book 

    1
2
    # Update Dublin Core in book-metadata.yml
vim book-metadata.yml

  2. Run course description analyzer 

    1
2
    python src/book_metadata_helper.py check --skill course_description_analyzer
# Run skill (manually or with Claude Code)

  3. Generate learning graph 

    1
2
    python src/book_metadata_helper.py check --skill learning_graph_generator
# ✓ Can run (course_description_analyzer completed with score 85 >= 70)

  4. Check progress 

    1
2
3
    python src/book_metadata_helper.py status
# Shows learning_graph_generator completed
# Shows glossary_generator and chapter_generator now unblocked

  5. Continue workflow

  6. Generate glossary and chapters (can run in parallel)
  7. Once chapters reach 30%, generate quizzes and FAQs
  8. When chapters reach 50%, generate social media assets
  9. Run quality metrics anytime
  10. Deploy when ready

Validation Rules

Configurable thresholds in book-metadata.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
validation:
  min_quality_scores:
    course_description: 70
    learning_graph: 70
    glossary: 70
    chapters: 60
    quizzes: 60

  min_completion:
    chapters_for_quizzes: 30
    chapters_for_faqs: 30
    chapters_for_social: 50

Extensibility

Adding New Skills

  1. Add skill entry to book-metadata.yml: 

    1
2
3
4
5
6
7
8
9
    skills:
  my_new_skill:
    status: "not_started"
    quality_score: null
    dependencies:
      - skill: some_dependency
        min_quality_score: 70
    outputs:
      files_created: 0

  2. Use the helper in your skill implementation

  3. Document integration in skill's README

Adding New Metadata

Extend the YAML structure: 

1
2
3
custom_section:
  my_field: value
  my_metrics: {}

Access via helper: 

1
2
metadata = BookMetadata()
custom = metadata.data.get('custom_section', {})

Future Enhancements

Potential additions: - Version control integration (link commits to skill runs) - Multi-book support - Web dashboard for visual workflow tracking - CI/CD integration for automated validation - Skill execution time tracking - Resource usage metrics - Collaborative features (multiple authors)

Getting Started

  1. Read the quickstart: docs/book-metadata-quickstart.md
  2. Review your metadata: book-metadata.yml
  3. Check status: python src/book_metadata_helper.py status
  4. Run next skill: Based on status report
  5. Repeat until book is complete

Support

  • Full documentation: docs/book-metadata-guide.md
  • Integration examples: docs/skills/metadata-integration-example.md
  • Quick reference: docs/book-metadata-quickstart.md

Summary

This metadata system provides: - ✅ Centralized book metadata (Dublin Core) - ✅ Skill dependency management - ✅ Quality tracking and validation - ✅ Workflow phase guidance - ✅ Status reporting and visibility - ✅ Communication between skills - ✅ Integration with Claude Code - ✅ Extensible architecture

It transforms ad-hoc skill execution into a structured, reliable workflow for creating high-quality intelligent textbooks.