skill-from-book

Skill From Book

Transform book content into structured, context-efficient Claude skills.

Overview

This skill guides you through converting a book (in markdown format) into a well-organized skill with:

• Granular knowledge files (one concept per file)
• Workflows for repeatable tasks
• Use-case guidelines (mapping tasks to relevant files)
• Progress tracking for multi-session work
• Subagent extraction tasks

CRITICAL INSTRUCTIONS

YOU MUST FOLLOW THIS WORKFLOW STRICTLY. DO NOT SKIP OR REORDER PHASES.

1. DO NOT read the book markdown file content before starting Phase 1
2. MUST read each reference file BEFORE starting its corresponding phase
3. MUST complete each phase before moving to the next
4. MUST use subagents for extraction tasks
5. MUST propose workflows to user before finalization

---

Workflow

Phase 1: Analysis

STOP! Before proceeding, you MUST:

1. Read references/analysis-guide.md completely
2. Only then proceed with the steps below

Phase 1 Steps:

1. Extract TOC and outline ONLY (DO NOT read full book content)

   # Count total lines
   wc -l book.md
   
   # Extract headers/TOC - THIS IS ALL YOU NEED
   grep -E "^#{1,3} " book.md
   

2. Identify knowledge categories from outline

   • Core principles/philosophy
   • Rules and guidelines
   • Examples (good vs bad)
   • Patterns and anti-patterns
   • Checklists and quick references

3. Define use cases

   • Who will use this skill?
   • What tasks will they perform?
   • What questions will they ask?

4. Ask user to confirm the identified categories and use cases before proceeding

---

Phase 2: Planning

STOP! Before proceeding, you MUST:

1. Read references/extraction-patterns.md completely
2. Read references/file-templates.md completely
3. Only then proceed with the steps below

Phase 2 Steps:

1. Design file structure with required files per category

   Each category MUST contain these 3 basic files:

   • knowledge.md - Core concepts, definitions, and foundational understanding
   • rules.md - Specific guidelines, do's and don'ts
   • examples.md - Good/bad code examples, before/after comparisons

   Additional files as needed:

   • patterns.md - Reusable solutions
   • smells.md - Anti-patterns and what to avoid
   • checklist.md - Quick reference checklists

   skill-name/
   ├── SKILL.md
   ├── progress.md
   ├── guidelines.md
   ├── workflows/           # NEW: Step-by-step processes
   │   ├── [task-1].md
   │   └── [task-2].md
   └── references/
       ├── category-1/
       │   ├── knowledge.md    # REQUIRED
       │   ├── rules.md        # REQUIRED
       │   ├── examples.md     # REQUIRED
       │   ├── patterns.md     # Optional
       │   └── checklist.md    # Optional
       └── category-2/
           ├── knowledge.md    # REQUIRED
           ├── rules.md        # REQUIRED
           ├── examples.md     # REQUIRED
           └── smells.md       # Optional
   

2. Create progress.md

   • List ALL files to create (required + optional)
   • Group by phase/priority
   • Track completion status

3. Plan extraction tasks

   • One task per knowledge file
   • Define input (book section with line ranges) and output (file path)
   • Identify dependencies between tasks

4. Ask user to confirm the file structure and extraction plan before proceeding

---

Phase 3: Extraction

STOP! Before proceeding, you MUST:

1. Have completed Phase 1 and Phase 2
2. Have user confirmation on the plan
3. Only then proceed with extraction

CRITICAL: You MUST use subagents (Task tool) for extraction. One subagent per topic - each subagent creates ALL files for that topic.

Main Agent Instructions for Phase 3

YOU MUST follow these steps:

1. One subagent per topic - Each subagent reads a book section ONCE and creates all files for that topic (knowledge.md, rules.md, examples.md, plus any optional files)
2. Prepare the subagent prompt by filling in the template below with specific values
3. Calculate line ranges from your Phase 1 analysis (TOC with line numbers)
4. Create the complete prompt - do NOT leave placeholders unfilled
5. Launch subagents in parallel for different topics
6. Update progress.md after all subagents complete

Subagent Prompt Template

IMPORTANT: Copy this template and replace ALL bracketed placeholders with actual values before launching subagent.

## Task: Extract [TOPIC] Knowledge Base

You are extracting knowledge from a book section to create a complete topic reference.

### Prerequisites - Read These Files First:
1. `skills/skill-from-book/references/file-templates.md` - Templates for all file types
2. `skills/skill-from-book/references/extraction-patterns.md` - Extraction rules

### Source Material:
- **Book**: [BOOK_PATH]
- **Section**: [CHAPTER/SECTION_NAME]
- **Line range**: Read with offset=[START_LINE], limit=[LINE_COUNT]

### Output Directory: [OUTPUT_TOPIC_PATH]

### Files to Create (in this order):

#### 1. knowledge.md (REQUIRED)
Core concepts, definitions, and foundational understanding.
- Extract: definitions, terminology, key concepts, how things relate
- Use the "Knowledge File" template

#### 2. rules.md (REQUIRED)
Specific guidelines, do's and don'ts.
- Extract: explicit rules, guidelines, best practices, exceptions
- Use the "Rules File" template

#### 3. examples.md (REQUIRED)
Good/bad code examples, before/after comparisons.
- Extract: all code samples, refactoring examples, comparisons
- Use the "Examples File" template

#### 4. [OPTIONAL_FILES - list any additional files needed]
[e.g., patterns.md, smells.md, checklist.md - specify what each should contain]

### Your Instructions:
1. Read the two prerequisite files FIRST to understand templates and extraction rules
2. Read the book section ONCE using: offset=[START_LINE], limit=[LINE_COUNT]
3. From that single read, extract content for ALL files listed above
4. For each file:
   - Transform content (prose → bullets, extract rules, include examples)
   - Format using the appropriate template from file-templates.md
   - Keep each file under 200 lines
   - Write to [OUTPUT_TOPIC_PATH]/[filename].md
5. Create files in order: knowledge.md → rules.md → examples.md → optional files

### Content Guidance:
[SPECIFIC_GUIDANCE - what to focus on, what to skip]

### Language Conversion (if applicable):
- Source: [SOURCE_LANG or "N/A"]
- Target: [TARGET_LANG or "N/A"]
- Convert ALL code examples to target language

Example: Filled Subagent Prompt

## Task: Extract Functions Knowledge Base

You are extracting knowledge from a book section to create a complete topic reference.

### Prerequisites - Read These Files First:
1. `skills/skill-from-book/references/file-templates.md` - Templates for all file types
2. `skills/skill-from-book/references/extraction-patterns.md` - Extraction rules

### Source Material:
- **Book**: /path/to/clean-code.md
- **Section**: Chapter 3 - Functions
- **Line range**: Read with offset=450, limit=380

### Output Directory: skills/clean-code/references/functions

### Files to Create (in this order):

#### 1. knowledge.md (REQUIRED)
Core concepts, definitions, and foundational understanding.
- Extract: what makes a function clean, key terminology (side effects, arguments, abstraction levels), how functions relate to other concepts
- Use the "Knowledge File" template

#### 2. rules.md (REQUIRED)
Specific guidelines, do's and don'ts.
- Extract: size rules, argument limits, naming conventions, single responsibility, do one thing principle
- Use the "Rules File" template

#### 3. examples.md (REQUIRED)
Good/bad code examples, before/after comparisons.
- Extract: all code samples showing good vs bad functions, refactoring walkthroughs
- Use the "Examples File" template

#### 4. checklist.md (OPTIONAL)
Quick reference for reviewing functions.
- Create a checklist from the rules for code review

### Your Instructions:
1. Read the two prerequisite files FIRST to understand templates and extraction rules
2. Read the book section ONCE using: offset=450, limit=380
3. From that single read, extract content for ALL files listed above
4. For each file:
   - Transform content (prose → bullets, extract rules, include examples)
   - Format using the appropriate template from file-templates.md
   - Keep each file under 200 lines
   - Write to skills/clean-code/references/functions/[filename].md
5. Create files in order: knowledge.md → rules.md → examples.md → checklist.md

### Content Guidance:
Focus on practical, actionable content. Skip author anecdotes and historical context. Prioritize rules that are universally applicable.

### Language Conversion:
- Source: Java
- Target: TypeScript
- Convert ALL code examples to TypeScript

Parallel Extraction Strategy

Run in parallel: Different topics (each handled by one subagent)

• Subagent 1: functions/ (Chapter 3)
• Subagent 2: naming/ (Chapter 2)
• Subagent 3: classes/ (Chapter 10)

Must wait: guidelines.md and workflows creation waits for ALL topic subagents to complete

Main Agent Checklist Before Launching Subagent

• All placeholders replaced with actual values
• Line offset and limit calculated from Phase 1 TOC
• Output directory path follows naming convention
• All required files (knowledge.md, rules.md, examples.md) listed
• Optional files specified with clear content guidance
• Content guidance is specific to this topic
• Language conversion specified if needed

---

Phase 4: Guidelines Creation

STOP! Before proceeding, you MUST:

1. Have completed all extraction tasks in Phase 3
2. Read references/guidelines-template.md completely
3. Only then proceed with guidelines creation

Phase 4 Steps:

Create guidelines.md that maps:

• Tasks → relevant files (and workflows)
• Code elements → relevant files
• Symptoms/problems → relevant files
• Decision trees for common scenarios

---

Phase 5: Workflow Proposal

STOP! Before proceeding, you MUST:

1. Have completed Phase 4 (Guidelines)
2. Read references/workflow-templates.md completely
3. Only then proceed with workflow proposal

Phase 5 Steps:

1. Identify potential workflows from the book content

   Look for:

   • Process descriptions ("how to do X")
   • Repeated tasks (mentioned multiple times)
   • Checklists in the book
   • Anti-pattern sections (imply correct process)
   • Multi-step procedures

2. Propose workflows to user

   Present a list of potential workflows:

   Based on the book content, I recommend these workflows:
   
   | Workflow | Purpose | Key Steps |
   |----------|---------|-----------|
   | [name] | [what it does] | [brief step summary] |
   | [name] | [what it does] | [brief step summary] |
   

3. Ask user to select which workflows to create

   Which workflows would you like me to create?
   - Select from the list above
   - Suggest additional workflows
   - Skip workflow creation
   

4. Create selected workflows

   For each selected workflow:

   • Use the template from references/workflow-templates.md
   • Include cross-references to relevant knowledge files
   • Add checkboxes for each step
   • Define clear exit criteria

5. Update guidelines.md to include workflow references

   Add a "Workflows" section at the top of guidelines.md:

   ## Workflows
   
   | Task | Workflow |
   |------|----------|
   | [task description] | `workflows/[name].md` |
   

---

Phase 6: Finalization

Phase 6 Steps:

1. Review all files for consistency
2. Update progress.md (mark complete)
3. Test with sample queries
4. Refine guidelines based on testing
5. Ask user to review the final skill

---

Key Principles

Granularity

• One concept per file
• Files should be 50-200 lines
• Split large topics into subtopics

Context Efficiency

• Only load what's needed
• Guidelines file routes to specific knowledge
• Avoid duplication across files

Actionable Content

• Rules over explanations
• Examples over theory
• Checklists for quick reference
• Workflows for repeatable tasks

Subagent-Friendly

• Each extraction task is independent
• Clear input/output specification
• Can run multiple extractions in parallel

File Naming Conventions

skill-name/
├── SKILL.md
├── guidelines.md
├── progress.md
├── workflows/                # Step-by-step processes
│   ├── [verb]-[noun].md      # e.g., code-review.md, bug-fix.md
│   └── ...
└── references/
    ├── [category]/           # Noun, plural (e.g., functions, classes)
    │   ├── knowledge.md      # REQUIRED: Core concepts and definitions
    │   ├── rules.md          # REQUIRED: Specific guidelines
    │   ├── examples.md       # REQUIRED: Good/bad examples
    │   ├── patterns.md       # Optional: Reusable solutions
    │   ├── smells.md         # Optional: Anti-patterns
    │   └── checklist.md      # Optional: Quick reference

Progress Tracking

Always maintain progress.md:

# [Skill Name] - Creation Progress

## Status: [X/Y files complete]

## Phase 1: Foundation
- [x] SKILL.md
- [x] progress.md
- [ ] guidelines.md

## Phase 2: Workflows
- [ ] workflows/[name].md
- [ ] workflows/[name].md

## Phase 3: [Category Name]
- [ ] category/knowledge.md   # REQUIRED
- [ ] category/rules.md       # REQUIRED
- [ ] category/examples.md    # REQUIRED
- [ ] category/patterns.md    # Optional
...

Quick Start

1. User provides the book markdown file path
2. DO NOT read the book content yet
3. Run Phase 1: Analysis (extract TOC only)
4. Get user confirmation
5. Run Phase 2: Planning
6. Get user confirmation
7. Run Phase 3: Extraction (use subagents)
8. Run Phase 4: Guidelines Creation
9. Run Phase 5: Workflow Proposal (get user selection)
10. Run Phase 6: Finalization