Personal AI infrastructure with learning-enabled assistance for work, travel, and personal tasks

version
0.26.0
GitHub stars
9

Install

/plugin install geoffrey@geoffrey

Run it inside Claude Code after adding the marketplace with /plugin marketplace add krishagel/geoffrey.

Contents

Discovered from source

Skills 33

Assistant Architect

Create valid JSON import files for PSD AI Studio's Assistant Architect system.

Spec Reference: See references/json-spec.md for complete field definitions and validation rules.


Input Modes

From Screenshot

When the user provides a screenshot, extract:

ElementMaps To
Text input boxesshort_text (single line) or long_text (multi-line)
Dropdowns/select menusselect with choices from visible options
Checkboxes/multi-selectmulti_select
File upload areasfile_upload
Field labelslabel property
Placeholder textoptions.placeholder
Visible instructionssystem_context or prompt content
Step numbers/tabsMultiple prompts in sequence

Also infer:

  • Assistant name from title/header
  • Description from any visible purpose text
  • Prompt content from visible instructions or "what this does" text

Handling Collapsed Dropdowns

CRITICAL: When you see a dropdown in a screenshot but can't see its options (e.g., shows "Select subject" or has a dropdown arrow but options aren't expanded), you MUST resolve the options before generating JSON.

Resolution order:

  1. Check if it matches a Common Field Library (see below)

    • "Grade", "Grade Level" → Use Grade Levels library
    • "Subject", "Content Area" → Use Subjects library
    • "State" → Use US States library
    • "Language" → Use Language library
    • "Tone", "Style" → Use Writing Tone library
    • "Format", "Output Format" → Use Output Format library
  2. If no library match, ASK the user:

    I see a dropdown for "[Field Name]" but can't see the options.
    
    Options:
    a) Provide a screenshot with the dropdown expanded
    b) List the values that should appear (comma-separated)
    c) Describe the type of options (e.g., "departments in our district")
    
  3. Never leave a select field without choices - this will cause import errors

Visual indicators of dropdowns:

  • Dropdown arrow (▼ or chevron) on right side
  • "Select..." placeholder text
  • Bordered box that looks clickable but isn't a text input
  • Different styling from text inputs (often lighter/grayed placeholder)

From Description (Dictation/Rambling)

Parse unstructured input for:

Look ForMaps To
"user provides/enters/types..."Input field
"asks for/needs a..."Input field
"choose from/select/pick..."select field
"upload/attach file..."file_upload field
"then/next/after that..."Additional prompt (chained)
"analyze/summarize/write/create..."Prompt purpose
"should be/must be/format as..."System context or prompt instructions

Smart Defaults

When not specified, use:

DecisionDefault
Modelgpt-4o (complex tasks), gpt-4o-mini (simple Q&A)
Field type for textlong_text with 6 rows
ExecutionSequential (single prompt unless steps mentioned)
Timeoutsnull (system default)
Required fieldstrue for primary input, false for options

Workflow

1. Gather Requirements

If screenshot provided: Extract all visible elements per the table above.

If description provided: Parse for inputs, outputs, and flow.

If unclear or incomplete: Ask targeted questions:

  • What should the assistant do?
  • What inputs does it need?
  • Single or multi-step?

1.5 Resolve All Dropdown Options (REQUIRED)

Before generating JSON, ensure every dropdown has defined options.

For each dropdown/select field identified:

If...Then...
Options are visible in screenshotExtract them exactly
Field matches a Common Field LibraryUse the library options
Field is domain-specific (e.g., "Department", "Building", "Program")ASK the user for the list
Unclear what options should beASK the user

Example question format:

I found these dropdowns that need options defined:

1. **Department** - What departments should be listed?
2. **Building** - What buildings/schools should be included?
3. **Program Type** - What program types exist?

You can provide comma-separated values, or share a screenshot with dropdowns expanded.

Do NOT proceed to JSON generation with unresolved dropdowns.

2. Design the Assistant

Based on requirements, determine:

DecisionOptions
Execution patternSequential (default) / Parallel / Multi-level
Model selectiongpt-4o (complex) / gpt-4o-mini (simple) / claude-3-5-sonnet
Input fieldsshort_text, long_text, select, multi_select, file_upload
TimeoutsDefault null, max 900 seconds

3. Generate JSON

Build the JSON structure:

{
  "version": "1.0",
  "exported_at": "[ISO-8601 timestamp]",
  "export_source": "Geoffrey Assistant Architect",
  "assistants": [{
    "name": "[Assistant Name]",
    "description": "[Purpose]",
    "prompts": [...],
    "input_fields": [...]
  }]
}

4. Write the File

Save to user's preferred location (default: ~/Downloads/[assistant-name].json).


Quick Patterns

Simple Q&A Assistant

{
  "version": "1.0",
  "export_source": "Geoffrey Assistant Architect",
  "assistants": [{
    "name": "Quick Helper",
    "description": "Answers questions clearly",
    "prompts": [{
      "name": "answer",
      "content": "Answer this question:\n\n${question}",
      "system_context": "You are a helpful expert.",
      "model_name": "gpt-4o-mini",
      "position": 0
    }],
    "input_fields": [{
      "name": "question",
      "label": "Your Question",
      "field_type": "long_text",
      "position": 0,
      "options": { "required": true, "rows": 6 }
    }]
  }]
}

Multi-Level Parallel (Solo → Parallel → Synthesis)

Prompts at the same position with different parallel_group values run simultaneously. Parallel prompts can only reference outputs from earlier positions, never from other prompts at the same position.

{
  "prompts": [
    {
      "name": "framing",
      "content": "Frame the key issues in this document:\n\n${document}",
      "model_name": "gpt-4o",
      "position": 0,
      "parallel_group": null
    },
    {
      "name": "strengths",
      "content": "Based on this framing:\n\n${prompt_0_output}\n\nIdentify strengths and opportunities.",
      "model_name": "gpt-4o",
      "position": 1,
      "parallel_group": 1000
    },
    {
      "name": "risks",
      "content": "Based on this framing:\n\n${prompt_0_output}\n\nIdentify risks and weaknesses.",
      "model_name": "gpt-4o",
      "position": 1,
      "parallel_group": 1001
    },
    {
      "name": "synthesis",
      "content": "Synthesize these perspectives:\n\nStrengths: ${prompt_1_output}\n\nRisks: ${prompt_2_output}",
      "model_name": "gpt-4o",
      "position": 2,
      "parallel_group": null
    }
  ]
}

Key rules:

  • parallel_group = null → solo prompt (runs alone at its position)
  • parallel_group = unique number → runs in parallel with other prompts at same position
  • Parallel prompts reference ${prompt_N_output} from earlier positions ONLY
  • The synthesis prompt (position 2) can reference all earlier prompt outputs
  • Alternative syntax: Instead of ${prompt_N_output}, you can use ${slugified-prompt-name} (e.g., ${framing} for a prompt named "framing"). Both ${...} and {{...}} delimiters work.

Transform with Options

{
  "prompts": [{
    "name": "transform",
    "content": "Rewrite in ${style} style:\n\n${content}",
    "model_name": "gpt-4o",
    "position": 0
  }],
  "input_fields": [
    {
      "name": "content",
      "label": "Content",
      "field_type": "long_text",
      "position": 0
    },
    {
      "name": "style",
      "label": "Writing Style",
      "field_type": "select",
      "position": 1,
      "options": {
        "choices": [
          { "value": "formal", "label": "Formal" },
          { "value": "casual", "label": "Casual" },
          { "value": "technical", "label": "Technical" }
        ],
        "default": "formal"
      }
    }
  ]
}

Validation Checklist

Before writing the file, verify:

  • version is "1.0"
  • Each assistant has name (min 3 chars), prompts, input_fields
  • Each prompt has name, content, model_name, position
  • Each input field has name, label, field_type, position
  • position values are sequential starting from 0
  • All ${variables} match input field names, prompt_N_output, or slugified prompt names
  • CRITICAL: Every select and multi_select field has options.choices array with at least 2 items
  • No dropdown was left with placeholder options like "Option 1", "Option 2"
  • Domain-specific dropdowns (departments, buildings, programs) have real values from user

Common Models

Use CaseModel
Complex analysisgpt-4o
Simple tasksgpt-4o-mini
Long contextclaude-3-5-sonnet
Fast responsesgemini-1.5-flash

Common Field Libraries

CRITICAL: When a field represents a finite set of choices (grade levels, subjects, states, etc.), ALWAYS use select or multi_select with proper options—NEVER use short_text or long_text.

Detecting Select Fields

If the screenshot or description contains ANY of these patterns, use a select field:

PatternField Type
"Select...", "Choose...", dropdown arrowselect
"Pick one", "Which...", finite listselect
"Check all that apply", multiple checkboxesmulti_select
Grade level, subject, state, language, formatselect (use library below)

Grade Levels (K-12)

{
  "name": "grade_level",
  "label": "Grade Level",
  "field_type": "select",
  "options": {
    "required": true,
    "choices": [
      { "value": "Pre-K", "label": "Pre-K" },
      { "value": "Kindergarten", "label": "Kindergarten" },
      { "value": "1st Grade", "label": "1st Grade" },
      { "value": "2nd Grade", "label": "2nd Grade" },
      { "value": "3rd Grade", "label": "3rd Grade" },
      { "value": "4th Grade", "label": "4th Grade" },
      { "value": "5th Grade", "label": "5th Grade" },
      { "value": "6th Grade", "label": "6th Grade" },
      { "value": "7th Grade", "label": "7th Grade" },
      { "value": "8th Grade", "label": "8th Grade" },
      { "value": "9th Grade", "label": "9th Grade" },
      { "value": "10th Grade", "label": "10th Grade" },
      { "value": "11th Grade", "label": "11th Grade" },
      { "value": "12th Grade", "label": "12th Grade" }
    ]
  }
}

Subjects (K-12)

{
  "name": "subject",
  "label": "Subject",
  "field_type": "select",
  "options": {
    "required": true,
    "choices": [
      { "value": "English Language Arts", "label": "English Language Arts" },
      { "value": "Mathematics", "label": "Mathematics" },
      { "value": "Science", "label": "Science" },
      { "value": "Social Studies", "label": "Social Studies" },
      { "value": "History", "label": "History" },
      { "value": "World Languages", "label": "World Languages" },
      { "value": "Physical Education", "label": "Physical Education" },
      { "value": "Health", "label": "Health" },
      { "value": "Visual Arts", "label": "Visual Arts" },
      { "value": "Music", "label": "Music" },
      { "value": "Theater/Drama", "label": "Theater/Drama" },
      { "value": "Computer Science", "label": "Computer Science" },
      { "value": "Career & Technical Education", "label": "Career & Technical Education" },
      { "value": "Special Education", "label": "Special Education" },
      { "value": "Library/Media", "label": "Library/Media" },
      { "value": "Counseling", "label": "Counseling" },
      { "value": "Other", "label": "Other" }
    ]
  }
}

US States

{
  "name": "state",
  "label": "State",
  "field_type": "select",
  "options": {
    "required": true,
    "default": "Washington",
    "choices": [
      { "value": "Alabama", "label": "Alabama" },
      { "value": "Alaska", "label": "Alaska" },
      { "value": "Arizona", "label": "Arizona" },
      { "value": "Arkansas", "label": "Arkansas" },
      { "value": "California", "label": "California" },
      { "value": "Colorado", "label": "Colorado" },
      { "value": "Connecticut", "label": "Connecticut" },
      { "value": "Delaware", "label": "Delaware" },
      { "value": "Florida", "label": "Florida" },
      { "value": "Georgia", "label": "Georgia" },
      { "value": "Hawaii", "label": "Hawaii" },
      { "value": "Idaho", "label": "Idaho" },
      { "value": "Illinois", "label": "Illinois" },
      { "value": "Indiana", "label": "Indiana" },
      { "value": "Iowa", "label": "Iowa" },
      { "value": "Kansas", "label": "Kansas" },
      { "value": "Kentucky", "label": "Kentucky" },
      { "value": "Louisiana", "label": "Louisiana" },
      { "value": "Maine", "label": "Maine" },
      { "value": "Maryland", "label": "Maryland" },
      { "value": "Massachusetts", "label": "Massachusetts" },
      { "value": "Michigan", "label": "Michigan" },
      { "value": "Minnesota", "label": "Minnesota" },
      { "value": "Mississippi", "label": "Mississippi" },
      { "value": "Missouri", "label": "Missouri" },
      { "value": "Montana", "label": "Montana" },
      { "value": "Nebraska", "label": "Nebraska" },
      { "value": "Nevada", "label": "Nevada" },
      { "value": "New Hampshire", "label": "New Hampshire" },
      { "value": "New Jersey", "label": "New Jersey" },
      { "value": "New Mexico", "label": "New Mexico" },
      { "value": "New York", "label": "New York" },
      { "value": "North Carolina", "label": "North Carolina" },
      { "value": "North Dakota", "label": "North Dakota" },
      { "value": "Ohio", "label": "Ohio" },
      { "value": "Oklahoma", "label": "Oklahoma" },
      { "value": "Oregon", "label": "Oregon" },
      { "value": "Pennsylvania", "label": "Pennsylvania" },
      { "value": "Rhode Island", "label": "Rhode Island" },
      { "value": "South Carolina", "label": "South Carolina" },
      { "value": "South Dakota", "label": "South Dakota" },
      { "value": "Tennessee", "label": "Tennessee" },
      { "value": "Texas", "label": "Texas" },
      { "value": "Utah", "label": "Utah" },
      { "value": "Vermont", "label": "Vermont" },
      { "value": "Virginia", "label": "Virginia" },
      { "value": "Washington", "label": "Washington" },
      { "value": "West Virginia", "label": "West Virginia" },
      { "value": "Wisconsin", "label": "Wisconsin" },
      { "value": "Wyoming", "label": "Wyoming" },
      { "value": "District of Columbia", "label": "District of Columbia" }
    ]
  }
}

Learning Standards Frameworks

{
  "name": "standards_framework",
  "label": "Standards Framework",
  "field_type": "select",
  "options": {
    "required": false,
    "choices": [
      { "value": "Common Core State Standards (CCSS)", "label": "Common Core State Standards (CCSS)" },
      { "value": "Next Generation Science Standards (NGSS)", "label": "Next Generation Science Standards (NGSS)" },
      { "value": "C3 Framework (Social Studies)", "label": "C3 Framework (Social Studies)" },
      { "value": "ISTE Standards", "label": "ISTE Standards (Technology)" },
      { "value": "National Core Arts Standards", "label": "National Core Arts Standards" },
      { "value": "SHAPE America Standards (PE/Health)", "label": "SHAPE America Standards (PE/Health)" },
      { "value": "ACTFL Standards (World Languages)", "label": "ACTFL Standards (World Languages)" },
      { "value": "State-Specific Standards", "label": "State-Specific Standards" },
      { "value": "Other", "label": "Other" }
    ]
  }
}

Writing Tone/Style

{
  "name": "tone",
  "label": "Tone",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "professional", "label": "Professional" },
      { "value": "friendly", "label": "Friendly" },
      { "value": "formal", "label": "Formal" },
      { "value": "casual", "label": "Casual" },
      { "value": "encouraging", "label": "Encouraging" },
      { "value": "academic", "label": "Academic" },
      { "value": "conversational", "label": "Conversational" }
    ],
    "default": "professional"
  }
}

Output Format

{
  "name": "output_format",
  "label": "Output Format",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "paragraph", "label": "Paragraph" },
      { "value": "bullet_points", "label": "Bullet Points" },
      { "value": "numbered_list", "label": "Numbered List" },
      { "value": "table", "label": "Table" },
      { "value": "outline", "label": "Outline" }
    ],
    "default": "paragraph"
  }
}

Length/Detail Level

{
  "name": "length",
  "label": "Length",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "brief", "label": "Brief (1-2 sentences)" },
      { "value": "short", "label": "Short (1 paragraph)" },
      { "value": "medium", "label": "Medium (2-3 paragraphs)" },
      { "value": "detailed", "label": "Detailed (comprehensive)" }
    ],
    "default": "medium"
  }
}

Audience

{
  "name": "audience",
  "label": "Audience",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "students", "label": "Students" },
      { "value": "parents", "label": "Parents/Guardians" },
      { "value": "teachers", "label": "Teachers" },
      { "value": "administrators", "label": "Administrators" },
      { "value": "school_board", "label": "School Board" },
      { "value": "community", "label": "Community Members" },
      { "value": "general", "label": "General Audience" }
    ]
  }
}

Language (for multilingual support)

{
  "name": "language",
  "label": "Output Language",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "English", "label": "English" },
      { "value": "Spanish", "label": "Spanish" },
      { "value": "Vietnamese", "label": "Vietnamese" },
      { "value": "Chinese (Simplified)", "label": "Chinese (Simplified)" },
      { "value": "Chinese (Traditional)", "label": "Chinese (Traditional)" },
      { "value": "Korean", "label": "Korean" },
      { "value": "Tagalog", "label": "Tagalog" },
      { "value": "Russian", "label": "Russian" },
      { "value": "Arabic", "label": "Arabic" },
      { "value": "Somali", "label": "Somali" },
      { "value": "Ukrainian", "label": "Ukrainian" }
    ],
    "default": "English"
  }
}

K-12 District-Specific Field Libraries

SCOPE: Use these libraries ONLY when building AI Studio assistants for educational/instructional purposes (lesson plans, assessments, student feedback, curriculum tools, etc.).

Pedagogical alignment: For educational assistants, reference PSD's Instructional Essentials skill (/psd-instructional-vision) to ensure alignment with district beliefs about rigor, inclusion, data-driven decisions, and innovation.

ELA Standards Domains

{
  "name": "ela_domain",
  "label": "ELA Domain",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Reading Literature", "label": "Reading Literature" },
      { "value": "Reading Informational Text", "label": "Reading Informational Text" },
      { "value": "Reading Foundational Skills", "label": "Reading Foundational Skills" },
      { "value": "Writing", "label": "Writing" },
      { "value": "Speaking and Listening", "label": "Speaking and Listening" },
      { "value": "Language", "label": "Language" }
    ]
  }
}

Math Standards Domains

{
  "name": "math_domain",
  "label": "Math Domain",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Counting and Cardinality", "label": "Counting and Cardinality (K)" },
      { "value": "Operations and Algebraic Thinking", "label": "Operations and Algebraic Thinking" },
      { "value": "Number and Operations in Base Ten", "label": "Number and Operations in Base Ten" },
      { "value": "Number and Operations - Fractions", "label": "Number and Operations - Fractions" },
      { "value": "Measurement and Data", "label": "Measurement and Data" },
      { "value": "Geometry", "label": "Geometry" },
      { "value": "Ratios and Proportional Relationships", "label": "Ratios and Proportional Relationships" },
      { "value": "The Number System", "label": "The Number System" },
      { "value": "Expressions and Equations", "label": "Expressions and Equations" },
      { "value": "Functions", "label": "Functions" },
      { "value": "Statistics and Probability", "label": "Statistics and Probability" }
    ]
  }
}

Science Standards Domains (NGSS)

{
  "name": "science_domain",
  "label": "Science Domain",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Physical Science", "label": "Physical Science" },
      { "value": "Life Science", "label": "Life Science" },
      { "value": "Earth and Space Science", "label": "Earth and Space Science" },
      { "value": "Engineering Design", "label": "Engineering Design" }
    ]
  }
}

Grade Bands

{
  "name": "grade_band",
  "label": "Grade Band",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "K-2", "label": "K-2 (Primary)" },
      { "value": "3-5", "label": "3-5 (Intermediate)" },
      { "value": "6-8", "label": "6-8 (Middle School)" },
      { "value": "9-12", "label": "9-12 (High School)" }
    ]
  }
}

Student Population / Learner Characteristics

{
  "name": "student_population",
  "label": "Student Population",
  "field_type": "multi_select",
  "options": {
    "choices": [
      { "value": "General Education", "label": "General Education" },
      { "value": "English Learners (EL/MLL)", "label": "English Learners (EL/MLL)" },
      { "value": "Students with IEPs", "label": "Students with IEPs" },
      { "value": "Students with 504 Plans", "label": "Students with 504 Plans" },
      { "value": "Highly Capable", "label": "Highly Capable/Gifted" },
      { "value": "At-Risk", "label": "At-Risk/Tier 2-3" }
    ]
  }
}

Instructional Model (aligned with PSD Tier 1 practices)

{
  "name": "instructional_model",
  "label": "Instructional Model",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Whole Group", "label": "Whole Group Direct Instruction" },
      { "value": "Small Group", "label": "Small Group (Flexible Grouping)" },
      { "value": "Stations/Centers", "label": "Stations/Learning Centers" },
      { "value": "Workshop Model", "label": "Workshop Model (Mini-lesson → Work Time → Share)" },
      { "value": "Guided Practice", "label": "Gradual Release (I Do, We Do, You Do)" },
      { "value": "Inquiry-Based", "label": "Inquiry-Based/Project-Based" },
      { "value": "Flipped", "label": "Flipped Classroom" },
      { "value": "Co-Teaching", "label": "Co-Teaching" }
    ]
  }
}

Assessment Type (aligned with Data-Driven Decisions essential)

{
  "name": "assessment_type",
  "label": "Assessment Type",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Formative - Exit Ticket", "label": "Formative - Exit Ticket" },
      { "value": "Formative - Check for Understanding", "label": "Formative - Check for Understanding" },
      { "value": "Formative - Observation", "label": "Formative - Observation/Anecdotal" },
      { "value": "Formative - Student Self-Assessment", "label": "Formative - Student Self-Assessment" },
      { "value": "Summative - Unit Test", "label": "Summative - Unit Test" },
      { "value": "Summative - Project/Performance", "label": "Summative - Project/Performance Task" },
      { "value": "Summative - Portfolio", "label": "Summative - Portfolio" },
      { "value": "Benchmark/Interim", "label": "Benchmark/Interim Assessment" },
      { "value": "Diagnostic", "label": "Diagnostic/Pre-Assessment" }
    ]
  }
}

Lesson Duration

{
  "name": "lesson_duration",
  "label": "Lesson Duration",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "15-20 minutes", "label": "15-20 minutes (Mini-lesson)" },
      { "value": "30 minutes", "label": "30 minutes" },
      { "value": "45 minutes", "label": "45 minutes (Standard period)" },
      { "value": "60 minutes", "label": "60 minutes" },
      { "value": "90 minutes", "label": "90 minutes (Block)" },
      { "value": "Multi-day", "label": "Multi-day lesson" }
    ]
  }
}

Bloom's Taxonomy Level (Depth of Knowledge)

{
  "name": "cognitive_level",
  "label": "Cognitive Level",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Remember", "label": "Remember (Recall facts)" },
      { "value": "Understand", "label": "Understand (Explain ideas)" },
      { "value": "Apply", "label": "Apply (Use in new situations)" },
      { "value": "Analyze", "label": "Analyze (Draw connections)" },
      { "value": "Evaluate", "label": "Evaluate (Justify decisions)" },
      { "value": "Create", "label": "Create (Produce new work)" }
    ]
  }
}

Depth of Knowledge (Webb's DOK)

{
  "name": "dok_level",
  "label": "Depth of Knowledge",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "DOK 1", "label": "DOK 1 - Recall" },
      { "value": "DOK 2", "label": "DOK 2 - Skill/Concept" },
      { "value": "DOK 3", "label": "DOK 3 - Strategic Thinking" },
      { "value": "DOK 4", "label": "DOK 4 - Extended Thinking" }
    ]
  }
}

Educator Role

{
  "name": "role",
  "label": "Role",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Classroom Teacher", "label": "Classroom Teacher" },
      { "value": "Special Education Teacher", "label": "Special Education Teacher" },
      { "value": "EL/MLL Specialist", "label": "EL/MLL Specialist" },
      { "value": "Instructional Coach", "label": "Instructional Coach" },
      { "value": "Counselor", "label": "School Counselor" },
      { "value": "Librarian", "label": "Teacher-Librarian" },
      { "value": "Paraeducator", "label": "Paraeducator/IA" },
      { "value": "Principal", "label": "Principal" },
      { "value": "Assistant Principal", "label": "Assistant Principal" },
      { "value": "District Staff", "label": "District Staff" }
    ]
  }
}

School Level

{
  "name": "school_level",
  "label": "School Level",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Elementary", "label": "Elementary School" },
      { "value": "Middle", "label": "Middle School" },
      { "value": "High", "label": "High School" },
      { "value": "K-8", "label": "K-8 School" },
      { "value": "Alternative", "label": "Alternative School" },
      { "value": "District-Wide", "label": "District-Wide" }
    ]
  }
}

Communication Type

{
  "name": "communication_type",
  "label": "Communication Type",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Parent Newsletter", "label": "Parent Newsletter" },
      { "value": "Parent Email", "label": "Parent Email" },
      { "value": "Student Feedback", "label": "Student Feedback" },
      { "value": "IEP/504 Communication", "label": "IEP/504 Communication" },
      { "value": "Behavior Communication", "label": "Behavior Communication" },
      { "value": "Progress Report", "label": "Progress Report" },
      { "value": "Staff Communication", "label": "Staff Communication" },
      { "value": "Community Announcement", "label": "Community Announcement" }
    ]
  }
}

Quarter/Trimester

{
  "name": "grading_period",
  "label": "Grading Period",
  "field_type": "select",
  "options": {
    "choices": [
      { "value": "Q1", "label": "Quarter 1" },
      { "value": "Q2", "label": "Quarter 2" },
      { "value": "Q3", "label": "Quarter 3" },
      { "value": "Q4", "label": "Quarter 4" },
      { "value": "Semester 1", "label": "Semester 1" },
      { "value": "Semester 2", "label": "Semester 2" },
      { "value": "Full Year", "label": "Full Year" },
      { "value": "Summer", "label": "Summer" }
    ]
  }
}

Making Reasonable Assumptions

For general assistants: Use the Common Field Libraries (grade, subject, state, tone, format, etc.).

For educational/instructional assistants: Use the K-12 District-Specific Field Libraries above AND invoke the PSD Instructional Vision skill (/psd-instructional-vision) for pedagogical alignment.

Educational Assistant Decision Framework

When a dropdown's options aren't visible in a screenshot for an educational tool:

Field TypeAssumption Strategy
Grade/Subject/StateUse Common Field Libraries
StandardsUse domain-level dropdowns (ELA, Math, Science domains) + text for specific codes
Roles/PositionsUse Educator Role library
Time/DurationUse Lesson Duration or Grading Period library
AssessmentUse Assessment Type library
Instructional approachUse Instructional Model library
Student groupsUse Student Population library
Cognitive rigorUse Bloom's or DOK library
District-specific (buildings, departments)Ask user - these vary by district

PSD Instructional Essentials Alignment

When building educational AI Studio assistants, ensure options align with PSD's four essentials:

  • Rigor & Inclusion → Include scaffolding options, differentiation choices, support for all learners
  • Data-Driven Decisions → Include assessment type options, formative check options
  • Continuous Growth → Include reflection prompts, self-assessment, goal-setting options
  • Innovation → Include technology integration, real-world connection, student voice options

Output

Write the JSON file to the user's specified path or ~/Downloads/[kebab-case-name].json.

Confirm:

  • File path written
  • Assistant name and purpose
  • Number of prompts and input fields
  • Next step: Import via AI Studio → Assistants → Import

CFO Daily Briefing Workflow

Overview

Generates a daily briefing for CFO Ashley Murphy and delivers it via:

  1. Terminal: Summary displayed immediately
  2. Email: HTML briefing with inline absence infographic + podcast attachment

No Obsidian vault writing. This skill produces email-only output.

Location

  • Gig Harbor, WA - Use for weather queries

Audience

  • Ashley Murphy - Chief Financial Officer, Peninsula School District
  • Framing: Financial impact, staffing costs, departmental operations, fiscal legislation

Phase 1: Gather Data

Execute these data gathering steps:

1.1 Red Rover - All Staff Absences

bun /Users/hagelk/non-ic-code/geoffrey/skills/redrover-manager/scripts/get_daily_summary.js today

Returns: total_absences, filled, unfilled, fill_rate, by_school, by_reason, by_position_type, unfilled_positions[]

1.2 Red Rover - Certificated Only

bun /Users/hagelk/non-ic-code/geoffrey/skills/redrover-manager/scripts/get_certificated_summary.js today

Returns: same shape as 1.1 but filtered to Teacher, ESA - Certificated, CTE - Teacher position types.

1.3 Classified (Derived)

Do not run a script. Subtract certificated values from all-staff values in the orchestration layer:

  • classified_absences = all_absences - cert_absences
  • classified_filled = all_filled - cert_filled
  • classified_unfilled = all_unfilled - cert_unfilled
  • classified_fill_rate = classified_filled / classified_absences * 100 (handle divide-by-zero)

1.3b Red Rover - Weekly Trends

bun /Users/hagelk/non-ic-code/geoffrey/skills/redrover-manager/scripts/get_weekly_summary.js 0

Provides 5-day trend context: daily averages, peak/slow days, fill rate trends. Used for "compared to this week's average" framing in the briefing.

1.4 FreshService - Transportation Tickets

bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/search_tickets.js "status:2 OR status:3" 9

Workspace ID: 9 (Transportation) Returns: count, tickets[] (id, subject, status, priority, created_at, due_by)

1.5 FreshService - Maintenance Tickets

bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/search_tickets.js "status:2 OR status:3" 6

Workspace ID: 6 (Maintenance) Returns: same shape as 1.4

1.6 FreshService - Employee Support Services Tickets

bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/search_tickets.js "status:2 OR status:3" 3

Workspace ID: 3 (Employee Support Services) Returns: same shape as 1.4

1.7 Legislative - Fiscal Focus

bun /Users/hagelk/non-ic-code/geoffrey/skills/legislative-tracker/scripts/get_recent_bill_activity.js --last-business-day

Workflow:

  1. Get the output from get_recent_bill_activity.js
  2. WebFetch each bill URL (batch 5-6 in parallel for speed)
  3. Extract latest action date from each bill page
  4. Filter to bills where latest_action_date >= lookback_start
  5. Prioritize bills with FISCAL impact type - these get detailed treatment
  6. Other bill types get brief mention only

Also pull Tier 2 finance committee bills:

bun /Users/hagelk/non-ic-code/geoffrey/skills/legislative-tracker/scripts/get_bills.js --tier 2 --format briefing

On Monday: Lookback starts on Friday (or earlier if Friday was a holiday), so includes all weekend activity.

1.8 K-12 Financial News

Use WebSearch with these queries (replace [MONTH YEAR] with current month/year):

  1. K-12 school district finance budget funding news past 24 hours [MONTH YEAR]
  2. Washington state education funding levy bond news [MONTH YEAR]
  3. WASBO Washington school business officials news [MONTH YEAR]
  4. OSPI fiscal budget allocation Washington state [MONTH YEAR]

WebFetch top 3-4 articles. Extract 2-3 sentence synopses for each:

  • What happened / what's new
  • Why it matters for K-12 finance
  • Key takeaway for a CFO

Freshness check: Verify article dates. Only include articles published within the last 48 hours. Skip older articles even if they appear in results.

1.9 Weather

Use WebSearch:

Gig Harbor WA weather today forecast

Extract:

  • Current conditions
  • High/low temperature
  • Precipitation chance
  • Any alerts

1.10 Calendar/Email (Simulated)

No API calls. This is a placeholder for future integration.

Display in the briefing:

Calendar and email integration pending. Check Outlook/Google Calendar directly.

Phase 2: Generate Content

2.1 Markdown Briefing

Build the briefing with these sections in order:

# CFO Daily Briefing - [DATE]

## Weather
[Current conditions, high/low, precipitation]

## CFO Calendar
*Calendar integration pending. Check Outlook/Google Calendar directly.*

## Staff Absences Dashboard

| Metric | All Staff | Certificated | Classified |
|--------|-----------|--------------|------------|
| Total Absences | X | Y | Z |
| Filled | X | Y | Z |
| Unfilled | X | Y | Z |
| Fill Rate | X% | Y% | Z% |

## Weekly Absence Trends
- This week's daily average: X absences
- Today vs average: [above/below/at average]
- Peak day this week: [day] with X absences
- Fill rate trend: [improving/declining/stable] (X% avg this week)

## Unfilled Positions
[If unfilled > 5, display attention alert]
[List unfilled positions with school, position type, and reason]

## Absences by School
| School | Total | Filled | Unfilled |
|--------|-------|--------|----------|
| ... | ... | ... | ... |

## Absences by Reason
| Reason | Count |
|--------|-------|
| ... | ... |

## Absences by Position Type
| Position Type | Count |
|---------------|-------|
| ... | ... |

## Department Tickets

### Transportation (Workspace 9) - [count] open
[List top tickets by priority with subject, status, created date]

### Maintenance (Workspace 6) - [count] open
[List top tickets by priority]

### Employee Support Services (Workspace 3) - [count] open
[List top tickets by priority]

## Legislative Fiscal Update

### FISCAL Impact Bills (Detailed)
[For each FISCAL bill with recent activity:]
**[Bill ID] - [Short Title]**
Action: [What happened]
Fiscal Impact: [Budget/funding implications]
Summary: [1-2 sentences]

### Other Education Bills (Brief)
- [Bill ID]: [Action] - [One line]

### Finance Committee Bills (Tier 2)
[Tier 2 bills from finance committees]

## K-12 Finance & WASBO/OSPI News

### [Article Title] - [Source]
[2-3 sentence synopsis with financial framing]

## Quick Stats
- Total absences: X (Cert: Y, Classified: Z)
- Fill rate: X% (Cert: Y%, Classified: Z%)
- Unfilled positions: X
- Department tickets: Transportation (X), Maintenance (Y), ESS (Z)
- Legislative bills with activity: X (Y fiscal impact)
- Finance articles: X

2.2 Podcast Script (~1400 words, ~9 min)

Transform the briefing into a conversational audio script. Address Ashley directly.

Required Sections (in order):

  1. Opening (~80 words)

    • "Good morning, Ashley."
    • Day, date, weather summary
    • Quick preview: "Today we have X absences with a Y% fill rate, Z department tickets, and some legislative movement on education funding."
  2. Absences Dashboard (~350 words)

    • Total absences, fill rate, unfilled count
    • Certificated vs classified breakdown
    • Weekly trend context: "Compared to this week's average of X, today is [above/below]..."
    • Schools with highest absence counts
    • Top absence reasons
    • Any unfilled positions requiring attention
    • Financial framing: "X unfilled positions means Y classrooms without coverage today"
  3. Department Tickets (~200 words)

    • Transportation: count + any urgent items
    • Maintenance: count + any urgent items
    • Employee Support Services: count + any urgent items
    • Highlight anything overdue or high-priority
  4. Legislative Fiscal Update (~300 words)

    • Bills with FISCAL impact that had recent activity
    • Budget implications for the district
    • Upcoming hearings or votes to watch
    • Finance committee bill highlights
  5. Finance/WASBO/OSPI News (~200 words)

    • 2-3 articles with financial relevance
    • Why each matters for PSD's budget or operations
  6. Closing (~100 words)

    • Top 3 items requiring CFO attention today
    • "Have a productive day, Ashley."

Tone Guidelines:

  • Professional, data-forward, financial framing
  • Use specific numbers, not vague language
  • "Your fill rate is 78%" not "fill rates are somewhat low"
  • Connect absence data to operational/financial impact
  • Reference trends: "up from yesterday" or "below this week's average"

CRITICAL - NO HALLUCINATION:

  • Use ONLY data from the scripts executed in Phase 1
  • Never invent absence numbers, ticket counts, or bill details
  • If a data source returned no results, say "No data available from [source]"

Save to /tmp/cfo_briefing_podcast.txt


Phase 3: Create Podcast

3.1 Apply Pronunciations

bun /Users/hagelk/non-ic-code/geoffrey/skills/morning-briefing/scripts/apply_pronunciations.js \
  --file /tmp/cfo_briefing_podcast.txt \
  --guide /Users/hagelk/non-ic-code/geoffrey/skills/cfo-briefing/pronunciation_guide.json

3.2 Generate Audio

uv run --with mlx-audio --with pydub /Users/hagelk/non-ic-code/geoffrey/skills/local-tts/scripts/generate_audio.py \
  --file /tmp/cfo_briefing_podcast.txt \
  --voice af_heart \
  --output ~/Desktop/cfo_briefing_[DATE].mp3

Voice: af_heart (warm, professional) Note: Replace [DATE] with YYYY-MM-DD format (e.g., cfo_briefing_2026-02-03.mp3)


Phase 3.5: Generate Absence Infographic

Build a dynamic prompt from Red Rover data and generate an infographic.

3.5.1 Build Infographic Prompt

Using the data gathered in Phase 1, construct a prompt:

Create a data dashboard infographic titled "PSD Staff Absences - [DATE]".

Main section - three large gauge/donut charts:
1. Total Absences: [X] (large number, navy background)
2. Fill Rate: [Y]% (color-coded: green if >=80%, gold if 70-79%, red if <70%)
3. Unfilled: [Z] (red accent if >5, gold if 3-5, green if <3)

Two-column comparison below the gauges:
Left column - "Certificated":
- Absences: [X]
- Filled: [Y]
- Unfilled: [Z]
- Fill Rate: [X]%

Right column - "Classified":
- Absences: [X]
- Filled: [Y]
- Unfilled: [Z]
- Fill Rate: [X]%

Bottom section - horizontal bar chart "Top 5 Schools by Absence Count":
[School 1]: [X] absences (filled portion in green, unfilled in red)
[School 2]: [X] absences
[School 3]: [X] absences
[School 4]: [X] absences
[School 5]: [X] absences

Style: Professional dashboard with PSD brand colors - navy (#003366) primary,
gold (#FFD700) accent, green (#28a745) for filled/positive, red (#dc3545) for
unfilled/negative. White background. Clean sans-serif typography. 16:9 aspect ratio.
Subtitle: "Prepared for Ashley Murphy, CFO"

3.5.2 Generate Image

uv run /Users/hagelk/non-ic-code/geoffrey/skills/image-gen/scripts/generate.py \
  "[infographic prompt]" \
  ~/Desktop/cfo_briefing_[DATE].png \
  16:9 \
  2K

Settings:

  • Aspect ratio: 16:9 (landscape dashboard)
  • Size: 2K (ensures text readability)
  • Output: ~/Desktop/cfo_briefing_[DATE].png

Phase 4: Send Email

4.1 Generate HTML Email

Using the template at skills/cfo-briefing/templates/email.html, generate the HTML email body by replacing all {{PLACEHOLDER}} values with actual data.

Template placeholders:

  • {{DATE}} - YYYY-MM-DD
  • {{DAY_OF_WEEK}} - Monday, Tuesday, etc.
  • {{DATE_FORMATTED}} - February 3, 2026
  • {{WEATHER_TEMP}} - e.g., 45°F
  • {{WEATHER_CONDITIONS}} - e.g., Partly Cloudy, High 48°F / Low 38°F
  • {{TOTAL_ABSENCES}} - total all-staff absences
  • {{FILL_RATE}} - all-staff fill rate percentage
  • {{FILL_RATE_CLASS}} - "green" if >=80%, "gold" if 70-79%, "red" if <70%
  • {{UNFILLED_COUNT}} - total unfilled
  • {{DEPT_TICKETS}} - combined ticket count across all 3 departments
  • {{ALL_ABSENCES}}, {{CERT_ABSENCES}}, {{CLASS_ABSENCES}} - breakdown totals
  • {{ALL_FILLED}}, {{CERT_FILLED}}, {{CLASS_FILLED}} - filled counts
  • {{ALL_UNFILLED}}, {{CERT_UNFILLED}}, {{CLASS_UNFILLED}} - unfilled counts
  • {{ALL_FILL_RATE}}, {{CERT_FILL_RATE}}, {{CLASS_FILL_RATE}} - fill rate %
  • {{TRANSPORT_COUNT}}, {{MAINT_COUNT}}, {{ESS_COUNT}} - per-department ticket counts
  • {{TRANSPORT_TICKETS}}, {{MAINT_TICKETS}}, {{ESS_TICKETS}} - ticket HTML lists
  • {{LEGISLATIVE_ITEMS}} - legislative section HTML
  • {{FINANCE_NEWS_ITEMS}} - news section HTML
  • {{WEEKLY_TRENDS_CONTENT}} - weekly trend summary HTML
  • {{UNFILLED_POSITIONS_LIST}} - list of unfilled positions HTML
  • {{CALENDAR_ITEMS}} - calendar items HTML (placeholder text for now)

Conditional sections (remove block including wrapper if condition not met):

  • {{#IF_ABSENCE_WARNING}}...{{/IF_ABSENCE_WARNING}} - show if fill rate <70% OR unfilled >5
  • {{ABSENCE_WARNING_TEXT}} - e.g., "Fill rate is 65% with 8 unfilled positions"
  • {{#IF_CALENDAR}}...{{/IF_CALENDAR}} - show if calendar data available
  • {{#IF_WEEKLY_TRENDS}}...{{/IF_WEEKLY_TRENDS}} - show if weekly data available
  • {{#IF_UNFILLED_ALERT}}...{{/IF_UNFILLED_ALERT}} - show if unfilled >5
  • {{#IF_LEGISLATIVE}}...{{/IF_LEGISLATIVE}} - show if legislative activity found
  • {{#IF_FINANCE_NEWS}}...{{/IF_FINANCE_NEWS}} - show if finance news found

Save generated HTML to /tmp/cfo_briefing_email.html

4.2 Send Email

cd /Users/hagelk/non-ic-code/geoffrey/skills/google-workspace && bun gmail/send_with_attachments.js psd \
  --to "hagelk@psd401.net" \
  --subject "CFO Daily Briefing - [DATE]" \
  --body-file /tmp/cfo_briefing_email.html \
  --html \
  --inline-image "~/Desktop/cfo_briefing_[DATE].png" \
  --attachments "~/Desktop/cfo_briefing_[DATE].mp3"

Options:

  • --html - Treat body as HTML
  • --inline-image - Embeds infographic at top of email (referenced as cid:briefing_image)
  • --attachments - Podcast MP3 attached for download

Production recipient: murphya@psd401.net (change --to when ready for production) Testing recipient: hagelk@psd401.net


Phase 5: Output Summary

Return standardized summary:

## Summary
Generated CFO daily briefing for [DATE]

## Actions
- Red Rover all-staff absences: X total, Y filled, Z unfilled (W% fill rate)
- Red Rover certificated: X total, Y filled, Z unfilled (W% fill rate)
- Derived classified: X total, Y filled, Z unfilled (W% fill rate)
- Weekly trends: X daily avg, peak [day] with Y absences
- Transportation tickets: X open
- Maintenance tickets: X open
- Employee Support tickets: X open
- Legislative bills with activity: X (Y with fiscal impact)
- Finance news articles: X
- Generated podcast: ~/Desktop/cfo_briefing_[DATE].mp3
- Generated infographic: ~/Desktop/cfo_briefing_[DATE].png
- Email sent to: hagelk@psd401.net

## Status
[Status emoji] [Complete/Partial]

## CFO Attention Items
1. [Most important item]
2. [Second most important]
3. [Third most important]

Error Handling

Red Rover API Error

Status: Partial
Note: Red Rover data unavailable - absence section skipped

FreshService API Error

Status: Partial
Note: FreshService workspace [ID] error - [department] tickets unavailable

Legislative Tracker Error

Status: Partial
Note: Legislative data unavailable - section skipped

Local TTS Generation Failed

Status: Partial
Note: Audio generation failed - check mlx-audio setup
Briefing sent without podcast attachment

Image Generation Failed

Status: Partial
Note: Infographic generation failed - email sent without inline image

Dependencies

Skill/ToolRequired ForFallback
redrover-managerAbsence dataSkip absence sections
freshservice-managerDepartment ticketsSkip ticket sections
legislative-trackerFiscal legislationSkip legislative section
local-ttsAudio podcastEmail without attachment
image-genAbsence infographicEmail without inline image
google-workspaceEmail deliveryDisplay summary in terminal only
WebSearchWeather, finance newsSkip sections

Configuration

Recipients

  • Testing: hagelk@psd401.net
  • Production: murphya@psd401.net

FreshService Workspaces

  • Transportation: workspace_id 9
  • Maintenance: workspace_id 6
  • Employee Support Services: workspace_id 3

Red Rover

  • All staff: get_daily_summary.js today
  • Certificated only: get_certificated_summary.js today
  • Weekly trends: get_weekly_summary.js 0

Voice

  • Model: Kokoro (local MLX TTS)
  • Voice: af_heart (warm, professional)
  • Target length: ~1400 words (~9 minutes)

Customization

Users can request:

  • "Skip news" - omit finance news section
  • "No podcast" - email without audio attachment
  • "Just absences" - minimal briefing with absence data only
  • "Send to Ashley" - use production recipient (murphya@psd401.net)

Clawdbot Monitor

Monitor the Clawdbot repository and identify opportunities to improve Geoffrey.

Clawdbot vs Geoffrey Quick Comparison

AspectClawdbotGeoffrey
ScopeMulti-channel messaging hub (WhatsApp, Discord, etc.)Claude Code plugin for personal AI
Skills60+ (CLI wrappers, platform integrations)26 (specialized workflows)
HooksEvent-driven TypeScript handlershooks.json configuration
MemoryHybrid vector + BM25 with SQLite-vecObsidian vault + knowledge-manager
ReleasesWeekly (v2026.x.x latest)Versioned plugin (v0.x.x)

Focus Areas

When invoked with an argument, focus analysis on that area:

  • skills - Skill formats, metadata, categories, CLI patterns
  • hooks - Event types, handler patterns, automation
  • extensions - Plugin architecture, provider isolation
  • memory - Search patterns, embeddings, persistence

Without an argument, perform full analysis across all areas.


Phase 1: Fetch Clawdbot Current State

1.1 Core Documentation

Fetch these from github.com/clawdbot/clawdbot:

  • README.md - Overall structure and philosophy
  • CLAUDE.md - System instructions (if exists)
  • Check releases page for version info

1.2 Skill Structure

Explore the skills directory:

  • List all available skills
  • Sample key skills that overlap with Geoffrey's domains
  • Note skill metadata patterns (requires.bins, requires.config, install methods)
  • Check for new skills since last analysis

1.3 Hook System

Examine hook architecture:

  • Event types (session, command, boot)
  • Handler patterns (TypeScript)
  • Compare to Geoffrey's hooks.json approach

1.4 Recent Changes

  • Check recent commits for significant updates
  • Look for new patterns or breaking changes
  • Note any announcements or migration guides

Phase 2: Analyze Geoffrey Current State

2.1 Core Architecture

Read these Geoffrey files:

  • CLAUDE.md - Founding principles and guidelines
  • README.md - Current capabilities
  • .claude-plugin/plugin.json - Version info

2.2 Skills Inventory

# Glob for all skills
skills/*/SKILL.md

Create inventory of current skills and their purposes.

2.3 Pattern Identification

Identify Geoffrey's current patterns:

  • Hook system usage (hooks.json)
  • Knowledge storage approach (Obsidian vault)
  • Skill structure conventions (SKILL.md frontmatter)
  • Validation patterns

Phase 3: Gap Analysis

Compare Geoffrey against Clawdbot across these dimensions:

3.1 Skill Coverage

  • What Clawdbot skills do we lack equivalent skills for?
  • Which skills would provide highest value for Geoffrey's use case?
  • Are there redundant or outdated skills?

3.2 Skill Metadata System

  • requires.bins - CLI dependency declarations
  • requires.config - Configuration requirements
  • Install methods - How skills auto-install dependencies
  • Compare to Geoffrey's current skill structure

3.3 Hook System

  • Clawdbot: Event-driven TypeScript handlers
  • Geoffrey: hooks.json configuration
  • What event types are missing?
  • What patterns could we adopt?

3.4 Extension Architecture

  • Plugin isolation patterns
  • Multi-provider support (LLM providers, messaging channels)
  • How Clawdbot handles modularity

3.5 Memory System

  • Clawdbot: Hybrid vector + BM25 with SQLite-vec
  • Geoffrey: Obsidian vault + knowledge-manager
  • Embedding integration patterns
  • Search and retrieval approaches

3.6 New Features

  • Recent Clawdbot additions worth adopting
  • Experimental features to watch

Phase 4: Generate Report

Create a markdown report with this structure:

# Clawdbot Monitor Report

**Geoffrey Version:** [from plugin.json]
**Clawdbot Version Analyzed:** [from releases]
**Analysis Date:** [today's date]

## Executive Summary
[2-3 sentence summary of key findings]

## Clawdbot Recent Changes
| Date | Change | Relevance to Geoffrey |
|------|--------|----------------------|
| ... | ... | ... |

## Features/Patterns to Adopt
| Priority | Feature | Purpose | Complexity | Notes |
|----------|---------|---------|------------|-------|
| High | ... | ... | ... | ... |
| Medium | ... | ... | ... | ... |
| Low | ... | ... | ... | ... |

## Pattern Improvements

### 1. [Pattern Name]
- **Clawdbot Implementation:** [how they do it]
- **Geoffrey Current:** [how we do it / missing]
- **Adoption Benefit:** [why adopt]
- **Files to Modify:** [list]

### 2. [Pattern Name]
...

## Skill Coverage Comparison
| Domain | Clawdbot Skill | Geoffrey Equivalent | Gap |
|--------|---------------|--------------------| ----|
| ... | ... | ... | ... |

## Recommended Actions

### Immediate (This Week)
- [ ] Action 1
- [ ] Action 2

### Short-Term (This Month)
- [ ] Action 1
- [ ] Action 2

### Long-Term (Explore)
- [ ] Action 1
- [ ] Action 2

Key Clawdbot Areas to Monitor

Based on repo structure, these are the primary areas:

AreaDescriptionGeoffrey Equivalent
skills/60+ modular skillsskills/ (26)
HooksEvent-driven TypeScripthooks.json
ExtensionsPlugin architecture(none currently)
MemoryHybrid vector + BM25Obsidian vault
ChannelsWhatsApp, Discord, etc.N/A (Claude Code only)

Key Differences from PAI Monitor

AspectPAIClawdbot
Update frequencyLess frequentWeekly releases
ArchitecturePacks + CLIDaemon + extensions
Skill count24 packs60+ skills
Memory modelFile-basedVector DB (SQLite-vec)
TargetPersonal AIMessaging hub

Execution Notes

  1. Start with Phase 1 - Always fetch fresh Clawdbot data, don't rely on cached knowledge
  2. Be thorough in Phase 2 - Accurate self-assessment is critical for gap analysis
  3. Prioritize in Phase 3 - Not all gaps need filling; focus on high-value opportunities for Geoffrey's use case
  4. Actionable Phase 4 - Every recommendation should have clear next steps
  5. Note Architecture Differences - Clawdbot is a daemon, Geoffrey is a plugin; some patterns won't translate

When focusing on a specific area, still provide brief context from other phases but concentrate analysis on the requested focus.

DOCX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Workflow Decision Tree

Reading/Analyzing Content

Use "Text extraction" or "Raw XML access" sections below

Creating New Document

Use "Creating a new Word document" workflow

Editing Existing Document

  • Your own document + simple changes Use "Basic OOXML editing" workflow

  • Someone else's document Use "Redlining workflow" (recommended default)

  • Legal, academic, business, or government docs Use "Redlining workflow" (required)

Reading and analyzing content

Text extraction

If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

Raw XML access

You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.

Unpacking a file

skills/docx/ooxml/scripts/unpack.py <office_file> <output_directory>

Key file structures
  • word/document.xml - Main document contents
  • word/comments.xml - Comments referenced in document.xml
  • word/media/ - Embedded images and media files
  • Tracked changes use <w:ins> (insertions) and <w:del> (deletions) tags

Creating a new Word document

When creating a new Word document from scratch, use docx-js, which allows you to create Word documents using JavaScript/TypeScript.

Workflow

  1. MANDATORY - READ ENTIRE FILE: Read docx-js.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
  2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
  3. Export as .docx using Packer.toBuffer()

Editing an existing Word document

When editing an existing Word document, use the Document library (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.

Workflow

  1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for the Document library API and XML patterns for directly editing document files.
  2. Unpack the document: skills/docx/ooxml/scripts/unpack.py <office_file> <output_directory>
  3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
  4. Pack the final document: skills/docx/ooxml/scripts/pack.py <input_directory> <office_file>

The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.

Redlining workflow for document review

This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. CRITICAL: For complete tracked changes, you must implement ALL changes systematically.

Batching Strategy: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.

Principle: Minimal, Precise Edits When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the <w:r> element from the original and reusing it.

Example - Changing "30 days" to "60 days" in a sentence:

# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

Tracked changes workflow

  1. Get markdown representation: Convert document to markdown with tracked changes preserved:

    pandoc --track-changes=all path-to-file.docx -o current.md
    
  2. Identify and group changes: Review the document and identify ALL changes needed, organizing them into logical batches:

    Location methods (for finding changes in XML):

    • Section/heading numbers (e.g., "Section 3.2", "Article IV")
    • Paragraph identifiers if numbered
    • Grep patterns with unique surrounding text
    • Document structure (e.g., "first paragraph", "signature block")
    • DO NOT use markdown line numbers - they don't map to XML structure

    Batch organization (group 3-10 related changes per batch):

    • By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
    • By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
    • By complexity: Start with simple text replacements, then tackle complex structural changes
    • Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"
  3. Read documentation and unpack:

    • MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
    • Unpack the document: skills/docx/ooxml/scripts/unpack.py <file.docx> <dir>
    • Note the suggested RSID: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.
  4. Implement changes in batches: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:

    • Makes debugging easier (smaller batch = easier to isolate errors)
    • Allows incremental progress
    • Maintains efficiency (batch size of 3-10 changes works well)

    Suggested batch groupings:

    • By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
    • By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
    • By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")

    For each batch of related changes:

    a. Map text to XML: Grep for text in word/document.xml to verify how text is split across <w:r> elements.

    b. Create and run script: Use get_node to find nodes, implement changes, then doc.save(). See "Document Library" section in ooxml.md for patterns.

    Note: Always grep word/document.xml immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.

  5. Pack the document: After all batches are complete, convert the unpacked directory back to .docx:

    skills/docx/ooxml/scripts/pack.py unpacked reviewed-document.docx
    
  6. Final verification: Do a comprehensive check of the complete document:

    • Convert final document to markdown:
      pandoc --track-changes=all reviewed-document.docx -o verification.md
      
    • Verify ALL changes were applied correctly:
      grep "original phrase" verification.md  # Should NOT find it
      grep "replacement phrase" verification.md  # Should find it
      
    • Check that no unintended changes were introduced

Converting Documents to Images

To visually analyze Word documents, convert them to images using a two-step process:

  1. Convert DOCX to PDF:

    soffice --headless --convert-to pdf document.docx
    
  2. Convert PDF pages to JPEG images:

    pdftoppm -jpeg -r 150 document.pdf page
    

    This creates files like page-1.jpg, page-2.jpg, etc.

Options:

  • -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
  • -jpeg: Output JPEG format (use -png for PNG if preferred)
  • -f N: First page to convert (e.g., -f 2 starts from page 2)
  • -l N: Last page to convert (e.g., -l 5 stops at page 5)
  • page: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for DOCX operations:

  • Write concise code
  • Avoid verbose variable names and redundant operations
  • Avoid unnecessary print statements

Dependencies

Required dependencies (install if not available):

  • pandoc: sudo apt-get install pandoc (for text extraction)
  • docx: npm install -g docx (for creating new documents)
  • LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
  • Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
  • defusedxml: pip install defusedxml (for secure XML parsing)

Drafts Manager Skill

Triage the Drafts inbox using a hybrid AI + human confirmation workflow. Routes content to OmniFocus (tasks) or Obsidian (notes) based on content analysis.

When to Activate

Use this skill when user wants to:

  • Triage or process their Drafts inbox
  • Route notes to OmniFocus or Obsidian
  • Check what's captured in Drafts
  • Clean up old drafts

Architecture

Two-Phase Hybrid Triage:

  1. Export & Analyze - Drafts exports inbox → Geoffrey analyzes → presents suggestions
  2. Confirm & Process - User confirms routing → Drafts processes each draft → archives
┌─────────┐  URL   ┌─────────┐  JSON   ┌─────────┐  Table  ┌──────┐
│Geoffrey │ ────► │ Drafts  │ ─────► │Geoffrey │ ──────► │ User │
│ trigger │       │ export  │        │ analyze │        │review│
└─────────┘       └─────────┘        └─────────┘        └──┬───┘
                                                           │
                                                     Confirmed
                                                           │
┌─────────┐  URL   ┌─────────┐  Routes  ┌──────────┐   ┌───▼────┐
│Geoffrey │ ────► │ Drafts  │ ───────► │OmniFocus │   │Process │
│ trigger │       │ process │         │ Obsidian │   │  list  │
└─────────┘       └────┬────┘         └──────────┘   └────────┘
                       │
                   Archives

Available Scripts

Scripts are in ./scripts/ directory. Run via:

bun ./scripts/script-name.js

trigger_export.js

Triggers the Drafts "Geoffrey Export Inbox" action via URL scheme.

Output: Path to exported JSON file

Use when: Starting triage

trigger_process.js

Triggers the Drafts "Geoffrey Process Draft" action with routing instructions.

Parameters: uuid, destination, project, tags, folder

Use when: Processing confirmed drafts

Required Drafts Actions

IMPORTANT: User must install these Drafts actions (found in ./actions/):

Geoffrey Export Inbox

Exports all inbox drafts to a JSON file for Geoffrey to analyze.

Location: ~/Library/Mobile Documents/iCloud~com~agiletortoise~Drafts5/Documents/geoffrey-export.json

Output format:

{
  "exported": "2025-11-23T10:30:00Z",
  "count": 5,
  "drafts": [
    {
      "uuid": "ABC123",
      "title": "First line of draft",
      "content": "Full content...",
      "tags": ["inbox"],
      "createdAt": "2025-11-22T14:00:00Z",
      "modifiedAt": "2025-11-22T14:00:00Z",
      "isFlagged": false
    }
  ]
}

Geoffrey Process Draft

Processes a single draft based on routing instructions from URL parameters.

URL Parameters:

  • uuid - Draft to process
  • destination - "omnifocus", "obsidian", "archive", or "trash"
  • project - OmniFocus project (if destination=omnifocus)
  • tags - Comma-separated tags (if destination=omnifocus)
  • dueDate - Due date (if destination=omnifocus)
  • folder - Obsidian folder (if destination=obsidian)

Content Analysis Rules

When analyzing drafts, look for these signals:

Route to OmniFocus (Task)

Signals:

  • Starts with action verb: "call", "email", "buy", "schedule", "review", "check"
  • Contains: "todo", "task", "@due", "@defer"
  • Short (< 50 words)
  • Contains person names
  • Shopping lists or errands

Apply omnifocus-manager routing rules for project/tag assignment

Route to Obsidian (Note)

Signals:

  • Longer content (> 100 words)
  • Meeting notes: "meeting with", "discussed", "attendees"
  • Ideas/brainstorms: "idea:", "thought:", "what if"
  • Reference material: links, quotes, research
  • Journal entries: "today I", feelings, reflections

Archive in Drafts

Signals:

  • Reference that may be needed again
  • Snippets of code or text
  • Temporary notes that are now done

Delete (Trash)

Signals:

  • Empty or nearly empty
  • Test/scratch content
  • Duplicates
  • Outdated info no longer needed

Obsidian Routing Rules

Content TypeFolderFrontmatter
Meeting notesMeetings/date, attendees, topics
Ideas/brainstormsGeoffrey/Inbox/tags, created
ResearchReference/source, tags, related
JournalJournal/date
General notesGeoffrey/Inbox/tags, created

Frontmatter template:

---
created: {{date}}
source: drafts
tags: [from-drafts]
related: []
---

Main Workflow: Triage Drafts

Phase 1: Export & Analyze

  1. Trigger export:

    open "drafts://x-callback-url/runAction?action=Geoffrey%20Export%20Inbox"
    
  2. Wait for export file (2-3 seconds)

  3. Read exported JSON:

    cat ~/Library/Mobile\ Documents/iCloud~com~agiletortoise~Drafts5/Documents/geoffrey-export.json
    
  4. Analyze each draft using content signals above

  5. Present suggestions table:

    ## Drafts Inbox Triage
    
    Found **5 drafts** to process:
    
    | # | Title | Suggestion | Destination | Details |
    |---|-------|------------|-------------|---------|
    | 1 | Call John about... | Task | OmniFocus | Project: Meetings, Tags: John, Follow Up |
    | 2 | Meeting notes 11/22 | Note | Obsidian | Folder: Meetings/ |
    | 3 | [empty] | Delete | Trash | Empty draft |
    | 4 | Shopping list | Task | OmniFocus | Project: Single Actions, Tags: Chores |
    | 5 | Idea for app... | Note | Obsidian | Folder: Geoffrey/Inbox/ |
    
    **Questions:**
    - #4: Should this go to a specific store location tag?
    
    Which numbers need changes? (Or type "process all" to confirm)
    

Phase 2: Process & Archive

  1. For each confirmed draft, trigger process action:

    # OmniFocus task
    open "drafts://x-callback-url/runAction?action=Geoffrey%20Process%20Draft&uuid=ABC123&destination=omnifocus&project=Meetings&tags=John,Follow%20Up&dueDate=2025-11-30"
    
    # Obsidian note
    open "drafts://x-callback-url/runAction?action=Geoffrey%20Process%20Draft&uuid=DEF456&destination=obsidian&folder=Meetings"
    
    # Archive
    open "drafts://x-callback-url/runAction?action=Geoffrey%20Process%20Draft&uuid=GHI789&destination=archive"
    
    # Delete
    open "drafts://x-callback-url/runAction?action=Geoffrey%20Process%20Draft&uuid=JKL012&destination=trash"
    
  2. Report results:

    ## Summary
    Processed 5 drafts from inbox
    
    ## Actions
    - 2 tasks created in OmniFocus
    - 2 notes saved to Obsidian
    - 1 draft deleted
    
    ## Status
    ✅ Complete
    
    ## Next Steps
    - Review tasks in OmniFocus inbox
    - Check Obsidian notes in Geoffrey/Inbox/
    

Error Handling

Drafts not running:

Status: ❌ Failed
Error: Drafts app is not running. Please open Drafts and try again.

Action not installed:

Status: ❌ Failed
Error: Drafts action "Geoffrey Export Inbox" not found.
Please install from: skills/drafts-manager/actions/

Export file not found:

Status: ⚠️ Partial
Error: Export file not created. Drafts may have timed out.
Try running the action manually in Drafts.

OmniFocus not running:

Status: ⚠️ Partial
Warning: OmniFocus not running. Task creation may have failed.
Please verify tasks were created.

Installation

1. Install Drafts Actions

Import the action files from ./actions/:

Option A: Import from file

  1. Open Drafts
  2. Go to Actions → Manage Actions
  3. Import from actions/geoffrey-export-inbox.draftsAction
  4. Import from actions/geoffrey-process-draft.draftsAction

Option B: Create manually

  1. Open Drafts
  2. Create new action "Geoffrey Export Inbox"
  3. Add Script step with code from actions/geoffrey-export-inbox.js
  4. Repeat for "Geoffrey Process Draft"

2. Verify Installation

Run: open "drafts://x-callback-url/runAction?action=Geoffrey%20Export%20Inbox"

Check for export file at: ~/Library/Mobile Documents/iCloud~com~agiletortoise~Drafts5/Documents/geoffrey-export.json

Tips for Best Results

Tagging in Drafts

Use these tags for manual pre-routing:

  • task - Force route to OmniFocus
  • note - Force route to Obsidian
  • archive - Keep in Drafts archive
  • delete - Trash without review

Quick Capture Patterns

When capturing to Drafts, these patterns help AI routing:

  • Start tasks with verbs: "Call", "Email", "Buy"
  • Start notes with context: "Meeting:", "Idea:", "Note:"
  • Use @ for OmniFocus hints: "@due(tomorrow)", "@project(Work)"

Regular Triage

Best practice: Triage Drafts daily to keep inbox small

  • Morning: Process yesterday's captures
  • Evening: Quick review of day's notes

Learned Routing Patterns

These patterns were learned through actual triage sessions with the user.

Content Type → Destination

Content TypeDestinationObsidian FolderOmniFocus Details
Meeting notesObsidianMeetings/2025/-
Conference notesObsidianMeetings/2025/-
Development roadmapObsidianWork/[Project]/Roadmap.mdFormat as checklist
API keys/credentialsDelete-Security risk
Error logs/JSON junkDelete-Cruft
Random passwordsDelete-Cruft
Contact infoContacts app-Also create follow-up task
Book recommendationsOmniFocus-Tags: Reading
Gift ideasOmniFocus-Tags: Chores, Shopping
Action items from meetingsOmniFocus-Tags: Follow Up
Reference links (AI, UDL)ObsidianReference/-
Personal project ideasOmniFocus-Tags: Coding
Presentation schedulesObsidianWork/Presentations/Future dates → tasks
Survey linksOmniFocus-Include links in notes

Signals for Each Destination

→ OmniFocus Task:

  • Starts with action verbs: "Submit", "Call", "Email", "Build", "Add"
  • Contains due date context: "first week of December", "by end of year"
  • Travel approvals, surveys to send, podcasts to record
  • Book to read, thing to buy, project to build
  • Multiple action items → single task with checklist in notes

→ Obsidian Note:

  • Meeting notes (look for date, attendees, discussion points)
  • Conference notes (look for session titles, speakers, links)
  • Development docs with code/commands (wrap in code blocks)
  • Reference material with links to external resources
  • Topic brainstorms and idea lists

→ Contacts App:

  • Contains name + phone/email
  • Create contact AND follow-up task if there's an action

→ Delete:

  • Empty or nearly empty
  • JSON/error logs
  • API keys (security)
  • Random strings/passwords
  • Test data that's no longer needed

→ Archive in Drafts:

  • Outdated but potentially useful later
  • Reference that may be needed again

Project/Folder Mappings

Obsidian Folders:

  • Meetings/2025/ - All meeting and conference notes
  • Work/AI-Studio/ - AI Studio development docs
  • Work/Jocular-Kangaroo/ - Jocular Kangaroo project
  • Work/Presentations/ - Presentation archives
  • Geoffrey/ - Geoffrey roadmap and ideas
  • Reference/ - Reference materials and links

OmniFocus Projects (go to Inbox if not found):

  • CoSN Work - CoSN-related tasks
  • Meetings - Follow-ups with people
  • Research for Future Plans - Books, research tasks

OmniFocus Tags:

  • Follow Up - Tasks requiring follow-up
  • Reading - Books to read
  • Chores - Shopping, errands
  • Coding - Development tasks
  • Geoffrey - AI-assistable tasks
  • Email - Tasks requiring email

Special Handling

Multi-item notes:

  • If note contains multiple distinct items, either:
    • Create single task with items as checklist in notes
    • Split into separate tasks (ask user preference)

Development roadmaps:

  • Format as Obsidian file with checkboxes
  • Use - [ ] for pending items
  • Use - [x] for completed items
  • Include code blocks for commands

Sensitive data:

  • API keys → Delete immediately
  • Student investigation data → Archive carefully, don't expose
  • Credentials → Delete or move to secure storage

Contact + Task pattern:

  • Add to Contacts app via add_contact.js
  • Create follow-up task with contact details in notes
  • Example: "Send maps to Kim Crowder" with email in notes

Future Enhancements

  • Batch processing without confirmation for tagged drafts
  • Smart date extraction from draft content
  • Template matching for common note types
  • Sync with omnifocus-manager tag hierarchy
  • Obsidian template application
  • Draft content search/query
  • Auto-detect project roadmaps and format as checklists
  • Recognize CoSN, ACPE, Kiwanis contexts for project routing

Eleven Labs Text-to-Speech

Generate high-quality audio from text using the Eleven Labs API. Ideal for podcast-style summaries, narration, and voice-overs.

Quick Start

# Generate audio with default voice (Rachel)
uv run scripts/generate_audio.py --text "Hello, this is a test."

# Generate from a text file
uv run scripts/generate_audio.py --file report.txt --output ~/Desktop/report.mp3

# Use a specific voice
uv run scripts/generate_audio.py --text "Breaking news..." --voice Josh

# List available voices
uv run scripts/list_voices.py

Scripts

generate_audio.py

Main script for TTS generation.

Arguments:

ArgumentDescriptionDefault
--textText content to convert-
--filePath to text file-
--voiceVoice name or IDRachel
--modelModel IDeleven_multilingual_v2
--outputOutput file path~/Desktop/audio_TIMESTAMP.mp3

Features:

  • Auto-chunks text >10k characters at sentence boundaries
  • Concatenates chunks into single MP3
  • Returns JSON with metadata (file path, voice, model, char count, chunks)

list_voices.py

Fetch and display available voices.

Arguments:

ArgumentDescriptionDefault
--allShow all voices (not just premade)false
--jsonOutput as JSONfalse

Curated Voices

Six voices selected for variety (see references/voices.md for details):

VoiceStyleBest For
RachelCalm, clearNarration, podcasts (default)
BellaSoft, gentleStorytelling, meditation
ElliYoung, expressiveCasual content, tutorials
JoshDeep, authoritativeNews, professional content
AdamMiddle-aged, clearBusiness, documentaries
AntoniWarm, versatileGeneral purpose

Use list_voices.py to discover additional voices.

Models

ModelIDBest ForChar Limit
Multilingual v2eleven_multilingual_v2Long-form (default)10,000
Flash v2.5eleven_flash_v2_5Quick, real-time40,000
Turbo v2.5eleven_turbo_v2_5Balanced40,000
Eleven v3eleven_v3Maximum expression3,000

Environment Setup

Requires ELEVENLABS_API_KEY in:

~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env

Examples

Daily Summary Podcast

# Generate individual segments
uv run scripts/generate_audio.py --file weather.txt --voice Rachel --output ~/Desktop/weather.mp3
uv run scripts/generate_audio.py --file news.txt --voice Josh --output ~/Desktop/news.mp3
uv run scripts/generate_audio.py --file calendar.txt --voice Bella --output ~/Desktop/calendar.mp3

Long Report

# Auto-chunks long text, concatenates into single file
uv run scripts/generate_audio.py --file quarterly_report.txt --model eleven_turbo_v2_5 --output report.mp3

Quick Test

uv run scripts/generate_audio.py --text "Testing one two three" --voice Adam

Output

Default: ~/Desktop/audio_YYYY-MM-DD_HHMMSS.mp3

Script returns JSON:

{
  "success": true,
  "file": "/Users/user/Desktop/audio_2026-01-23_143022.mp3",
  "voice": "Rachel",
  "model": "eleven_multilingual_v2",
  "characters": 1234,
  "chunks": 1
}

Limitations

  • Character limits vary by model (see table above)
  • One voice per generation (multi-voice requires separate files)
  • Output format: MP3 only

Freshservice Manager Skill

Configuration

  • Domain: psd401.freshservice.com
  • Agent ID: 6000130414 (Kris Hagel)
  • Primary Workspace: 2 (Technology)
  • API Key: Stored in ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env

Workspaces

IDName
2Technology (primary)
3Employee Support Services
4Business Services
5Teaching & Learning
6Maintenance
8Investigations
9Transportation
10Safety & Security
11Communications
13Software Development

Team Context

  • TSD Generic Account (6000875582) - Shared by high school interns for Chromebook repairs
  • David Edwards - Desktop Support Tech, handles most varied workload including incidents
  • Carol Winget - Student Database Admin, PowerSchool specialist
  • Laura Durkin - Admin Secretary, handles new students and badges

Reports & Summaries

Daily Summary

Get a narrative summary of what happened in Technology on a specific day.

Natural language triggers:

  • "What happened in Freshservice yesterday?"
  • "Give me today's tech summary"
  • "What did the team do on Wednesday?"

Script: bun get_daily_summary.js [date]

Date options:

  • today (default)
  • yesterday
  • Day names: monday, tuesday, wednesday, etc.
  • last wednesday, last friday
  • Specific date: 2025-11-20

Output includes:

  • Total tickets closed
  • Breakdown by category (Chromebook, Schoology, Security Alert, etc.)
  • Breakdown by agent with their tickets
  • Automated ticket count (password resets)

Weekly Summary

Get trends and metrics for the entire week.

Natural language triggers:

  • "Weekly tech summary"
  • "How did the team do this week?"
  • "Give me the weekly Freshservice report"

Script: bun get_weekly_summary.js [weeks_ago]

Options:

  • 0 = this week (default)
  • 1 = last week
  • 2 = two weeks ago

Output includes:

  • Total closed and daily average
  • Peak day and slow day
  • Daily trend by volume
  • Category breakdown with percentages
  • Category trends (which days had spikes)
  • Top agents with ticket counts and focus areas
  • Agent daily breakdown

Narrative Style

When presenting summaries, write a 1-minute narrative that:

  • Highlights the main story of the day/week (outages, big pushes, etc.)
  • Calls out specific people and what they handled
  • Notes any concerning patterns (security alerts, cut wires, etc.)
  • Converts UTC timestamps to Pacific time
  • Uses specific numbers and ticket counts

Ticket Operations

List Tickets

bun list_tickets.js '{"workspace_id": 2, "filter": "new_and_my_open"}'

Filters: new_and_my_open, watching, spam, deleted, archived

Search Tickets

bun search_tickets.js "status:2 AND priority:3" 2

Query syntax: field:value AND/OR field:value Fields: status, priority, agent_id, group_id, created_at, updated_at

Get Ticket Details

bun get_ticket.js <ticket_id>

Get Service Request (with form data)

bun get_service_request.js <ticket_id>

Includes requester info, custom form fields, requested items.

Create Ticket

bun create_ticket.js '<json>'

Required: subject, description, email or requester_id Optional: priority, status, workspace_id

Update Ticket

bun update_ticket.js <ticket_id> '<json>'

Can update: status, priority, responder_id, group_id

Add Note

bun add_note.js <ticket_id> '{"body": "Note text", "private": true}'

Optional: notify_emails array to alert specific agents.

Agent Operations

List Agents

bun list_agents.js [query]

Query filters by first name, last name, or email. Returns: id, name, email, job_title

Use this to resolve "assign to Mark" → find Mark's agent ID → update ticket.

Get Agent by Email

bun get_agent.js <email>

Approvals

Get Pending Approvals

bun get_approvals.js [status]

Status: requested (default), approved, rejected, cancelled

Note: Freshservice API does not support approving service requests programmatically. User must approve via:

  • Web UI: https://psd401.freshservice.com/helpdesk/tickets/<id>
  • Email reply to approval request

Common Workflows

"Add a note to Jodi on ticket 151501"

  1. Find Jodi's agent ID: bun list_agents.js jodi → 6000542935
  2. Add note: bun add_note.js 151501 '{"body": "...", "notify_emails": ["miloj@psd401.net"]}'

"Assign ticket to Mark"

  1. Find Mark's ID: bun list_agents.js mark
  2. Update ticket: bun update_ticket.js <id> '{"responder_id": <mark_id>}'

"What approvals do I have?"

  1. Get approvals: bun get_approvals.js
  2. For each approval, get details: bun get_service_request.js <ticket_id>

Cross-skill workflow

"Add note to ticket, create OmniFocus task, reassign ticket" - can combine Freshservice note + OmniFocus task creation + ticket update in one flow.

Category Detection

Tickets are auto-categorized by subject keywords:

  • Password Reset: "password reset"
  • Security Alert: "security alert", "compromised", "breach"
  • Schoology: "schoology"
  • PowerSchool: "powerschool"
  • Promethean Board: "promethean"
  • Chromebook: "chromebook"
  • Phone/Voicemail: "phone", "voicemail", "ext."
  • Badge Request: "badge"
  • New Student: "new student", "enrollee"
  • Intercom: "intercom"
  • Raptor: "raptor"
  • GoGuardian: "goguardian", "go guardian"
  • Access/Login: "login", "access", "mfa"

Status Codes

CodeStatus
2Open
3Pending
4Resolved
5Closed

Priority Codes

CodePriority
1Low
2Medium
3High
4Urgent

Google Workspace Skill

Overview

Unified Google Workspace integration for managing email, calendar, files, and communication across three accounts:

AliasPurposeEmail
psdWorkPSD district email
khPersonalPersonal Gmail
hrgBusinessConsulting & real estate

Account Selection

Explicit

  • "check my psd email"
  • "send email from hrg"
  • "kh calendar for tomorrow"

Inferred

Geoffrey will infer the appropriate account from context:

  • Work-related → psd
  • Personal matters → kh
  • Business/real estate → hrg

Available Operations

Gmail

ScriptDescriptionExample
list_messages.jsList inbox, unread, by label"show unread psd emails"
read_message.jsGet full message content"read that email"
send_message.jsCompose and send"send email to John about..."
send_with_attachment.jsSend with file attachment"email report with PDF attached"
search_messages.jsSearch with Gmail operators"find emails from Sarah last week"
get_unread_summary.jsUnread count + top messages"how many unread emails?"

Calendar

ScriptDescriptionExample
list_events.jsGet upcoming events"what's on my calendar today"
create_event.jsSchedule new events"schedule meeting tomorrow at 2pm"
update_event.jsModify existing events"move that meeting to 3pm"
search_events.jsFind by criteria"find meetings with Mike"

Drive

ScriptDescriptionExample
list_files.jsBrowse/search files"find budget spreadsheet"
read_file.jsGet file content"show me that document"
create_file.jsCreate new docs/sheets"create a new spreadsheet"
upload_file.jsUpload local file"upload this to drive"

Tasks

ScriptDescriptionExample
list_tasks.jsGet task lists"show my google tasks"
create_task.jsAdd new task"add task to google tasks"
complete_task.jsMark done"complete that task"

Chat

ScriptDescriptionExample
list_spaces.jsGet available spaces"list chat spaces"
send_message.jsPost to space"send message to team chat"
read_messages.jsGet chat history"show recent chat messages"

Usage Patterns

Running Scripts

All scripts use the token_manager for authentication:

const { getAuthClient } = require('./auth/token_manager');

async function main() {
  const account = process.argv[2] || 'psd';
  const auth = await getAuthClient(account);

  // Use auth with Google API
  const gmail = google.gmail({ version: 'v1', auth });
  // ...
}

Output Format

All scripts return JSON:

{
  "success": true,
  "account": "psd",
  "data": { ... },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "count": 5
  }
}

Error Handling

{
  "error": "Token expired",
  "account": "psd",
  "action": "Run: node token_manager.js refresh psd"
}

Setup Required

Before using this skill:

  1. Complete Google Cloud Console setup (see auth/GOOGLE_CLOUD_SETUP.md)
  2. Add credentials to ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env
  3. Authenticate all three accounts
  4. For PSD account: allowlist OAuth app in Google Admin

Cross-Account Operations

Some operations work across accounts:

  • "Forward this to my personal email"
  • "Copy this file to my work drive"
  • "Add to both calendars"

Gmail Search Operators

Support standard Gmail search:

  • from: - sender
  • to: - recipient
  • subject: - subject line
  • has:attachment - with attachments
  • after: / before: - date range
  • is:unread - unread only
  • label: - by label

Example: "search psd email for from:boss@psd.org after:2024-01-01 has:attachment"

Notes

  • Access tokens expire after 1 hour (auto-refreshed)
  • Refresh tokens don't expire unless revoked
  • All API calls are rate-limited by Google
  • Keep API has limited availability (may not be enabled)

Image Generation Skill

Generate professional images, infographics, and diagrams using Google's Nano Banana 2 model (gemini-3.1-flash-image-preview).

Model Capabilities

Nano Banana 2 (released February 26, 2026):

  • Text rendering - Accurate, legible text in images
  • Google Search grounding - Real-time data (weather, stocks, etc.)
  • Subject consistency - Up to 5 characters maintained across generations
  • Multi-turn conversation - Iterative refinement
  • Up to 14 reference images - For composition and style transfer
  • Resolutions: 1K, 2K, 4K
  • Aspect ratios: 1:1, 2:3, 3:2, 4:3, 16:9, 21:9

Scripts

All scripts use Python via uv run with inline dependencies.

generate.py - Text to Image

uv run scripts/generate.py "prompt" output.png [aspect_ratio] [size]

Examples:

# Basic image
uv run scripts/generate.py "A cozy coffee shop in autumn" coffee.png

# Infographic with specific aspect ratio
uv run scripts/generate.py "Infographic explaining how neural networks work" nn.png 16:9 2K

# 4K professional image
uv run scripts/generate.py "Professional headshot, studio lighting" headshot.png 3:2 4K

edit.py - Image Editing

uv run scripts/edit.py input.png "edit instructions" output.png

Examples:

# Edit existing image
uv run scripts/edit.py photo.png "Change the background to a beach sunset" edited.png

compose.py - Multi-Image Composition

uv run scripts/compose.py "prompt" output.png --refs image1.png image2.png

Examples:

# Combine styles from multiple images
uv run scripts/compose.py "Combine these styles into a logo" logo.png --refs style1.png style2.png

Workflows

Workflows provide structured approaches for specific visual types. Each workflow follows the PAI 6-step editorial process:

  1. Extract narrative - Understand the complete story/concept
  2. Derive visual concept - Single metaphor with 2-3 physical objects
  3. Apply aesthetic - Define style, colors, mood
  4. Construct prompt - Build detailed generation instructions
  5. Generate - Execute via script
  6. Validate - Check against criteria, regenerate if needed

Available Workflows

  • infographic.md - Data visualization, statistics, explainers
  • diagram.md - Technical diagrams, flowcharts, architecture

Workflow Usage

When generating images, follow the appropriate workflow:

For Infographics

1. What data/concept needs visualization?
2. What's the key insight or takeaway?
3. Aspect ratio: 16:9 (landscape) recommended
4. Include: clear hierarchy, minimal text, supporting icons
5. Generate at 2K minimum for text clarity

For Diagrams

1. What system/process is being illustrated?
2. What are the key components and relationships?
3. Style: flat colors, clean lines, minimal detail
4. Generate at 2K for label clarity

Environment Setup

Requires GEMINI_API_KEY environment variable. This should be set from Geoffrey's secrets:

source ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/secrets/.env

Best Practices

Infographics

  • Use simple, direct prompts: "Infographic explaining how X works"
  • Model auto-includes relevant icons/logos
  • 16:9 aspect ratio works best
  • Generate at 2K+ for readable text

General

  • Multi-turn refinement: generate, then ask for specific changes
  • Reference images improve consistency
  • Be specific about style, mood, lighting
  • SynthID watermark is automatic (Google provenance)

Output Location

By default, save images to /tmp/ or user-specified paths. For persistent storage, use:

~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/images/

⚠️ CRITICAL: Never Read Generated Images

DO NOT use the Read tool on generated images.

Why:

  • 4K images (3840x2160) are within the 8000px limit
  • 2K images (2560x1440) are also safe
  • BUT: Do not Read them - they're for user consumption, not analysis
  • For edits, use edit.py script, not Read tool

Workflow:

  1. Generate image with script
  2. Return file path to user
  3. User views the high-quality output

Limitations

  • No photorealistic humans (safety filter)
  • No copyrighted characters
  • Maximum 14 reference images for composition
  • 4K only available with Nano Banana 2 and Nano Banana Pro

Pricing

SizeCost per Image
1KFree tier / $0.04
2K$0.134
4K$0.24

Knowledge Manager Skill

You are Geoffrey's knowledge management system. Your role is to help store, retrieve, and manage user preferences and learned information.

Your Capabilities

  • Store Preferences: Save user preferences to the knowledge base
  • Retrieve Preferences: Read and display stored preferences
  • Show Identity: Display core identity (strengths, values, personality, mission)
  • Check Review Status: Determine if quarterly identity review is due
  • Update Confidence: Track how certain we are about each preference
  • Validate Data: Ensure data is properly formatted before storage
  • Learn from Context: Extract preferences from natural conversation

Knowledge Storage Location

All knowledge is stored in:

~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/knowledge/
├── preferences.json              # Behavioral preferences with confidence scores
├── identity-core.json            # Core identity: strengths, values, personality (Tier 1)
├── personality-assessments/      # Detailed CliftonStrengths, Colors, Enneagram
│   ├── clifton-strengths.json
│   ├── colors-profile.json
│   └── enneagram-profile.json
├── memory.jsonl                  # Conversation history (future)
└── patterns.json                 # Detected patterns (future)

Obsidian Identity Documents:

Geoffrey/Identity/
├── Personal-Constitution.md      # Philosophy, values, principles
├── Personality-Profiles.md       # All assessments consolidated
└── Identity-Evolution-Log.md     # Quarterly reviews and evolution tracking

Preference Structure

Each preference includes:

  • Category: Domain (travel, work, communication, etc.)
  • Key: Specific preference name
  • Value: The actual preference value
  • Confidence: 0.0-1.0 score
    • 1.0 = Explicitly stated by user
    • 0.8-0.9 = Strong pattern (5+ observations)
    • 0.6-0.7 = Moderate pattern (3-4 observations)
    • 0.4-0.5 = Weak pattern (1-2 observations)
    • <0.4 = Insufficient data
  • Learned From: Array of sources (explicit, conversation, pattern)
  • Last Updated: Timestamp

How to Store a Preference

When the user teaches you something:

  1. Read current preferences:

    cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/preferences.json
    
  2. Parse and validate the user's statement

  3. Update the JSON with new preference:

    • Add to appropriate category
    • Set confidence based on how it was learned
    • Record the source
    • Update timestamp
  4. Write back to the file

  5. Confirm to the user what was learned

Example Interactions

User teaches explicitly:

User: "I always prefer Marriott hotels. I'm Platinum Elite."

Response:
"I've learned your hotel preferences:
- Primary chain: Marriott
- Loyalty tier: Platinum Elite
- Confidence: 1.0 (explicitly stated)

Stored in knowledge base. I'll use this for all future travel planning."

User asks about preferences:

User: "What do you know about my travel preferences?"

Response:
"Your travel preferences:

Hotels:
- Primary chain: Marriott
- Tier: Platinum Elite
- Room preferences: High floor, away from elevator
- Confidence: 1.0

Airlines:
- Primary: Alaska Airlines
- Seat preference: Aisle
- Confidence: 0.8 (observed pattern from 5 bookings)

You can update these anytime by telling me or using /preferences"

When to Activate

Use this skill when:

  • User explicitly teaches you something ("I prefer...", "Always...", "Never...")
  • User asks about their preferences ("What do you know about...", "Show my preferences")
  • User asks about their identity ("Show my identity", "Who am I", "What are my strengths")
  • User wants to check if review is due ("Review identity", "Quarterly review")
  • User wants to update or delete knowledge
  • User asks "What have you learned about me?"
  • User triggers credit card benefits check

Identity Context (Always Load for Identity Queries)

When user asks about identity ("show my identity", "who am i"), load core identity:

cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/identity-core.json

Display format for "show my identity":

## Core Identity Summary

**Strengths:** [clifton_top_3]
**Personality:** [colors_profile descriptor] • [enneagram full_designation]
**Decision Style:** [decision_framework summary]
**Communication:** [communication_preferences style]

**Core Mission:** [telos_summary core_mission]

**Top 3 Values:**
1. [value 1]
2. [value 2]
3. [value 3]

**Growth Edge:** [challenges and blind spots]

**Next Review:** [next_review date] (quarterly)

*Full details: identity-core.json (v[version]), Personal-Constitution.md, Personality-Profiles.md*

Quarterly Review Check

When user asks "review identity" or "quarterly review", run check script:

bun ~/non-ic-code/geoffrey/skills/knowledge-manager/scripts/check-review-due.js

If review is due:

  • Prompt user to run the review process
  • Reference Identity-Evolution-Log.md for review workflow
  • Offer to open the log in Obsidian

If not due yet:

  • Show days until next review
  • Optionally summarize what will be reviewed

Important Guidelines

  • Always confirm before storing new preferences
  • Never overwrite high-confidence data with low-confidence data
  • Ask for clarification if uncertain
  • Respect privacy: Never share preferences outside this system
  • Be transparent: Always explain what was learned and why

Data Validation

Before storing, verify:

  • ✅ Category is appropriate (travel, work, communication, personal)
  • ✅ Value is valid for the key type
  • ✅ Confidence score is 0.0-1.0
  • ✅ Timestamp is ISO-8601 format
  • ✅ JSON is valid and well-formatted

Error Handling

If the knowledge file doesn't exist:

  • Create it with default structure
  • Initialize version 1.0
  • Add first preference

If JSON is malformed:

  • Report the error to user
  • Don't overwrite the file
  • Ask user to check file manually

Credit Card Benefits Tracking

Overview

Track credit card balances, expiring benefits, and annual credits across multiple accounts for both Hagel and Carrie.

Storage Location

~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/knowledge/credit-card-status.json

Accounts to Track

Hagel:

  • Chase Sapphire Reserve (...2502)
  • Marriott Bonvoy Amex (3 cards: ...81004, ...43001, ...61000)
  • Alaska/Atmos Rewards

Carrie:

  • Alaska/Atmos account
  • Chase account(s)

Data Structure

{
  "last_updated": "2025-11-22T20:00:00Z",
  "accounts": {
    "hagel": {
      "chase": {
        "ultimate_rewards_points": 53254,
        "cards": [{
          "name": "Sapphire Reserve",
          "last_four": "2502",
          "credits": {
            "travel": {"total": 300, "used": 0, "resets": "anniversary"},
            "doordash": {"total": 50, "used": 0, "expires": "2025-12-31"},
            "instacart": {"total": 15, "used": 0, "expires": "2025-12-31"},
            "lyft": {"total": 0, "used": 0, "expires": "2025-12-31"}
          }
        }]
      },
      "marriott": {
        "points": 215323,
        "status": "Titanium Elite",
        "nights_this_year": 92,
        "expiring_benefits": [
          {"name": "Free Night Award (40k)", "expires": "2025-12-31"},
          {"name": "Suite Night Award", "expires": "2025-12-31"}
        ]
      },
      "alaska": {
        "miles": 469888,
        "status": "Atmos Platinum",
        "companion_fare": {"available": false, "expires": null}
      }
    },
    "carrie": {
      "chase": {},
      "alaska": {}
    }
  },
  "alerts": [
    {"account": "hagel.marriott", "item": "Free Night Award", "expires": "2025-12-31", "days_remaining": 39}
  ]
}

Check Benefits Workflow

When user triggers "check benefits":

  1. Use browser-control to scrape each account:

    • Chase: ultimaterewardspoints.chase.com + benefits page
    • Marriott: marriott.com/loyalty/myAccount/activity.mi
    • Alaska: alaskaair.com/account/wallet
    • Amex: global.americanexpress.com/dashboard
  2. Extract key data:

    • Point/mile balances
    • Credit usage status
    • Expiring benefits with dates
    • Free night certificates
  3. Save to status file in iCloud

  4. Generate alerts for items expiring within 30 days

  5. Report to user with action items

Monthly Reminder

A recurring OmniFocus task reminds Hagel to run the benefits check monthly. Task details:

  • Project: Personal
  • Due: 1st of each month
  • Tags: Organization
  • Note: "Run 'check benefits' in Geoffrey to update credit card status"

Future Enhancements

In later phases, this skill will:

  • Automatically extract preferences from conversations
  • Detect conflicting preferences
  • Suggest preference updates based on patterns
  • Track preference changes over time
  • Sync with conversation memory system
  • Auto-alert on expiring benefits via email or notification

Legislative Tracker Skill

Track Washington State K-12 education legislation from leg.wa.gov using committee-based discovery. This approach queries committees directly via SOAP API to get ALL bills - not just keyword matches.

Why Committee-Based Discovery

Problem with keyword searching: Bills with unexpected wording or indirect impacts get missed. A bill about "unfunded mandates" might never mention "school" but still affect districts.

Solution: Query education committees directly. If a bill is in the House Education Committee or Senate Early Learning & K-12 Education Committee, it's education-related by definition.


Discovery Strategy

Tier 1: Direct Education Bills (Comprehensive)

Query these committees to get ALL education bills:

CommitteeChamberQuery
EducationHouseAll bills - no filtering
Early Learning & K-12 EducationSenateAll bills - no filtering

Tier 2: Indirect Impact Bills (Candidates)

Query these committees and filter via WebFetch:

CommitteeChamber
AppropriationsHouse
Capital BudgetHouse
Labor & Workplace StandardsHouse
Ways & MeansSenate
Labor & CommerceSenate
State Government, Tribal Affairs & ElectionsSenate

Workflow: The SOAP API returns only bill IDs. Geoffrey must:

  1. Get all bill IDs from Tier 2 committees (~700 bills)
  2. WebFetch each bill's summary page to get the title/description
  3. Filter for education keywords in the description
  4. Add matching bills to the tracked list

Filter keywords: school, student, teacher, education, k-12, district, ospi, classroom, principal, paraeducator, learning, instruction, curriculum, diploma, graduation, superintendent, levy, bond, capital, school construction

Tier 3: WebSearch Fallback

If SOAP API fails, use WebSearch:

site:leg.wa.gov "referred to Education" 2025-26
site:leg.wa.gov "Early Learning & K-12" 2025-26
site:leg.wa.gov K-12 school district bill 2025

Workflow Phases

Phase 1: Committee Discovery (SOAP)

Run the orchestrator script:

bun skills/legislative-tracker/scripts/get_bills.js

Returns two lists:

  • confirmed_bills: From Tier 1 education committees (definitely education-related)
  • tier2_candidates: From Tier 2 finance committees (need filtering)

Phase 2: WebFetch Confirmed Bills

For each bill in confirmed_bills:

URL: https://app.leg.wa.gov/billsummary?BillNumber={NUM}&Year=2025

Extract full details for analysis.

Phase 3: Filter Tier 2 Candidates

For each bill in tier2_candidates:

  1. WebFetch the bill summary page
  2. Check if title/description contains education keywords
  3. If relevant, add to tracked bills list

Education keywords: school, student, teacher, education, k-12, district, ospi, classroom, principal, paraeducator, learning, instruction, curriculum, diploma, graduation, superintendent, levy, bond, capital

Phase 4: Analysis

Apply analysis framework to all tracked bills:

  • Assign priority level (HIGH/MEDIUM/LOW)
  • Categorize impact type (FISCAL/OPERATIONAL/WORKFORCE/GOVERNANCE)
  • Assess fiscal implications
  • Flag district legislator sponsorship

Phase 4: Output

Generate report in requested format and save to Obsidian:

Path: Work/PSD/Legislative/[YYYY-MM-DD].md
Tags: #legislation #psd #work

Script Usage

Main Orchestrator

# Full discovery (both tiers)
bun skills/legislative-tracker/scripts/get_bills.js

# Education committees only (Tier 1)
bun skills/legislative-tracker/scripts/get_bills.js --tier 1

# Finance committees only (Tier 2)
bun skills/legislative-tracker/scripts/get_bills.js --tier 2

# Briefing format for morning-briefing integration
bun skills/legislative-tracker/scripts/get_bills.js --format briefing

Committee Explorer

# List all active committees
bun skills/legislative-tracker/scripts/get_committees.js

# House committees only
bun skills/legislative-tracker/scripts/get_committees.js --chamber house

# Education committees only
bun skills/legislative-tracker/scripts/get_committees.js --filter education

Single Committee Query

# Get bills in a specific committee
bun skills/legislative-tracker/scripts/get_committee_bills.js \
  --committee "Education" --agency House

# Include referral history
bun skills/legislative-tracker/scripts/get_committee_bills.js \
  --committee "Education" --agency House --referrals

Single Bill Lookup

# Get WebFetch URL for a specific bill
bun skills/legislative-tracker/scripts/get_bill_info.js HB 2551 --year 2025
bun skills/legislative-tracker/scripts/get_bill_info.js "SB 6247" --year 2025

Analysis Framework

Priority Levels

LevelSymbolCriteria
HIGH🔴Direct fiscal impact >$100K, immediate deadline (<7 days), new mandates affecting operations, sponsored by district legislator
MEDIUM🟡Moderate impact, compliance changes, deadline within 30 days
LOW🟢Minimal direct impact, monitoring only, distant timeline

Impact Categories

CategoryKeywordsDescription
FISCALlevy, bond, funding, appropriationFunding formulas, levies, bonds, appropriations
OPERATIONALprocurement, transportation, facilitiesDay-to-day operations, contracts, services
WORKFORCEstaff, salary, certification, benefitsStaffing, compensation, certification requirements
GOVERNANCEreporting, accountability, boardCompliance, reporting, board authority

Fiscal Impact Indicators

IndicatorSymbolMeaning
COST INCREASE⬆️Adds expense to district budget
COST DECREASE⬇️Reduces costs or adds revenue
RISK⚠️Financial uncertainty or liability exposure
NEUTRAL➡️No direct fiscal impact to district

Output Formats

Briefing JSON (for morning-briefing)

{
  "summary": {
    "total_bills": 12,
    "new_this_period": 3,
    "urgent": 2,
    "by_priority": { "high": 2, "medium": 5, "low": 5 }
  },
  "priority_items": [
    {
      "bill": "HB 1234",
      "title": "Concerning school construction funding",
      "priority": "high",
      "impact": "fiscal",
      "fiscal_indicator": "cost_increase",
      "next_action": "House vote 2026-01-30",
      "summary": "Increases capital project funding requirements by 15%"
    }
  ],
  "upcoming_deadlines": [],
  "generated_at": "2026-01-27T08:00:00Z"
}

Full Report Markdown

# WA School Legislation Radar
Report Date: 2026-01-27
Session: 2025-26 Regular
Discovery: Committee-based (Tier 1 + Tier 2)

## 🚨 Priority Action Items

### 🔴 HIGH Priority

#### HB 1234 - School Construction Funding
- **Status:** Passed House, in Senate Education Committee
- **Sponsors:** Rep. Smith (26th), Rep. Jones
- **Impact:** FISCAL ⬆️
- **Summary:** Increases capital project funding requirements
- **Next Action:** Senate hearing Feb 1

## 📊 Legislative Dashboard

### Discovery Summary
| Source | Bills Found |
|--------|-------------|
| House Education | 15 |
| Senate EL/K-12 | 12 |
| Tier 2 (filtered) | 8 |
| **Total Unique** | **28** |

### By Priority
| Priority | Count | Bills |
|----------|-------|-------|
| 🔴 HIGH | 2 | HB 1234, SB 5678 |
| 🟡 MEDIUM | 5 | ... |
| 🟢 LOW | 5 | ... |

## 📋 All Tracked Bills

[Per-bill details grouped by priority level]

---
*Generated by Geoffrey Legislative Tracker*
*Discovery: Committee-based SOAP API*

Data Sources

SOAP API (Primary)

Endpoint: https://wslwebservices.leg.wa.gov/

ServiceMethodPurpose
CommitteeServiceGetActiveHouseCommitteesList House committee names
CommitteeServiceGetActiveSenateCommitteesList Senate committee names
CommitteeActionServiceGetInCommitteeBills currently in committee
CommitteeActionServiceGetCommitteeReferralsByCommitteeAll bills ever referred

Parameters:

  • biennium: "2025-26"
  • agency: "House" or "Senate"
  • committeeName: Exact name from GetActive*Committees

WebFetch (Bill Details)

URL Pattern: https://app.leg.wa.gov/billsummary?BillNumber={NUM}&Year=2025


District Configuration

From config/topics.yaml:

district:
  name: "Peninsula School District"
  legislators:
    - name: "Sen. Emily Randall"
      district: 26
      chamber: senate
    - name: "Rep. Spencer Hutchins"
      district: 26
      chamber: house
    - name: "Rep. Adison Richards"
      district: 26
      chamber: house

Bills sponsored by district legislators get elevated priority consideration.


Error Handling

ScenarioResponse
SOAP timeout/errorFall back to WebSearch (Tier 3)
Committee not foundCheck exact name via get_committees.js
No bills in committeeNormal - committee may not have active bills
Bill page unavailableSkip bill, note in report

Session Scope

  • Current biennium: 2025-26
  • Session types: Regular, Special (1st, 2nd, 3rd)
  • Year parameter for URLs: 2025 (uses session start year)

Related Skills

  • morning-briefing: Receives legislative JSON for audio summary
  • obsidian-manager: Stores full reports to vault
  • omnifocus-manager: (Optional) Could create tasks for urgent deadlines

Local TTS Skill

Generate high-quality speech audio locally using Apple Silicon MLX acceleration and the Kokoro-82M model. No API keys or recurring costs.

Quick Start

# Generate MP3 from text
uv run --with mlx-audio --with pydub skills/local-tts/scripts/generate_audio.py \
    --text "Hello, this is a test." \
    --output ~/Desktop/test.mp3

# Generate from file
uv run --with mlx-audio --with pydub skills/local-tts/scripts/generate_audio.py \
    --file /tmp/script.txt \
    --voice af_heart \
    --output ~/Desktop/podcast.mp3

# List available voices
uv run --with mlx-audio skills/local-tts/scripts/list_voices.py

Parameters

ParameterRequiredDefaultDescription
--textOne of text/file-Text to convert
--fileOne of text/file-Path to text file
--voiceNoaf_heartVoice preset
--outputYes-Output file path (.mp3, .wav)
--modelNoKokoro-82M-bf16Model to use
--list-voicesNo-Show available voices

Voice Presets

American English Female (prefix: af_)

  • af_heart - Warm, friendly (default)
  • af_bella - Soft, calm
  • af_nova - Clear, professional
  • af_river - Clear, confident
  • af_sarah - Soft, expressive

American English Male (prefix: am_)

  • am_adam - Clear, professional
  • am_echo - Deep, smooth
  • am_liam - Articulate, conversational
  • am_michael - Soft, measured

British English (prefix: bf_, bm_)

  • bf_emma - Clear, refined female
  • bm_daniel - Clear, professional male
  • bm_george - Distinguished male

See references/voices.md for full list.

Output Format

{
  "success": true,
  "file": "/Users/hagelk/Desktop/podcast.mp3",
  "voice": "af_heart",
  "model": "Kokoro-82M-bf16",
  "characters": 9824,
  "chunks": 20,
  "duration_seconds": 612.5,
  "generation_time": 45.2
}

Performance

HardwareSpeedNotes
M3 Pro 36GB~3-4x realtimeFirst run slower (model loading)
M1/M2 Mac Mini 8GB~1.5x realtimeWorks well for briefings
M1/M2 Mac Mini 16GB~2x realtimeComfortable headroom

Technical Details

  • Model: Kokoro-82M-bf16 (~200MB download on first run)
  • Sample rate: 24kHz mono
  • Chunking: Text split at ~400 chars per chunk for quality
  • Concatenation: Chunks joined seamlessly via pydub
  • Formats: MP3, WAV, M4A, OGG

Important Notes

  1. MUST use --with flags - Do not use PEP 723 inline deps. mlx-audio requires uv's cached environment.

  2. First run is slower - Model downloads ~200MB and espeak dependencies initialize.

  3. Model cached at: ~/.cache/huggingface/hub/models--mlx-community--Kokoro-82M-bf16/

Integration with Morning Briefing

The morning-briefing skill uses this for podcast generation:

uv run --with mlx-audio --with pydub skills/local-tts/scripts/generate_audio.py \
    --file /tmp/morning_briefing_podcast.txt \
    --voice af_heart \
    --output ~/Desktop/morning_briefing.mp3

Morning Briefing Workflow

Overview

Generates a daily morning briefing and delivers it three ways:

  1. Terminal: Summary displayed immediately
  2. Obsidian: Full briefing saved to daily note
  3. Email: Briefing text + audio podcast attachment

Location

  • Gig Harbor, WA - Use for weather queries

Phase 1: Gather Data

Execute these data gathering steps:

1.1 Calendar (Today's Events)

cd /Users/hagelk/non-ic-code/geoffrey/skills/google-workspace && bun calendar/list_events.js psd --today

Returns JSON with today's events including:

  • Event summary, location, start/end times
  • Attendees and response status
  • Hangout/meet links

Account: Use psd for work calendar

1.2 OmniFocus Tasks (Due & Flagged)

osascript -l JavaScript /Users/hagelk/non-ic-code/geoffrey/skills/morning-briefing/scripts/get_due_flagged.js

Returns tasks that are:

  • Due today or overdue
  • Flagged
  • Available (not blocked, not deferred to future)

1.3 Recent Emails (Last 24 Hours)

# Get yesterday's date in Gmail query format
YESTERDAY=$(date -v-1d +%Y/%m/%d)
cd /Users/hagelk/non-ic-code/geoffrey/skills/google-workspace && bun gmail/list_messages.js psd --query "in:inbox after:$YESTERDAY" --max 15

Returns recent inbox messages with:

  • From, subject, date, snippet
  • Whether read or unread
  • Thread ID for context
  • Labels array

Filtering: Only show emails still in inbox (not already labeled/processed).

  • Emails with custom labels (Label_XXXXX) have been sorted and should be excluded
  • Exception: Include emails with SaneCC or SaneLater labels (worth knowing about)
  • System labels (UNREAD, INBOX, CATEGORY_*, IMPORTANT) don't count as "processed"

Philosophy: Any email still in inbox from last 24 hours needs attention, read or not.

Account: Use psd for work email

1.4 Open Freshservice Tickets

bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/list_tickets.js '{"workspace_id": 2, "filter": "new_and_my_open"}'

Returns open tickets assigned to or created by user in Technology workspace.

1.5 Pending Approvals

bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/get_approvals.js requested

Returns service requests awaiting approval.

1.6 Weather

Use WebSearch:

Gig Harbor WA weather today forecast

Extract:

  • Current conditions
  • High/low temperature
  • Precipitation chance
  • Any alerts

1.7 EdTech News (with Synopses)

Use WebSearch:

K-12 education technology news past 24 hours January 2026

For each article found (3-5 articles):

  1. Use WebFetch to read the full article
  2. Extract a 2-3 sentence synopsis covering:
    • What happened / what's new
    • Why it matters for K-12 education
    • Key takeaway or action item

Freshness check: Verify article dates before including. Only include articles published within the last 24 hours. Skip older articles even if they appear in results.

Topics to cover:

  • EdTech product launches and updates
  • School technology policy changes
  • Cybersecurity in schools
  • Digital learning trends

1.8 AI News (with Synopses)

Use WebSearch:

artificial intelligence news past 24 hours January 2026 latest

For each article found (3-5 articles):

  1. Use WebFetch to read the full article
  2. Extract a 2-3 sentence synopsis covering:
    • What's the development
    • Industry impact
    • Relevance to education/work

Freshness check: Verify article dates before including. Only include articles published within the last 24 hours. Skip older articles even if they appear in results.

Topics to cover:

  • Major AI model releases and capabilities
  • AI policy and regulation
  • Enterprise AI adoption
  • AI research breakthroughs

1.9 K-12 Leadership News (with Synopses)

Use WebSearch:

K-12 school leadership superintendent news past 24 hours January 2026

For each article found (2-3 articles):

  1. Use WebFetch to read the full article
  2. Extract a 2-3 sentence synopsis covering:
    • Policy or leadership development
    • Impact on districts/schools
    • Relevance to CIO/technology leadership

Freshness check: Verify article dates before including. Only include articles published within the last 24 hours. Skip older articles even if they appear in results.

Topics to cover:

  • State and federal education policy
  • Superintendent and board news
  • School funding and budgets
  • Workforce and staffing trends

1.9b School Safety & Security News (with Synopses)

Use WebSearch:

K-12 school safety security news past 24 hours January 2026

For each article found (3 articles):

  1. Use WebFetch to read the full article
  2. Extract a 2-3 sentence synopsis covering:
    • What happened / what's new
    • Impact on school safety practices
    • Key takeaway for districts

Freshness check: Verify article dates before including. Only include articles published within the last 24 hours. Skip older articles even if they appear in results.

Topics to cover:

  • School security incidents and responses
  • Safety policy changes
  • Emergency preparedness
  • Mental health and threat assessment
  • Physical security technology

1.10 Technology Team EOD Messages (Last Business Day) - DETAILED

Get end-of-day check-in messages from the Technology Staff space:

cd /Users/hagelk/non-ic-code/geoffrey/skills/google-workspace && bun chat/get_eod_messages.js psd spaces/AAAAxOtpv10 last-business-day

CRITICAL - NO HALLUCINATION:

  • ONLY use names that appear in the sender field of the script output
  • If script returns no messages, say "No EOD messages found"
  • If script returns messages with sender IDs instead of names, display the ID (e.g., "users/12345...")
  • NEVER invent names, locations, or accomplishments
  • Copy-paste approach: treat script output as source of truth

Before extracting team data:

  1. Examine the raw JSON output from the script
  2. List the exact sender values returned
  3. Use ONLY those names - no paraphrasing, no "improving"

CRITICAL: Extract FULL details from each team member's EOD message. Look for messages that contain "Today:" prefix - these are the detailed EOD summaries.

For each team member who posted an EOD summary:

  1. Name: Who posted (use EXACTLY the name from sender field)
  2. Location(s): Where they worked (WFH, DCRC, school sites)
  3. Key accomplishments: Specific tasks completed (not just "tickets")
  4. Notable items: Interesting problems solved, projects worked on
  5. Issues/blockers: Any problems mentioned

Example extraction from raw message:

Brad White:
- Location: TSD (Tech Services)
- Accomplished: Packaged Cinema 4D plugin for deployment, fixed OAuth blocking for Maxon App sign-in, created SwiftDialog notification for plugin installs, used Claude Code for first time to create Installomator label for Godot game engine
- Notable: Working on Unity deployment troubleshooting, burning comp time leaving early

Note: If today is Monday, "last business day" = Friday (or Thursday if Friday was a holiday).

1.10b Safety & Security Team EOD Messages (Last Business Day)

Get end-of-day check-in messages from the Safety & Security Staff space:

cd /Users/hagelk/non-ic-code/geoffrey/skills/google-workspace && bun chat/get_eod_messages.js psd spaces/AAAAFpQaAnA last-business-day

Space: PSD Safety & Security Team

CRITICAL - NO HALLUCINATION:

  • ONLY use names that appear in the sender field of the script output
  • If script returns no messages, say "No EOD messages found"
  • If script returns messages with sender IDs (e.g., "users/12345...") instead of names:
    • Display as: Unknown (users/123456...) - [Location from message content]
    • Add note: "Name not in mapping - update chat_user_mapping.json"
  • NEVER invent names, locations, or accomplishments
  • Copy-paste approach: treat script output as source of truth

Before extracting team data:

  1. Examine the raw JSON output from the script
  2. List the exact sender values returned
  3. Use ONLY those names - no paraphrasing, no "improving"

Extract using same format as Technology Team - names, locations, accomplishments, issues.

Note: If today is Monday, "last business day" = Friday (or Thursday if Friday was a holiday).

1.11 Team Completed Tickets (Last Business Day)

Get tickets closed by the Technology team on the last business day:

# First get the last business day
LAST_BIZ_DAY=$(bun /Users/hagelk/non-ic-code/geoffrey/skills/morning-briefing/scripts/get_last_business_day.js | jq -r '.date')

# Then get daily summary for that date
bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/get_daily_summary.js "$LAST_BIZ_DAY"

CRITICAL - NO HALLUCINATION:

  • ONLY use agent names that appear in the byAgent section of script output
  • Use EXACTLY the ticket counts returned by the script
  • NEVER invent names or ticket counts
  • If an agent's name shows as ID or email, display it as-is

Before reporting ticket stats:

  1. Examine the raw JSON output from get_daily_summary.js
  2. List the exact agent names from byAgent field
  3. Use ONLY those names and counts

Returns:

  • Total tickets closed
  • Breakdown by agent
  • Breakdown by category (Password Reset, Chromebook, etc.)
  • Automated vs agent-resolved

Workspace: Technology (workspace_id: 2)

1.12 Ticket Trends Analysis

Compare last business day to previous days for trends:

# Get last 5 business days of summaries for trend analysis
# The get_daily_summary.js script supports date parsing
bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/get_daily_summary.js "last monday"
bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/get_daily_summary.js "last tuesday"
# etc.

Analyze for:

  • Volume trends (increasing/decreasing)
  • Category spikes (sudden increase in specific issue types)
  • Agent workload distribution
  • Unusual patterns

1.13 Software Development Workspace Tickets

Get open tickets in the Software Development workspace:

bun /Users/hagelk/non-ic-code/geoffrey/skills/freshservice-manager/scripts/search_tickets.js "status:2 OR status:3" 13

Returns all open (status:2) and pending (status:3) tickets in the Software Development workspace.

Workspace ID: 13 (Software Development) Note: This is the user's internal software development bug tracker for AI Studio and other PSD applications.

1.14 Legislative Activity (Last Business Day)

Get K-12 education bills with activity since the last business day:

# Get lookback info and bills to check
bun /Users/hagelk/non-ic-code/geoffrey/skills/legislative-tracker/scripts/get_recent_bill_activity.js --last-business-day

This returns:

  • Date range to check (last business day → today)
  • List of ~143 confirmed education bill IDs
  • WebFetch instructions for each bill

Workflow:

  1. Get the output from get_recent_bill_activity.js
  2. WebFetch each bill URL (batch 5-6 in parallel for speed)
  3. Extract latest action date from each bill page
  4. Filter to bills where latest_action_date >= lookback_start
  5. Apply priority framework (HIGH/MEDIUM/LOW based on district impact)
  6. Include summary of what each bill does

On Monday: Lookback starts on Friday (or earlier if Friday was a holiday), so includes all weekend activity (hearings, votes, committee actions).

Example URLs to WebFetch:

  • https://app.leg.wa.gov/billsummary?BillNumber=1020&Year=2025
  • https://app.leg.wa.gov/billsummary?BillNumber=5038&Year=2025

Note: Only include bills that actually had activity. If no bills moved, output "No legislative activity since [date]".

Phase 2: Generate Briefing

2.1 Analyze & Prioritize

Review gathered data and identify:

  • Conflicts: Overlapping calendar events
  • Urgencies: Overdue tasks, high-priority tickets
  • Themes: Patterns across data sources

2.2 Format Markdown Briefing

Use this structure:

# Daily Briefing - [DATE]

## Weather
[Current conditions, high/low, precipitation]

## Today's Calendar
| Time | Event | Location |
|------|-------|----------|
| ... | ... | ... |

**Conflicts/Notes**: [any issues]

## Priority Tasks
### Due Today
- [ ] Task 1
- [ ] Task 2

### Flagged
- [ ] Task 3

### Overdue
- [ ] Task 4 (due [date])

## Recent Emails (Last 24h)
[X emails in inbox from last 24 hours]

### Needs Response
- From: [sender] - [subject] (snippet)
- From: [sender] - [subject] (snippet)

### FYI/Notifications
- [sender] - [subject]

## Freshservice
### Technology Tickets: [count] open
[Top 3-5 tickets by priority/age]

### Software Development Tickets: [count] open
[List tickets in Software Dev workspace]

### Pending Approvals: [count]
[List with ticket #, requester, summary]

## Team Activity (Last Business Day: [DAY, DATE])

**Data Source Verification (REQUIRED):**
- Technology EOD script returned: [X] messages from [list exact sender names from JSON]
- Safety & Security EOD script returned: [X] messages from [list exact sender names from JSON]
- Freshservice daily summary returned: [X] tickets by [list exact agent names from JSON]

*Use ONLY the names listed above. Never invent or paraphrase names.*

### Technology Team EOD Summaries

**[Name from sender field]** - [Location(s)]
- [Key accomplishment 1 - be specific about what they did]
- [Key accomplishment 2]
- [Notable: any interesting problems solved or projects]

**[Name from sender field]** - [Location(s)]
- [Key accomplishment 1]
- [Key accomplishment 2]
- [Issues: any blockers or problems mentioned]

*[Continue for each team member who posted an EOD summary]*

### Safety & Security Team EOD Summaries

**[Name from sender field]** - [Location(s)]
- [Key accomplishment 1]
- [Key accomplishment 2]
- [Notable: any issues or incidents handled]

*If sender shows as user ID (users/12345...), display: **Unknown (users/12345...)** - [Location]*

*[Continue for each team member who posted an EOD summary]*

### Tickets Completed by Team: [count]
| Agent | Tickets | Top Categories |
|-------|---------|----------------|
| [Name from byAgent field] | X | Password Reset (Y), Chromebook (Z) |

### Ticket Trends
- Volume: [up/down/stable] vs previous days
- Notable patterns: [any spikes or anomalies]

## EdTech News

### [Article Title 1] - [Source]
[2-3 sentence synopsis: what happened, why it matters, key takeaway]

### [Article Title 2] - [Source]
[2-3 sentence synopsis]

### [Article Title 3] - [Source]
[2-3 sentence synopsis]

## AI News

### [Article Title 1] - [Source]
[2-3 sentence synopsis: what's the development, industry impact, relevance]

### [Article Title 2] - [Source]
[2-3 sentence synopsis]

### [Article Title 3] - [Source]
[2-3 sentence synopsis]

## K-12 Leadership News

### [Article Title 1] - [Source]
[2-3 sentence synopsis: policy/leadership development, impact, relevance to tech leadership]

### [Article Title 2] - [Source]
[2-3 sentence synopsis]

## School Safety & Security News

### [Article Title 1] - [Source]
[2-3 sentence synopsis: what happened, impact on safety practices, takeaway for districts]

### [Article Title 2] - [Source]
[2-3 sentence synopsis]

### [Article Title 3] - [Source]
[2-3 sentence synopsis]

## Legislative Activity ([Last Biz Day] - Today)

[X] education bills had movement:

### 🔴 HIGH Priority

#### [Bill ID] - [Short Title]
**Action**: [What happened - hearing, vote, committee action, etc.]
**Summary**: [1-2 sentences: what the bill does, potential district impact]

### 🟡 MEDIUM Priority

#### [Bill ID] - [Short Title]
**Action**: [What happened]
**Summary**: [1-2 sentences]

### 🟢 LOW Priority
- [Bill ID]: [Action type] - [One line summary]

*No legislative activity since [date]* - if no bills moved

## Quick Stats
- Calendar events: X
- Tasks overdue: X | Due today: X | Flagged: X
- Open tickets (Tech): X
- Open tickets (Software Dev): X
- Pending approvals: X
- Recent emails (24h): X
- Team tickets closed [last biz day]: X
- News articles: EdTech (X) | AI (X) | Leadership (X)
- Legislative bills with activity: X

2.3 Generate Podcast Script (Extended Format)

Transform the briefing into a comprehensive conversational audio script:

  • First person, casual professional tone
  • 10-15 minutes speaking time (~1500-2000 words)
  • Address listener directly ("Here's what you need to know today...")

Required Sections (in order):

  1. Opening (~100 words)

    • Day, date, weather summary
    • Quick preview of key items
  2. Calendar & Schedule (~150 words)

    • Today's events with context
    • Highlight key meetings/events
    • Note any conflicts or prep needed
  3. Tasks & Priorities (~150 words)

    • Overdue items that need attention
    • Due today items
    • Flagged priorities
  4. Tickets & Service Desk (~150 words)

    • Open Technology tickets
    • Software Development tickets
    • Pending approvals
  5. Team Activity - DETAILED (~400 words)

    • What the Technology team accomplished on last business day
    • Highlight 3-5 team members by name with specifics
    • Notable projects, interesting problems solved
    • What the Safety & Security team accomplished
    • Overall ticket closure stats

    CRITICAL - NO HALLUCINATION:

    • Use ONLY names from the script output sender fields
    • Use ONLY ticket counts from the get_daily_summary.js output
    • If script returned no messages, say "No EOD messages were posted"
    • NEVER invent names, locations, or accomplishments
  6. EdTech News (~200 words)

    • 2-3 articles with synopses
    • Why each matters for K-12
  7. AI News (~200 words)

    • 2-3 articles with synopses
    • Industry impact and relevance
  8. K-12 Leadership News (~150 words)

    • 1-2 articles with synopses
    • Policy/leadership implications

8b. School Safety & Security News (~150 words)

  • 2-3 articles with synopses
  • Safety practices and district implications
  1. Legislative Update (~150 words)

    • Bills that had hearings, votes, or readings since last business day
    • Highlight any with direct district impact (fiscal, operational, staffing)
    • Note upcoming hearing dates if relevant
    • On Mondays, include weekend activity summary
  2. Closing (~100 words)

    • Top 3 priorities for the day
    • Sign off

Style Guidelines:

  • Use team members' first names when discussing their work
  • Include specific details (not "worked on tickets" but "resolved 34 Chromebook repairs")
  • Transition smoothly between sections
  • Add brief commentary/analysis on news items

Save to /tmp/morning_briefing_podcast.txt

Phase 3: Create Podcast

uv run --with mlx-audio --with pydub /Users/hagelk/non-ic-code/geoffrey/skills/local-tts/scripts/generate_audio.py \
  --file /tmp/morning_briefing_podcast.txt \
  --voice af_heart \
  --output ~/Desktop/morning_briefing_[DATE].mp3

Voice Selection: af_heart (warm, friendly - good for morning briefing) Note: Uses local MLX TTS (Kokoro model) - no API costs

Phase 3.5: Generate Infographic (MANDATORY)

CRITICAL: The infographic MUST be generated. Do not skip this phase.

Create a visual summary infographic using the image-gen skill.

3.5.1 Build Infographic Prompt

Based on gathered data, construct a prompt for the infographic:

Create an infographic summarizing a daily work briefing for [DATE].

Visual concept: A clean dashboard layout with distinct sections for different data categories.

Key data to display:
- Weather: [conditions], High [X]°F, Low [Y]°F
- Calendar: [X] events today, highlight: [key meeting]
- Tasks: [X] overdue, [Y] due today, [Z] flagged
- Tickets: [X] Technology open, [Y] Software Dev open
- Team Activity: [X] tickets closed by team yesterday
- Emails: [X] in inbox from last 24h

Style: Professional, clean design with PSD brand colors (navy blue #003366, gold accent #FFD700).
Flat design, clear sections, modern sans-serif typography.

Layout: Horizontal 16:9, organized as a dashboard with weather top-left, calendar top-right,
tasks and tickets in middle row, team stats at bottom.

Title: "Daily Briefing - [DATE]"
Subtitle: "Gig Harbor, WA"

3.5.2 Generate Image

uv run /Users/hagelk/non-ic-code/geoffrey/skills/image-gen/scripts/generate.py \
  "[infographic prompt]" \
  ~/Desktop/morning_briefing_[DATE].png \
  16:9 \
  2K

Settings:

  • Aspect ratio: 16:9 (landscape dashboard)
  • Size: 2K (ensures text readability)
  • Output: ~/Desktop/morning_briefing_[DATE].png

Phase 4: Save to Obsidian

4.1 Copy Infographic to Obsidian Assets

cp ~/Desktop/morning_briefing_[DATE].png \
  ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents/Personal_Notes/Geoffrey/Daily\ Briefings/assets/

4.2 Add Infographic to Briefing Markdown

At the top of the briefing (after the title), add:

![Daily Briefing Infographic](assets/morning_briefing_[DATE].png)

4.3 Save Briefing File

Use Obsidian MCP tools:

  1. Check if daily note exists:

    mcp__obsidian-vault__get_vault_file
    filename: "Geoffrey/Daily Briefings/[YYYY-MM-DD].md"
    
  2. Create or update:

    mcp__obsidian-vault__create_vault_file
    filename: "Geoffrey/Daily Briefings/[YYYY-MM-DD].md"
    content: [full briefing markdown with infographic embed]
    

File path pattern: Geoffrey/Daily Briefings/YYYY-MM-DD.md

Fallback (if MCP unavailable): Write directly to iCloud path:

/Users/hagelk/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/Geoffrey/Daily Briefings/[YYYY-MM-DD].md

Phase 5: Send Email (HTML with Inline Infographic)

5.1 Generate HTML Email Body

Create a professional HTML email (NOT markdown). Use the template at skills/morning-briefing/templates/email.html as reference.

Key HTML structure:

<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width: 600px; margin: 0 auto; }
    .header { text-align: center; border-bottom: 2px solid #003366; padding: 16px; }
    .stat-box { background: #f8f9fa; padding: 12px; text-align: center; }
    /* ... more styles from template ... */
  </style>
</head>
<body>
  <!-- Infographic at TOP - referenced via cid:briefing_image -->
  <img src="cid:briefing_image" alt="Daily Briefing" style="width: 100%; max-width: 600px; border-radius: 8px; margin-bottom: 20px;">

  <div class="header">
    <h1 style="color: #003366;">Daily Briefing</h1>
    <p>[DAY_OF_WEEK], [DATE_FORMATTED]</p>
  </div>

  <!-- Weather, Stats, Calendar, Tasks, Team, News sections -->
  <!-- See templates/email.html for full structure -->

  <div style="background: #e8f4f8; padding: 16px; border-radius: 8px; margin-top: 20px;">
    <strong>Attachments:</strong><br>
    🎧 Audio Podcast (~10-15 min)<br>
    📊 Infographic (also shown above)
  </div>

  <p style="text-align: center; color: #666; font-size: 12px;">
    Full briefing: Obsidian/Geoffrey/Daily Briefings/[DATE].md
  </p>
</body>
</html>

CRITICAL: The <img src="cid:briefing_image"> displays the infographic inline at the top of the email.

Save to /tmp/morning_briefing_email.html

5.2 Send with Inline Image + Attachments

cd /Users/hagelk/non-ic-code/geoffrey/skills/google-workspace && bun gmail/send_with_attachments.js psd \
  --to "hagelk@psd401.net" \
  --subject "Daily Briefing - [DATE]" \
  --body-file /tmp/morning_briefing_email.html \
  --html \
  --inline-image "~/Desktop/morning_briefing_[DATE].png" \
  --attachments "~/Desktop/morning_briefing_[DATE].mp3"

Options explained:

  • --html - Treat body as HTML (required for formatting)
  • --inline-image - Embeds image at top of email (referenced as cid:briefing_image)
  • --attachments - Additional files to attach (podcast)

Result:

  • Infographic displays INLINE at top of email (visible without downloading)
  • Podcast attached for download
  • Email renders nicely in Gmail with professional styling

Output

Return standardized summary:

## Summary
Generated daily briefing for [DATE]

## Actions
- Gathered calendar events: X
- Gathered tasks: X (Y due today, Z flagged)
- Gathered Technology tickets: X open, Y approvals pending
- Gathered Software Dev tickets: X open
- Gathered team EOD messages: X from [last business day]
- Gathered team completed tickets: X from [last business day]
- Weather: [conditions]
- News: X headlines
- Generated podcast: ~/Desktop/morning_briefing_[DATE].mp3
- Saved to Obsidian: Geoffrey/Daily Briefings/[DATE].md
- Email: [sent/skipped - reason]

## Status
[Status emoji] [Complete/Partial]

## Quick View
[2-3 line summary of most important items]

Error Handling

Missing Google Workspace Scripts

If calendar/email scripts don't exist:

  • Skip those sections
  • Note "Integration pending" in output
  • Continue with available data sources

OmniFocus Not Running

Status: Partial
Note: OmniFocus not running - task data unavailable

Freshservice API Error

Status: Partial
Note: Freshservice API error - ticket data unavailable

Local TTS Generation Failed

Status: Partial
Note: Audio generation failed - check mlx-audio setup
Briefing saved to Obsidian without podcast

Dependencies

Skill/ToolRequired ForFallback
google-workspaceCalendar, email, team EODSkip sections
omnifocus-managerTasksSkip section
freshservice-managerTickets, approvals, team statsSkip section
local-ttsAudio podcastText-only briefing
obsidian-vault (MCP)Save briefingDisplay only
WebSearchNews, weatherSkip sections

Configuration

User Preferences

  • Location: Gig Harbor, WA (weather)
  • Work Email: psd account
  • Technology Workspace: workspace_id: 2
  • Software Dev Workspace: workspace_id: 13
  • Technology Chat Space: spaces/AAAAxOtpv10 (Technology Staff Check-Ins & Logs)
  • Safety & Security Chat Space: spaces/AAAAFpQaAnA (PSD Safety & Security Team)
  • Voice: af_heart (warm, friendly - local Kokoro TTS)
  • Podcast Length: 10-15 minutes (~1500-2000 words)

Customization

Users can request:

  • "Skip news" - omit news section
  • "No podcast" - text only
  • "Just calendar and tasks" - minimal briefing

Multi-Model Research Agent

Implements Karpathy's LLM Council pattern for superior research through parallel queries, peer review, and chairman synthesis.

Architecture

Geoffrey/Claude (Native Council Member):

  • Routes simple vs complex queries
  • Calls external API orchestrator (research.py)
  • Provides my own research response
  • Conducts peer review phase
  • Requests GPT-5.1 synthesis (chairman)
  • Saves final report to Obsidian

Python External API Orchestrator:

  • Fetches responses from GPT-5.1, Gemini 3.0 Pro, Perplexity Sonar, Grok 4.1
  • Returns JSON with all external responses
  • I handle all orchestration and synthesis

When to Use This Skill

Use multi-model research when:

  • Complex analysis needed - Multiple perspectives valuable
  • Factual verification critical - Cross-model validation
  • Comprehensive coverage required - No single model sufficient
  • Current information essential - Perplexity provides web grounding
  • Contested topics - Benefit from diverse model perspectives

Simple vs Council Mode

Simple Mode (Perplexity only):

  • Factual lookups
  • Current events
  • Quick research with citations
  • Completes in <15 seconds

Council Mode (Full council):

  • Comparative analysis
  • Deep research
  • Multiple perspectives needed
  • Strategic questions
  • Completes in <90 seconds

Workflow

Simple Query

User: "What are the latest developments in quantum computing?"
     ↓
I decide: Simple query (factual, current)
     ↓
I call: uv run scripts/research.py --query "..." --models perplexity
     ↓
I read: JSON response from Perplexity
     ↓
I format: Markdown report with citations
     ↓
I save: To Obsidian Geoffrey/Research folder
     ↓
I return: Summary to user with Obsidian link

Council Query

User: "Compare the AI strategies of OpenAI, Anthropic, and Google"
     ↓
I decide: Council query (comparative, complex)
     ↓
I call: uv run scripts/research.py --query "..." --models gpt,gemini,perplexity,grok
     ↓
I read: JSON with all external responses
     ↓
I provide: My own (Claude) research response
     ↓
I conduct: Peer review (each model ranks others)
     ↓
I request: GPT-5.1 chairman synthesis
     ↓
I format: Comprehensive markdown report
     ↓
I save: To Obsidian Geoffrey/Research folder
     ↓
I return: Summary with Obsidian link

Output Format

All research reports saved to Obsidian include:

  • Executive Summary (2-3 paragraphs)
  • Key Findings (organized by theme, inline citations)
  • Confidence Assessment (what's certain vs debated)
  • References Section (all sources with URLs and dates)

Citations use numeric format: [1], [2], etc.

Technical Details

Python Script:

cd skills/multi-model-research
uv run scripts/research.py --query "Your question" --models perplexity --output /tmp/responses.json

Config:

  • config.yaml - Model settings, routing rules
  • prompts/system_prompts.yaml - Per-model system prompts
  • prompts/peer_review.md - Peer review template
  • prompts/chairman_synthesis.md - GPT-5.1 synthesis template

Dependencies:

  • httpx (async HTTP client)
  • pyyaml (config parsing)
  • python-dotenv (env vars)
  • python-frontmatter (Obsidian frontmatter)

API Keys Required:

  • OPENAI_API_KEY (GPT-5.1)
  • GEMINI_API_KEY (Gemini 3.0 Pro)
  • PERPLEXITY_API_KEY (Sonar Pro)
  • XAI_API_KEY (Grok 4.1)

All keys configured in ~/.env file.

Examples

Simple Research:

User: "What is RAG in AI?"

I route to: Simple mode (Perplexity)
Output: Concise explanation with current examples and citations
Time: ~10 seconds

Council Research:

User: "Compare serverless vs containers for production ML workloads"

I route to: Council mode (all 4 external + me)
Process:
  1. GPT-5.1: Provides comprehensive technical comparison
  2. Gemini 3.0: Analyzes cost and performance trade-offs
  3. Perplexity: Current industry trends and case studies
  4. Grok 4.1: Developer sentiment from X/Twitter
  5. Claude (me): Synthesize with nuanced analysis
  6. Peer review: Each model ranks others
  7. GPT-5.1 (chairman): Final synthesis

Output: Multi-perspective analysis with citations
Time: ~60 seconds

Limitations

  • Cost: Council mode uses 4-5 API calls per query
  • Latency: Council mode takes 60-90 seconds
  • API Limits: Rate limits may throttle parallel requests
  • Citation Quality: Non-Perplexity models require URL extraction

Future Enhancements

  • Streaming responses during deliberation
  • Cost tracking and budget limits
  • Query history and versioning
  • Custom model weights based on topic
  • Integration with Geoffrey's knowledge base

This skill implements Karpathy's LLM Council pattern released November 22, 2025.

Obsidian Manager Skill

Manage the user's Obsidian vault as a persistent second brain. Read existing knowledge, write new content, and search across years of highlights and notes.

Vault Configuration

Path: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/

Write Mode: Auto-create new files, confirm before updating existing files.

Vault Structure

Personal_Notes/
├── Geoffrey/              # Geoffrey-generated content
│   ├── Mission Control.md # Central dashboard (Dataview queries)
│   ├── Scheduled Tasks.md # Scheduler dashboard
│   ├── Research/          # Research task outputs
│   │   ├── Daily AI Briefings/  # Daily automated research
│   │   ├── {Project}/     # Other research projects
│   │   └── attachments/   # Research images
│   ├── Reports/           # Generated reports and artifacts
│   │   ├── PSD/           # Peninsula School District reports
│   │   │   ├── Discipline/    # Discipline reports and infographics
│   │   │   ├── Enrollment/    # Enrollment reports
│   │   │   ├── Tech Support/  # Tech support dashboards
│   │   │   └── {topic}/       # Other PSD topics
│   │   ├── HRG/           # Hat Rack Group (consulting LLC) reports
│   │   │   └── {topic}/       # HRG topics
│   │   ├── Personal/      # Personal reports
│   │   │   └── {topic}/       # Personal topics
│   │   └── {org}/         # Other organizations as needed
│   ├── Daily-Logs/        # Session summaries (YYYY-MM-DD.md)
│   ├── Learnings/         # Extracted patterns (YYYY-MM-DD-topic.md)
│   └── Decisions/         # Major decisions with rationale (YYYY-MM-DD-topic.md)
├── Meetings/              # Meeting notes (YYYY-MM-DD format)
├── People/                # Contact profiles with metadata
├── Readwise/              # Synced highlights (368 articles, 34 books)
│   ├── Articles/
│   ├── Books/
│   ├── Podcasts/
│   └── Tweets/
├── Snipd/                 # Podcast highlights (58+ episodes)
│   └── Data/              # Podcast folders > episodes
└── Templates/             # Note templates

CRITICAL: See CLAUDE.md "Obsidian Organizational Rules" section for:

  • Strict folder structure requirements
  • File naming conventions
  • Routing rules by content type
  • Validation checklist before writing

Always validate folder placement before writing any files to Geoffrey folder.

Scripts

All scripts use Python via uv run with inline dependencies.

Search Scripts

search.py - General Vault Search
uv run scripts/search.py "query" [folder] [--limit N]

Search across the vault for keyword matches. Returns file paths and matching excerpts.

Examples:

# Search entire vault
uv run scripts/search.py "prompt engineering"

# Search specific folder
uv run scripts/search.py "leadership" People

# Limit results
uv run scripts/search.py "AI" Readwise/Articles --limit 10
search-readwise.py - Search Highlights
uv run scripts/search-readwise.py "query" [--author "name"] [--category articles|books|podcasts]

Search Readwise highlights by topic, author, or category.

Examples:

# Search by topic
uv run scripts/search-readwise.py "second brain"

# Search specific author
uv run scripts/search-readwise.py "AI" --author "Andrej Karpathy"

# Search books only
uv run scripts/search-readwise.py "habits" --category books
search-snipd.py - Search Podcast Transcripts
uv run scripts/search-snipd.py "query" [--show "podcast name"]

Search Snipd podcast transcripts and snips.

Examples:

# Search all podcasts
uv run scripts/search-snipd.py "machine learning"

# Search specific show
uv run scripts/search-snipd.py "leadership" --show "Huberman Lab"

Creation Scripts

create-note.py - Create New Note
uv run scripts/create-note.py "title" "content" [--folder Geoffrey/Research] [--tags tag1,tag2] [--related "[[Note]]"]

Create a new note with proper frontmatter and optional backlinks.

Examples:

# Create research note
uv run scripts/create-note.py "AI Model Comparison" "Content here..." --folder Geoffrey/Research --tags research,ai

# Create with backlinks
uv run scripts/create-note.py "Meeting Notes" "Content..." --folder Meetings --related "[[John Smith]],[[Project Alpha]]"
open-in-obsidian.py - Open Note in Obsidian
uv run scripts/open-in-obsidian.py "path/to/note.md"

Opens the specified note in Obsidian using Actions URI.

Content Routing

CRITICAL: When creating content, use these destinations. NEVER dump files directly into Geoffrey/ - always use proper subfolders.

Content TypeFolderNaming Pattern
Research resultsGeoffrey/Research/YYYY-MM-DD-topic.md
ReportsGeoffrey/Reports/{org}/{topic}/Descriptive name with date
Images/InfographicsSame as parent reportDescriptive Name YYYY-MM-DD.png
Meeting notesMeetings/Topic - YYYY-MM-DD.md
Daily summariesGeoffrey/Daily-Logs/YYYY-MM-DD.md
LearningsGeoffrey/Learnings/topic-slug.md
DecisionsGeoffrey/Decisions/YYYY-MM-DD-decision.md
Person updatesPeople/Existing file name

Naming Rules:

  • All images/infographics MUST include date in filename
  • Format: Descriptive Name YYYY-MM-DD.png or Descriptive Name YYYY-MM-DD to YYYY-MM-DD.png for date ranges
  • Example: Peninsula High School Discipline Report 2025-11-17 to 2025-11-20.png

Reports Folder Structure: Pattern: Geoffrey/Reports/{organization}/{topic}/

Organizations:

  • PSD - Peninsula School District reports

    • Geoffrey/Reports/PSD/Discipline/
    • Geoffrey/Reports/PSD/Enrollment/
    • Geoffrey/Reports/PSD/Attendance/
    • Geoffrey/Reports/PSD/{topic}/
  • HRG - Hat Rack Group (consulting LLC) reports

    • Geoffrey/Reports/HRG/{topic}/
  • Personal - Personal reports

    • Geoffrey/Reports/Personal/{topic}/
  • {org} - Other organizations as needed

Frontmatter Standard

All Geoffrey-created notes should include:

---
created: 2025-11-23
tags: [geoffrey, research]
source: geoffrey
related:
  - "[[Related Note 1]]"
  - "[[Related Note 2]]"
---

When to Read from Vault

  • Before research tasks: Check if user has relevant Readwise highlights or existing notes
  • When people mentioned: Look up context in People folder
  • For meeting prep: Find past meetings and related notes
  • For context: Search Snipd transcripts for podcast discussions on topic

When to Write to Vault

  • After research: Save results to Geoffrey/Research/
  • Learned patterns: Extract insights to Geoffrey/Learnings/
  • Major decisions: Document with rationale in Geoffrey/Decisions/
  • Session summaries: Optional daily logs to Geoffrey/Daily-Logs/

Creating Backlinks

Always create backlinks to existing content:

  1. Search before creating: Find related notes first
  2. Use wiki-links: [[Note Title]] format
  3. Add to frontmatter: List in related: field
  4. Reference sources: Link to Readwise/Snipd sources when relevant

Example:

Based on insights from [[Readwise/Articles/Building a Second Brain]],
and discussed in [[Snipd/Data/Huberman Lab/episode-123]],
the key pattern is...

Readwise Content Format

Readwise notes have this structure:

---
Author: "Author Name"
Full Title: "Article Title"
Category: #articles
Summary: "AI-generated summary"
---

## Highlights
- Highlight text with optional tags like [[topic]]

Snipd Content Format

Snipd episodes have rich metadata:

---
episode_show: "Podcast Name"
episode_publish_date: 2024-01-15
mentioned_books: ["Book 1", "Book 2"]
snips_count: 5
---

### Snip 1
**Timestamp:** 00:15:30
> Quote text here

**Transcript:** Full context...

Actions URI Integration

Use Actions URI to interact with Obsidian app:

# Open a note
open "obsidian://actions-uri/note/open?vault=Personal_Notes&file=Geoffrey/Research/note.md"

# Create and open
open "obsidian://actions-uri/note/create?vault=Personal_Notes&file=path&content=..."

Best Practices

  1. Search before creating: Always check for existing content
  2. Link generously: Create connections between notes
  3. Use consistent tags: Match existing tag patterns
  4. Keep notes atomic: One idea per note in Learnings
  5. Include sources: Always cite Readwise/Snipd sources
  6. Respect existing structure: Don't reorganize user's folders

Output Format

When completing Obsidian operations:

## Summary
What was done

## Files
- Created: `path/to/new.md`
- Updated: `path/to/existing.md` (if confirmed)

## Related Content Found
- [[Relevant Note 1]] - why it's relevant
- [[Relevant Note 2]] - why it's relevant

## Next Steps
- Recommendations if any

OmniFocus Manager Skill

Manage OmniFocus tasks with proper project assignment, tagging, and organization based on user preferences.

When to Activate

Use this skill when user wants to:

  • Add/create tasks
  • Follow up with someone
  • Triage or review inbox
  • Clean up or organize tasks
  • Check what's due or available
  • Query task status

User Preferences

Task Creation Philosophy:

  • Always assign to a project (never leave in Inbox)
  • Always set expected completion date
  • Tag with person + "Follow Up" for 1:1 discussions
  • Use location tags for shopping tasks

Working with OmniFocus Scripting

JXA vs AppleScript: When to Use Each

Use JXA (JavaScript for Automation) for:

  • ✅ Reading data (tasks, projects, tags, inbox)
  • ✅ Creating/updating individual tasks
  • ✅ Adding tags to tasks
  • ✅ Moving tasks between projects
  • ✅ Fast, single-purpose operations

Use AppleScript for:

  • ✅ Creating projects inside folders
  • ✅ Creating folders
  • ✅ Bulk operations on multiple projects
  • ✅ Complex nested structures (folder → project → tasks)

CRITICAL DIFFERENCE:

  • External JXA scripts (via osascript -l JavaScript) have limitations
  • OmniJS (built-in JavaScript in OmniFocus app) has more capabilities
  • Documentation examples showing new Project(name, folder) work in OmniJS but NOT in external JXA scripts

Common Pitfalls & Solutions

PitfallWhy It HappensSolution
Projects created at root instead of in folderJXA parentFolder property doesn't work externallyUse AppleScript with tell folder blocks
Duplicate empty foldersScript creates folder but projects fail to nestAlways verify count of projects of folder after creation
"Can't convert types" errorsJXA type mismatch between app objects and JavaScriptUse AppleScript for complex operations
Projects appear created but aren'tScript reports success but verification shows 0 projectsAlways verify after creation, never trust script output alone
Can't delete folders via scriptFolders don't support deletion commandsManual cleanup in OmniFocus UI required

Verification Patterns

ALWAYS verify operations that modify structure:

# After creating projects in folder
tell application "OmniFocus"
  tell default document
    set projectCount to count of projects of folder "Folder Name"
    if projectCount is 0 then
      return "ERROR: Projects not in folder!"
    else
      return "SUCCESS: " & projectCount & " projects created"
    end if
  end tell
end tell

NEVER assume success based on:

  • Script completing without errors
  • Return value claiming success
  • Absence of error messages

ALWAYS verify by:

  • Counting items created
  • Checking container relationships
  • Querying actual data structure

Error Recovery Workflow

If you create projects incorrectly:

  1. STOP - Don't create more until you understand the problem
  2. VERIFY - Check actual state: projects of folder "X"
  3. CLEAN UP - Drop wrong projects: mark dropped proj
  4. NOTE - Empty folders must be manually deleted in UI
  5. FIX - Use correct method (AppleScript for folders)
  6. VERIFY AGAIN - Confirm correction worked

Available Scripts

Scripts are in ./scripts/ directory.

For JXA scripts:

osascript -l JavaScript ./scripts/script-name.js

For AppleScript:

osascript ./scripts/script-name.applescript

IMPORTANT: Always use pure JXA/AppleScript, NOT Omni Automation URL scheme. The URL scheme triggers security popups for every unique script. Direct scripting runs silently.

Key JXA Patterns (for individual tasks)

  • doc.inboxTasks.push(task) - create new tasks
  • app.add(tag, {to: task.tags}) - add existing tags (not push!)
  • task.assignedContainer = project - move to project

get_inbox.js

Returns remaining inbox tasks (matches OmniFocus Inbox perspective).

Filter logic: Tasks with no project + not completed + not dropped + not deferred to future

Output: JSON with count and task array (id, name, note, tags, dueDate)

Use when: Starting inbox triage

get_tags.js

Returns full tag hierarchy with groupings.

Output: JSON with all 129 tags organized by parent/children

Use when: Need to find correct tags for a task

get_projects.js

Returns full project/folder structure.

Output: JSON with projects and folder paths

Use when: Need to find correct project for a task

add_task.js

Creates a new task with proper tags and project.

Parameters: name, project, tags[], dueDate, deferDate, note, flagged

Use when: Creating new tasks

update_task.js

Updates any existing task (not just inbox).

Parameters: name or id, project, tags[], dueDate, deferDate

Use when: Triaging/moving tasks, adding tags

create_tag.js

Creates a new tag, optionally under a parent.

Parameters: name, parent (optional)

Use when: Tag doesn't exist for a person or category

create_projects_in_folder.applescript

CRITICAL: Creates projects INSIDE folders (not at root level).

WHY APPLESCRIPT, NOT JXA: External JXA scripts (osascript -l JavaScript) cannot reliably create projects in folders. Projects appear created but end up at root level, not in the folder. This creates duplicate folders and organizational mess.

CORRECT PATTERN (AppleScript):

tell application "OmniFocus"
  tell default document
    set myFolder to make new folder with properties {name:"Folder Name"}
    tell myFolder
      set proj to make new project with properties {name:"Project Name", note:"Description"}
      tell proj
        make new task with properties {name:"Task Name"}
      end tell
    end tell
  end tell
end tell

WRONG PATTERNS (DO NOT USE):

  • ❌ JXA: new Project(name, folderNamed('X')) - only works in OmniJS, not external scripts
  • ❌ JXA: project.folder = folder - sets property but doesn't move
  • ❌ JXA: project.parentFolder = folder - projects still at root level
  • ❌ JXA: folder.projects.push(project) - fails silently

DELETION NOTES:

  • Projects: Use AppleScript mark dropped proj command
  • Folders: Cannot be deleted via script - must delete manually in OmniFocus UI
  • Always verify folder contents before assuming success

Use when: Creating multiple projects organized in folders (annual planning, strategic priorities, etc.)

Interface for Other Skills

If another skill needs to create OmniFocus projects/tasks, use these patterns:

Creating Individual Tasks

Call directly from other skill:

osascript -l JavaScript /path/to/omnifocus-manager/scripts/add_task.js '{
  "name": "Task name",
  "project": "Project Name",
  "tags": ["Tag1", "Tag2"],
  "dueDate": "2026-01-15",
  "note": "Optional note"
}'

Creating Folder with Multiple Projects

Build AppleScript dynamically:

  1. Generate AppleScript string with folder + projects + tasks structure
  2. Write to temp file: /tmp/create_projects_TIMESTAMP.applescript
  3. Execute: osascript /tmp/create_projects_TIMESTAMP.applescript
  4. Verify: Check count of projects of folder "Folder Name" returns expected count
  5. Clean up: Remove temp file

Example structure:

tell application "OmniFocus"
  tell default document
    set targetFolder to make new folder with properties {name:"FOLDER_NAME"}
    tell targetFolder
      # Repeat for each project:
      set proj to make new project with properties {name:"PROJECT_NAME", note:"NOTE"}
      tell proj
        # Repeat for each task:
        make new task with properties {name:"TASK_NAME"}
      end tell
    end tell
  end tell
end tell

CRITICAL: Always verify after creation. Don't trust return values.

Best Practices for Folder/Project Creation

Pre-Creation Checklist

BEFORE creating projects in folders:

  1. Check for existing folders:

    tell application "OmniFocus"
      tell default document
        set folderNames to name of every folder
        return folderNames
      end tell
    end tell
    
  2. Verify folder doesn't already exist to avoid duplicates

  3. Plan the complete structure - folder name, all project names, all tasks

During Creation

CRITICAL RULES:

  1. Use AppleScript, NOT JXA for external scripts creating projects in folders
  2. Create folder FIRST using make new folder
  3. Use tell folder block for all project creation
  4. Nest tell project blocks for task creation

Post-Creation Verification

ALWAYS verify projects are in folder:

tell application "OmniFocus"
  tell default document
    set folderProjects to projects of folder "Folder Name"
    return "Found " & (count of folderProjects) & " projects"
  end tell
end tell

If count is 0:

  • Projects created at root level (wrong!)
  • Need to delete and recreate using correct AppleScript pattern

Cleanup After Errors

If you create projects incorrectly:

  1. Drop projects: mark dropped proj for each wrong project
  2. Empty folders cannot be deleted via script - must delete manually in OmniFocus UI
  3. Always verify after cleanup before recreating

Complete Example: Creating Folder with Projects

# Build AppleScript dynamically
cat > /tmp/create_folder_projects.applescript << 'EOF'
tell application "OmniFocus"
  tell default document
    set myFolder to make new folder with properties {name:"Project Folder"}
    tell myFolder
      set proj1 to make new project with properties {name:"Project 1", note:"Description"}
      tell proj1
        make new task with properties {name:"Task 1"}
        make new task with properties {name:"Task 2"}
      end tell
    end tell
  end tell
end tell
EOF

# Execute
osascript /tmp/create_folder_projects.applescript

# Verify
osascript << 'VERIFY'
tell application "OmniFocus"
  tell default document
    set projectCount to count of projects of folder "Project Folder"
    return "Created " & projectCount & " projects in folder"
  end tell
end tell
VERIFY

Tag Hierarchy Reference

Top-level categories:

  • Activity - What type of work (Creative, Coding, Writing, Reading, Research, etc.)
  • Energy - Required mental state (Full Focus, Short Dashes, Brain Dead, Low, High)
  • Location - Where to do it (Home, Grocery Stores, PSD Sites, Other Shopping)
  • People - Who's involved (Personal family, PSD staff by department)
  • Groups - Team meetings (Cabinet, Engineering Team, DLI Admin, etc.)
  • Time - When to do it (Morning, Afternoon, Evening)
  • Communications - How to communicate (Email, Phone, In Person, etc.)
  • Online - Online tools (Freshservice, Github, Google Docs)
  • Standalone - Follow Up, Waiting For, Waiting, Kiwanis

People → PSD breakdown:

  • Tech: Mel, Bill, Reese, Mark, Brad, Mason, Jordan, etc.
  • DCRC: Jodi, Terri, Laura
  • Comms: Danielle, Jake, Shana
  • ESC: Ashley, John Y, Patrick, Krestin, James, Wendy, Janna, etc.
  • SSOs: Moose, Brent

Special tags:

  • Geoffrey - tasks that AI can assist with
  • Full Focus - requires dedicated focus time

Task Routing Rules

By Task Type → Project

Task TypeProjectDefault Due
Discussions with peopleMeetings7 days
Phone callsMeetings7 days
CoSN-relatedCoSN Work7 days
Digital Promise workDigital Promise7 days
AI/automation projectsAI Studio7 days
Coding/developmentCoding Projects7 days
Research/learningResearch for Future Plans7 days
SOP/process developmentStandard Operating Procedures14 days
Form/procedure updatesDepartment Procedures7 days
District reimbursementsPurchasing & Acquisitions7 days
Travel approvals(appropriate project)14 days
Data governanceData Governance14 days
Tech support issues→ Freshservice ticketN/A

By Task Type → Tags

Task TypeTags
Discussion with person[Person name], Follow Up
Phone callPhone, Follow Up
Research tasksResearch
AI-assistable tasksGeoffrey
Focus time neededFull Focus
Admin/organizationalOrganization
Safety/security related(relevant ESC person)

Routing Signals

Goes to Meetings project:

  • "talk to [person]"
  • "discuss with"
  • "follow up with"
  • "check with"
  • "call [person/org]"
  • "get [thing] to [person]"

Goes to Research for Future Plans:

  • "look at/into"
  • "what about"
  • CISA resources
  • Training to consider
  • External resources to review

Goes to Coding Projects or AI Studio:

  • AI/automation ideas
  • "build a program"
  • Geoffrey capabilities
  • Technical tools to explore

Needs Freshservice (skip for now):

  • User-reported issues
  • Equipment requests
  • "doesn't work/load"
  • Form rebuild requests

Common Workflows

Add a Task

  1. Parse user request for: task name, person (if any), context clues

  2. Apply routing rules above to determine:

    • Project - based on task type
    • Tags - person + communication method + activity type
    • Due date - based on task type timing
  3. If tag doesn't exist, create it with create_tag.js

  4. Run add_task.js with parameters

  5. Return standardized output

Example:

User: "Follow up with Mel about the drone program"

Actions:
- Task: "Follow up with Mel about the drone program"
- Project: PSD > General Technology > Digital Innovation Leads
- Tags: Mel, Follow Up
- Due: Next 1:1 date or 7 days

Triage Inbox

  1. Get inbox tasks:

    osascript -l JavaScript ./scripts/get_inbox.js
    

    This returns only remaining tasks (no project, not completed, not dropped, not deferred)

  2. Present assumptions in batches (10-15 tasks):

    • Read task notes for context clues
    • Apply routing rules to suggest project, tags, due date
    • Flag unclear tasks that need user input
  3. Ask clarifying questions:

    • Who is [person/acronym]?
    • Which project for [ambiguous task]?
    • Should this be skipped (needs email context)?
  4. Batch update confirmed tasks:

    osascript -l JavaScript ./scripts/update_task.js '{"name":"...", "project":"...", "tags":[...], "dueDate":"..."}'
    
  5. Create missing tags/projects as needed:

    osascript -l JavaScript ./scripts/create_tag.js '{"name":"PersonName", "parent":"ESC"}'
    
  6. Skip tasks that need:

    • Email context (user needs to read first)
    • Freshservice ticket creation
    • More information to route properly

Triage output format:

## My assumptions on remaining tasks:

| # | Task | Project | Tags | Notes |
|---|------|---------|------|-------|
| 1 | task name | Meetings | Person, Follow Up | context |

**Questions:**
- #X: Who is [person]?
- #Y: Which project for this?

Which numbers need correction?

Clean Up Tasks

  1. Find tasks that are:
    • Overdue
    • Stale (no activity)
    • Missing tags
    • In wrong project
  2. Suggest actions:
    • Complete
    • Defer
    • Delete
    • Re-tag
    • Move

Error Handling

If OmniFocus not running:

Status: ❌ Failed
Error: OmniFocus is not running. Please open OmniFocus and try again.

If tag not found:

  • Check for similar tags (fuzzy match)
  • Suggest creating new tag
  • Ask user to clarify

If project not found:

  • List available projects in that domain
  • Suggest closest match
  • Ask user to specify

Output Format

Always use standardized format:

## Summary
Created task with proper tags and project assignment

## Actions
- Created task: "[task name]"
- Project: [full project path]
- Tags: [tag1, tag2, tag3]
- Due: [date]
- Notes: [if any]

## Status
✅ Complete

## Next Steps
- Task appears in [relevant perspective]
- Follow up scheduled for [date if applicable]

Future Enhancements

  • Batch task creation
  • Smart project suggestion based on content
  • Calendar integration for due dates
  • Recurring task patterns
  • Perspective queries
  • Task completion tracking

PAI Monitor

Monitor the Personal AI Infrastructure repository and identify opportunities to improve Geoffrey.

Focus Areas

When invoked with an argument, focus analysis on that area:

  • packs - Deep dive on PAI pack additions/changes
  • hooks - Hook system evolution and patterns
  • skills - Skill structure and patterns
  • patterns - Architectural patterns (memory, validation, etc.)

Without an argument, perform full analysis across all areas.


Phase 1: Fetch PAI Current State

1.1 Core Documentation

Fetch these from github.com/danielmiessler/Personal_AI_Infrastructure:

  • README.md - Overall structure and philosophy
  • CLAUDE.md - System instructions and principles
  • Check releases for version info

1.2 Pack Structure

Explore the Packs/ directory:

  • List all available packs
  • Sample key packs: hooks, algorithm, memory, skills
  • Note any new packs since last analysis

1.3 Recent Changes

  • Check recent commits for significant updates
  • Look for new patterns or breaking changes
  • Note any announcements or migration guides

Phase 2: Analyze Geoffrey Current State

2.1 Core Architecture

Read these Geoffrey files:

  • CLAUDE.md - Founding principles and guidelines
  • README.md - Current capabilities
  • .claude-plugin/plugin.json - Version info

2.2 Skills Inventory

# Glob for all skills
skills/*/SKILL.md

Create inventory of current skills and their purposes.

2.3 Pattern Identification

Identify Geoffrey's current patterns:

  • Hook system usage
  • Knowledge storage approach
  • Skill structure conventions
  • Validation patterns

Phase 3: Gap Analysis

Compare Geoffrey against PAI across these dimensions:

3.1 Pack/Skill Coverage

  • What PAI packs do we lack equivalent skills for?
  • Which packs would provide highest value?
  • Are there redundant or outdated skills?

3.2 Architectural Patterns

  • Hook system: How does PAI's compare to our hooks.json?
  • Memory system: Knowledge persistence patterns
  • Validation: Secret prevention, protected files

3.3 Documentation Patterns

  • Does PAI use VERIFY.md, INSTALL.md, or other conventions?
  • Are there documentation patterns we should adopt?

3.4 Principles Alignment

Check Geoffrey's adherence to PAI founding principles:

  • Scaffolding > Model
  • Code Before Prompts
  • Deterministic Output
  • Goal → Code → CLI → Prompts
  • Test First

3.5 New Features

  • Recent PAI additions worth adopting
  • Experimental features to watch

Phase 4: Generate Report

Create a markdown report with this structure:

# PAI Monitor Report

**Geoffrey Version:** [from plugin.json]
**PAI Version Analyzed:** [from releases or README]
**Analysis Date:** [today's date]

## Executive Summary
[2-3 sentence summary of key findings]

## PAI Recent Changes
| Date | Change | Relevance to Geoffrey |
|------|--------|----------------------|
| ... | ... | ... |

## Packs/Features We Could Adopt
| Priority | Pack/Feature | Purpose | Complexity | Notes |
|----------|-------------|---------|------------|-------|
| High | ... | ... | ... | ... |
| Medium | ... | ... | ... | ... |
| Low | ... | ... | ... | ... |

## Pattern Improvements

### 1. [Pattern Name]
- **PAI Implementation:** [how they do it]
- **Geoffrey Current:** [how we do it / missing]
- **Adoption Benefit:** [why adopt]
- **Files to Modify:** [list]

### 2. [Pattern Name]
...

## Principles Alignment Check
| PAI Principle | Geoffrey Status | Gap |
|--------------|-----------------|-----|
| Scaffolding > Model | [status] | [gap if any] |
| Code Before Prompts | [status] | [gap if any] |
| ... | ... | ... |

## Recommended Actions

### Immediate (This Week)
- [ ] Action 1
- [ ] Action 2

### Short-Term (This Month)
- [ ] Action 1
- [ ] Action 2

### Long-Term (Explore)
- [ ] Action 1
- [ ] Action 2

Key PAI Areas to Monitor

Based on repo structure, these are the primary areas:

AreaDescriptionGeoffrey Equivalent
Packs/24+ modular capability packagesskills/
Releases/Full system snapshotsplugin versions
Hook System14+ event typeshooks.json
Memory SystemKnowledge persistenceObsidian vault
Algorithm SystemISC tracking, metricscompound learnings
Validation.pai-protected.json(none currently)

Execution Notes

  1. Start with Phase 1 - Always fetch fresh PAI data, don't rely on cached knowledge
  2. Be thorough in Phase 2 - Accurate self-assessment is critical for gap analysis
  3. Prioritize in Phase 3 - Not all gaps need filling; focus on high-value opportunities
  4. Actionable Phase 4 - Every recommendation should have clear next steps

When focusing on a specific area, still provide brief context from other phases but concentrate analysis on the requested focus.

PDF to Markdown Converter

Convert PDF files to clean, well-structured Markdown. Tables become markdown tables. Images and graphics are described as text (no image files generated).

Quick Start

uv run skills/pdf-to-markdown/scripts/convert_to_markdown.py input.pdf

Output: ~/Desktop/{filename}.md

Options

FlagDescription
--no-llmSkip LLM processing (faster, images become [Image] placeholders)
--force-ocrForce OCR on all pages (for scanned PDFs)
--page-range "0,5-10"Process specific pages only

Common Use Cases

Convert a PDF with default settings

uv run skills/pdf-to-markdown/scripts/convert_to_markdown.py ~/Documents/report.pdf

Specify output location

uv run skills/pdf-to-markdown/scripts/convert_to_markdown.py report.pdf ~/Documents/report.md

Fast conversion (no image descriptions)

uv run skills/pdf-to-markdown/scripts/convert_to_markdown.py --no-llm report.pdf

Scanned PDF (force OCR)

uv run skills/pdf-to-markdown/scripts/convert_to_markdown.py --force-ocr scanned_doc.pdf

Extract specific pages

uv run skills/pdf-to-markdown/scripts/convert_to_markdown.py --page-range "0-5" large_report.pdf

Output

  • Pure Markdown text (no embedded images)
  • Tables converted to Markdown table format
  • Images/charts described as text using LLM
  • Clean formatting suitable for AI processing

Requirements

  • GEMINI_API_KEY: Required for LLM image descriptions (loaded from 1Password)
  • Use --no-llm flag if you don't have Gemini API access

First Run Note

The first run downloads ML models (~1-2GB) which are cached at ~/.cache/marker/. Subsequent runs are faster.

Technical Details

Uses Marker library:

  • 31k+ GitHub stars
  • Best-in-class PDF conversion accuracy
  • Surya OCR for 90+ languages
  • Gemini LLM integration for image understanding

PDF Processing Guide

Overview

This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see reference.md. If you need to fill out a PDF form, read forms.md and follow its instructions.

Quick Start

from pypdf import PdfReader, PdfWriter

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Extract text
text = ""
for page in reader.pages:
    text += page.extract_text()

Python Libraries

pypdf - Basic Operations

Merge PDFs
from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)
Split PDF
reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    writer = PdfWriter()
    writer.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as output:
        writer.write(output)
Extract Metadata
reader = PdfReader("document.pdf")
meta = reader.metadata
print(f"Title: {meta.title}")
print(f"Author: {meta.author}")
print(f"Subject: {meta.subject}")
print(f"Creator: {meta.creator}")
Rotate Pages
reader = PdfReader("input.pdf")
writer = PdfWriter()

page = reader.pages[0]
page.rotate(90)  # Rotate 90 degrees clockwise
writer.add_page(page)

with open("rotated.pdf", "wb") as output:
    writer.write(output)

pdfplumber - Text and Table Extraction

Extract Text with Layout
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)
Extract Tables
with pdfplumber.open("document.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            print(f"Table {j+1} on page {i+1}:")
            for row in table:
                print(row)
Advanced Table Extraction
import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        tables = page.extract_tables()
        for table in tables:
            if table:  # Check if table is not empty
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

# Combine all tables
if all_tables:
    combined_df = pd.concat(all_tables, ignore_index=True)
    combined_df.to_excel("extracted_tables.xlsx", index=False)

reportlab - Create PDFs

Basic PDF Creation
from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas

c = canvas.Canvas("hello.pdf", pagesize=letter)
width, height = letter

# Add text
c.drawString(100, height - 100, "Hello World!")
c.drawString(100, height - 120, "This is a PDF created with reportlab")

# Add a line
c.line(100, height - 140, 400, height - 140)

# Save
c.save()
Create PDF with Multiple Pages
from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate("report.pdf", pagesize=letter)
styles = getSampleStyleSheet()
story = []

# Add content
title = Paragraph("Report Title", styles['Title'])
story.append(title)
story.append(Spacer(1, 12))

body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
story.append(body)
story.append(PageBreak())

# Page 2
story.append(Paragraph("Page 2", styles['Heading1']))
story.append(Paragraph("Content for page 2", styles['Normal']))

# Build PDF
doc.build(story)

Command-Line Tools

pdftotext (poppler-utils)

# Extract text
pdftotext input.pdf output.txt

# Extract text preserving layout
pdftotext -layout input.pdf output.txt

# Extract specific pages
pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5

qpdf

# Merge PDFs
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf

# Split pages
qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
qpdf input.pdf --pages . 6-10 -- pages6-10.pdf

# Rotate pages
qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees

# Remove password
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

pdftk (if available)

# Merge
pdftk file1.pdf file2.pdf cat output merged.pdf

# Split
pdftk input.pdf burst

# Rotate
pdftk input.pdf rotate 1east output rotated.pdf

Common Tasks

Extract Text from Scanned PDFs

# Requires: pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

# Convert PDF to images
images = convert_from_path('scanned.pdf')

# OCR each page
text = ""
for i, image in enumerate(images):
    text += f"Page {i+1}:\n"
    text += pytesseract.image_to_string(image)
    text += "\n\n"

print(text)

Add Watermark

from pypdf import PdfReader, PdfWriter

# Create watermark (or load existing)
watermark = PdfReader("watermark.pdf").pages[0]

# Apply to all pages
reader = PdfReader("document.pdf")
writer = PdfWriter()

for page in reader.pages:
    page.merge_page(watermark)
    writer.add_page(page)

with open("watermarked.pdf", "wb") as output:
    writer.write(output)

Extract Images

# Using pdfimages (poppler-utils)
pdfimages -j input.pdf output_prefix

# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.

Password Protection

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()

for page in reader.pages:
    writer.add_page(page)

# Add password
writer.encrypt("userpassword", "ownerpassword")

with open("encrypted.pdf", "wb") as output:
    writer.write(output)

Quick Reference

TaskBest ToolCommand/Code
Merge PDFspypdfwriter.add_page(page)
Split PDFspypdfOne page per file
Extract textpdfplumberpage.extract_text()
Extract tablespdfplumberpage.extract_tables()
Create PDFsreportlabCanvas or Platypus
Command line mergeqpdfqpdf --empty --pages ...
OCR scanned PDFspytesseractConvert to image first
Fill PDF formspdf-lib or pypdf (see forms.md)See forms.md

Next Steps

  • For advanced pypdfium2 usage, see reference.md
  • For JavaScript libraries (pdf-lib), see reference.md
  • If you need to fill out a PDF form, follow the instructions in forms.md
  • For troubleshooting guides, see reference.md

Personal Strategic Planning Skill

Annual strategic review and goal-setting system combining interview-driven planning with evidence-based reflection across five personal life/work domains.

Note: For organizational/K-12 district strategic planning, use the strategic-planning-manager skill instead.

When to Activate

This skill activates when the user requests:

Annual Review (Primary Mode):

  • "Let's do my annual review"
  • "Help me plan for [year]"
  • "I want to do strategic planning"
  • "Set goals for next year"

Quarterly Check-In (Lighter Mode):

  • "Quarterly check-in"
  • "Review my progress"
  • "How am I tracking against my goals?"

Domain Modes: Each review covers 5 domains:

  1. CIO Role (day job - Technology, Communications, Safety/Security)
  2. Consulting/Speaking (reputation building, CoSN board, conferences)
  3. Product Development (AI products: voice app, survey tool)
  4. Real Estate Investing (portfolio management)
  5. Financial Planning (entrepreneurial income, retirement prep)

Available Scripts

scripts/generate_annual_review.py

Generates formatted annual review markdown file in Obsidian.

Usage:

uv run scripts/generate_annual_review.py '{json_data}' --year 2026

Input: JSON with interview data (all domains, goals, indicators) Output: Markdown file at Personal_Notes/Reviews/Annual/{YEAR}-Annual-Review.md

scripts/generate_quarterly_review.py

Generates quarterly check-in markdown file in Obsidian.

Usage:

uv run scripts/generate_quarterly_review.py '{json_data}' --year 2026 --quarter Q1

Input: JSON with progress data per domain Output: Markdown file at Personal_Notes/Reviews/Quarterly/{YEAR}-Q{N}-Review.md

scripts/sync_to_omnifocus.js

Creates OmniFocus projects and tasks from Priority Goals.

Usage:

osascript -l JavaScript scripts/sync_to_omnifocus.js '{json_data}'

Input: JSON with goals, indicators, actions, milestones Output: OmniFocus projects created, returns confirmation JSON

Annual Review Workflow

The annual review follows a 6-phase interview pattern modeled after the writer skill.

Phase 1: Domain Selection & Context Loading

Objective: Set scope and load relevant context for each domain.

Geoffrey:

  1. Displays 5 domains with mission from identity-core.json:

    • CIO Role → TELOS Technology/Communications/Safety sections
    • Consulting/Speaking → TELOS Economics (reputation building)
    • Product Development → Short-term goals (AI products)
    • Real Estate → TELOS Economics (income streams)
    • Financial → Long-term goals (retirement, entrepreneurial income)
  2. Asks: "Which domain(s) do you want to review?" (allow multi-select for first run)

  3. For first annual review: Offer "Retrospective (2025) + Prospective (2026)" or "Prospective only"

Output: List of selected domains with loaded context


Phase 2: Year-in-Review Reflection (Per Domain)

Objective: Ground planning in reality by examining what actually happened.

Interview Questions (one domain at a time):

Q1: "What were your top 3 priorities in [domain] this year?"

Q2: "For each priority, what actually happened?"

  • Challenge: Require evidence/outcomes, not just activities
  • Push for: Specific metrics, concrete changes, measurable results

Q3: "What worked exceptionally well in [domain]?"

  • Challenge: Require specifics, not generalities
  • Push for: Root causes of success, replicable patterns

Q4: "What underperformed or stalled?"

  • Challenge: Require root causes, not just symptoms
  • Push for: Honest assessment, systemic barriers

Q5: "What surprised you—positive or negative?"

After all domains reviewed:

Q6: "Looking across all domains, what patterns do you see?"

Q7: "What's one lesson you'd apply everywhere next year?"

Challenge Mechanisms:

  • Vague answer → "Say more? What would that look like specifically?"
  • Activity-focused → "That's what you did. What was the result?"
  • No evidence → "What metric or outcome would prove that?"

Phase 3: Strategic Direction (Per Domain)

Objective: Define clear vision for next year aligned with core mission.

Interview Questions (one domain at a time):

Q1: "At the end of [next year], what does success look like in [domain]?"

  • Must be: Specific, measurable, stakeholder-focused
  • Challenge: Push beyond vague aspirations to concrete outcomes

Q2: "Who are the primary stakeholders for [domain]?"

  • Follow-up: "For each stakeholder, what specifically changes for them if you succeed?"

Q3: "How does [domain] success contribute to your core mission?"

  • Display: Relevant TELOS section + constitution values
  • Challenge: If alignment is weak, ask "Is this the right priority?"

Q4: "What are 2-3 major initiatives or changes in [domain]?"

  • Challenge if >3: "Which would you protect if capacity gets constrained?"
  • Challenge if maintenance: "Is this strategic work or keeping lights on?"

Q5: "What will you explicitly NOT do in [domain]?"

  • This is the hardest question - use scaffolding if stuck:
    1. "What requests have you said no to—or wish you had?"
    2. "What did you consider but decide against?"
    3. "If someone proposed adding [new initiative], what would you tell them?"
    4. "What are you currently doing that you should stop?"
  • Why it matters: "Every 'yes' is an implicit 'no' to something else. If you can't name what you're not doing, you haven't made strategic choices."

Q6: "What's the biggest barrier to success in [domain]?"

  • Follow-up: "What needs to be true for you to succeed?"

Q7: "What resources/support do you need that you don't have?"

  • Challenge if "nothing": "Most meaningful work requires time, development, or coordination—not just money."

Challenge Progression:

  1. Curious: "Say more?" / "What would that look like?"
  2. Gentle push: "Help me see this concretely. If I walked into your office in December [next year], what would I notice?"
  3. Direct challenge: "This is staying abstract. Let's get specific—what's one concrete outcome?"
  4. Support scaffolding: Offer frameworks, examples, different angles

After domain completed:

  • Summarize strategic direction back to user
  • Get confirmation before moving to next domain

Phase 4: Priority Goals with Success Indicators (Per Domain)

Objective: Translate strategic direction into measurable progress.

Constraints:

  • Maximum 3 Priority Goals per domain (hard cap)
  • Each goal requires 2-3 Success Indicators with baselines + targets
  • Each goal requires Key Actions with owners, dependencies, timeline
  • Each goal requires Quarterly Milestones

Interview Process:

For each domain:

  1. Establish Priority Goals:

    • "Based on our conversation, what are your 2-3 Priority Goals for [domain]?"
    • Challenge if >3: "You've listed [N]. Research shows more than 3 priorities means none get focus. Which would you cut?"
    • Challenge if activity-focused: Reframe as outcome (e.g., "implement curriculum" → "students demonstrate deeper engagement")
  2. Define Success Indicators (for each goal):

    • "How will you know you're making progress on [goal]?"
    • Require: Current state (baseline) → Target state (end of year)
    • Accept: Both quantitative and qualitative
      • Quantitative: "Student re-enrollment: 92% → 95%"
      • Qualitative: "Faculty report feeling supported: 45% agree → 70% agree"
    • Challenge if no baseline: "How will you establish one?" or "Is this a learning year?"
    • Challenge if vague target: "Too easy or unrealistic?"
    • Challenge if activity metric: "That measures what you did, not the result. What outcome changes?"
  3. Identify Actions, Owners, Dependencies:

    • "What are the key actions that will drive [goal]?"
    • For each action:
      • Action/Project: What will be done
      • Owner: Who is accountable (a person, not committee)
      • Dependencies: Other people/teams/resources required
      • Timeline: Q1/Q2/Q3/Q4 milestones
  4. Map Quarterly Milestones:

    • "What should be true by end of Q1 (Mar 31), Q2 (Jun 30), Q3 (Sep 30), Q4 (Dec 31)?"

Challenge Mechanisms:

  • Activity → Outcome reframing: "If you do X successfully, what changes? That's the priority."
  • No baseline: "Can you establish one now? If not, note this as 'learning year' for baseline."
  • Vague targets: "If you hit this target, would you be satisfied? What would failure look like?"

After all domains completed:

  1. Confirm Alignment:
    • "Looking at all your goals together—do they clearly ladder up to your strategic direction AND to your core mission?"
    • If weak alignment: Work to adjust or note misalignment for discussion

Phase 5: Cross-Domain Integration

Objective: Portfolio view, trade-offs, advisor review, identity alignment.

Portfolio Questions:

Q1: "Looking at all 5 domains—what's the overall story of [next year]?"

Q2: "Where are you over-committed? What trade-offs do you need to make?"

Q3: "Which domain gets your BEST energy? Which gets leftovers?"

Q4: "If one domain had to be 'maintenance mode' in [next year], which and why?"

Personal Board of Directors (optional but recommended):

Q5: "Who are your 4-7 advisors across domains?"

  • For each: Name, Domain expertise, What they help with, Last consulted
  • Roles to consider: Connector, Accountability Partner, Futurist, Subject Matter Expert

Q6: "Who's missing from your board?"

  • Prompt: "Do you have a Connector (network access), Futurist (trends), Accountability Partner?"

Alignment with Identity:

Q7: "Do these goals align with your Type 3w4 achievement pattern?"

  • Context: Meaningful, competent, expert-level impact (from identity-core.json)

Q8: "Which goals leverage your Input/Analytical/Learner strengths?"

  • Display: How each goal creates opportunities for information gathering, evidence-based thinking, mastery

Q9: "Any goals that require relationship building (your 0% Blue gap)?"

  • Follow-up: "How will you handle that? Who can help?"

Q10: "Looking at your workload—where's the Type 3 stress risk?"

  • Context: Type 3 pattern = push harder when stressed
  • Prompt: "If things get overwhelming in Q2, what's your PAUSE trigger before pushing harder?"

Phase 6: Review & Finalize

Objective: Generate output, get approval, save to systems.

Geoffrey:

  1. Display Complete Annual Review

    • Use templates/annual-review-template.md format
    • Show full markdown output for review
  2. Get User Approval

    • "Does this capture your strategic plan for [year]?"
    • "What would you adjust?"
    • Iterate until confirmed
  3. Save to Obsidian

    • Run scripts/generate_annual_review.py
    • Save to Personal_Notes/Reviews/Annual/{YEAR}-Annual-Review.md
  4. Ask about OmniFocus

    • "Create OmniFocus projects from your Priority Goals now or later?"
    • If now: Run scripts/sync_to_omnifocus.js
  5. Review Personal User Guide for Updates

    • Read current User Guide: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/Geoffrey/Kris-Hagel-User-Guide.md
    • Compare to this year's review conversation:
      • Role changes (meeting cadences, team structure, responsibilities)
      • New growth areas identified
      • Communication pattern shifts
      • Changed priorities, frustrations, or energizers
      • "What drains me" / "What energizes me" updates
    • Propose specific, evidence-based updates:
      • "In this review you mentioned X, but your User Guide says Y. Should I update?"
      • "You identified [growth area] but it's not documented. Should we add it?"
    • If updates approved: Edit the User Guide and confirm changes
    • If significant changes: Suggest notifying team/peers
  6. Schedule Quarterly Reviews

    • Confirm quarterly timing: Mar 31, Jun 30, Sep 30, Dec 31
    • Add to OmniFocus as recurring tasks

Final Output:

  • Annual review markdown file (Obsidian)
  • OmniFocus projects (if requested)
  • Confirmation message with file path

Quarterly Check-In Workflow

The quarterly check-in is a lighter interview (15-20 min) focused on progress and adjustment.

Check-In Questions

For each domain with Priority Goals:

Q1: "Progress status on [Goal]?"

  • ✅ On track (will hit target)
  • ⚠️ At risk (may miss target without intervention)
  • ❌ Off track (unlikely to hit target)

Q2: "What evidence supports your assessment?"

  • Current state vs. Q{N} milestone
  • What happened this quarter?

Q3: "What's working? What's stalled?"

Q4: "Do Success Indicators still make sense?"

  • Adjust targets? (yes/no + rationale)
  • Add/remove indicators?

Q5: "What needs to change for Q{N+1}?"

  • Actions to add/drop
  • Resources needed
  • Trade-offs with other domains

After all domains:

Q6: "Overall portfolio health?"

  • Energy distribution across domains
  • Over-committed anywhere?
  • Mid-course corrections needed?

Q7: "User Guide check against this quarter's insights"

  • Read current User Guide: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/Geoffrey/Kris-Hagel-User-Guide.md
  • Compare to quarterly progress discussion:
    • Any communication preferences that changed?
    • New frustrations or energizers to document?
    • Growth areas with visible progress?
  • Propose specific updates based on evidence from this check-in
  • If updates approved: Edit and save

Check-In Output

Geoffrey:

  1. Run scripts/generate_quarterly_review.py
  2. Save to Personal_Notes/Reviews/Quarterly/{YEAR}-Q{N}-Review.md
  3. Update annual review frontmatter with link to quarterly review
  4. Confirm adjustments to OmniFocus if targets/actions changed

Output Format

Annual Review

See templates/annual-review-template.md for complete format.

Key sections:

  • Year-in-Review Summary (cross-domain patterns, lessons)
  • Per Domain: Review + Strategic Direction + Priority Goals
  • Cross-Domain Integration (portfolio, trade-offs, advisors, alignment)
  • Next Steps (quarterly reviews, OmniFocus sync, advisor shares)

Quarterly Review

See templates/quarterly-review-template.md for complete format.

Key sections:

  • Progress status per Priority Goal
  • Evidence of progress vs. milestones
  • What's working / what's stalled
  • Adjustments for next quarter
  • Portfolio health check

Integration with Existing Systems

Obsidian

Storage locations:

Personal_Notes/
└── Reviews/
    ├── Annual/
    │   └── YYYY-Annual-Review.md
    └── Quarterly/
        └── YYYY-QN-Review.md

Frontmatter:

---
created: {date}
year: {YEAR}
domains: [CIO, Consulting, Product, RealEstate, Financial]
status: Draft | Final
quarterly_reviews:
  - Q1: [[YYYY-Q1-Review]]
  - Q2: null
  - Q3: null
  - Q4: null
---

OmniFocus

Project structure:

  • [Domain] - [Goal Name] (e.g., "CIO Role - Improve AI Adoption")
  • Tasks for each action (owner/dependencies in notes)
  • Milestones as tasks with Q1/Q2/Q3/Q4 due dates
  • Tags: domain name + "2026 Goals"

Personal User Guide

Location:

Personal_Notes/Geoffrey/Kris-Hagel-User-Guide.md

Review triggers:

  • Annual review (Phase 6) - comprehensive review
  • Quarterly check-ins - light evidence-based updates

Update approach:

  • Evidence-based: Compare User Guide to review conversation
  • Specific proposals: Point out discrepancies with examples
  • User approval required before editing

Identity-Core Integration

Loads from:

  • ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/knowledge/identity-core.json

References:

  • TELOS mission per domain
  • Constitution values (equity, excellence, empathy, learning, innovation, integrity)
  • Strengths (Input, Significance, Analytical, Achiever, Learner)
  • Personality (Type 3w4, Green-Orange, 0% Blue relationship gap)
  • Decision framework, stress patterns, growth edges

Uses for:

  • Alignment checks in Part 3 (Strategic Direction)
  • Challenge questions in Part 5 (Cross-Domain Integration)
  • Framing success in terms of Mastery + Legacy + Freedom

Framework Integration

James Clear Systems Focus

Applied in:

  • Success Indicators: Include leading (process) + lagging (outcome) metrics
  • During goal-setting: Ask "What system/habit supports this goal?"
  • Reframe outcome goals → process goals where appropriate

Example:

  • Outcome: "Launch AI voice app"
  • System: "Ship feature every 2 weeks" + "User feedback session biweekly"

Personal Board of Directors

Included in: Part 5 (Cross-Domain Integration)

Tracks:

  • 4-7 advisors across domains
  • Roles: Connector, Accountability Partner, Futurist, Subject Matter Expert
  • Last consulted date (accountability)

Life Map (Alex Lieberman)

Maps to 5 domains:

  • Career → CIO Role + Consulting/Speaking
  • Finances → Real Estate + Financial Planning
  • Meaning → Product Development (AI products = legacy)
  • Relationships → Cross-domain question (0% Blue gap)
  • Health → Not covered (note for future expansion)
  • Fun → Not covered (note for future expansion)

Ideal Lifestyle Costing (Tim Ferriss)

Optional exercise in: Financial Planning domain

Question: "What does your ideal [year] look like? Cost it out." Use for: Retirement planning milestone


Error Handling

Common Scenarios

1. User can't answer "what you will NOT do" (Q5 in Strategic Direction):

  • Response: Use scaffolding questions (see Phase 3)
  • If still stuck: "Let's flag this and come back after Priority Goals are defined."
  • Note in output: "Strategic exclusions to be determined"

2. User has no baseline for Success Indicator:

  • Response: "Can you establish a baseline now? If not, we'll note this as a 'learning year' for baseline setting."
  • Record: Current = "Baseline TBD" → Target = [value]

3. User proposes >3 Priority Goals:

  • Response: "You've listed [N] priorities. Research shows more than 3 means none get focus. Which would you cut?"
  • Enforce: Hard cap at 3 per domain

4. User's goals don't align with strategic direction:

  • Response: "You said your strategic direction was [X], but this goal seems focused on [Y]. Help me see the connection."
  • If misalignment remains: Note in "Potential Misalignments" section for discussion

5. User wants to skip domains:

  • Response: Allow skipping for quarterly check-ins
  • For annual: Recommend covering all 5, but allow "maintenance mode" designation

6. User wants to adjust targets mid-year (quarterly check-in):

  • Response: "What changed? What's the rationale for adjusting?"
  • Record: Original target + Revised target with date/reason
  • Update: OmniFocus milestones if needed

Future Enhancements

  • Add Health and Fun domains to Life Map coverage
  • Integrate with calendar for automatic quarterly review reminders
  • Add mid-year strategic adjustment session (July)
  • Create visualization dashboard for progress tracking
  • Add retrospective analysis comparing year-over-year patterns
  • Integration with knowledge-manager for automatic preference updates based on goals
  • Add voice AI option for conducting interview (user speaks, Geoffrey transcribes and challenges)

Version History

v1.1.0 (2026-01-26)

  • Renamed from strategic-planning-manager to personal-strategic-planning
  • Updated triggers to avoid conflict with organizational planning skill
  • For organizational/K-12 strategic planning, use strategic-planning-manager

v1.0.0 (2026-01-02)

  • Initial release
  • Annual review interview (6 phases)
  • Quarterly check-in interview
  • Obsidian integration (Reviews folder)
  • OmniFocus integration (auto-create projects)
  • Identity-core alignment checks
  • Progressive challenge mechanisms
  • 5-domain structure

PPTX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Reading and analyzing content

Text extraction

If you just need to read the text contents of a presentation, you should convert the document to markdown:

# Convert document to markdown
python -m markitdown path-to-file.pptx

Raw XML access

You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.

Unpacking a file

skills/pptx/ooxml/scripts/unpack.py <office_file> <output_dir>

Note: The unpack.py script is located at skills/pptx/ooxml/scripts/unpack.py relative to the project root. If the script doesn't exist at this path, use find . -name "unpack.py" to locate it.

Key file structures
  • ppt/presentation.xml - Main presentation metadata and slide references
  • ppt/slides/slide{N}.xml - Individual slide contents (slide1.xml, slide2.xml, etc.)
  • ppt/notesSlides/notesSlide{N}.xml - Speaker notes for each slide
  • ppt/comments/modernComment_*.xml - Comments for specific slides
  • ppt/slideLayouts/ - Layout templates for slides
  • ppt/slideMasters/ - Master slide templates
  • ppt/theme/ - Theme and styling information
  • ppt/media/ - Images and other media files
Typography and color extraction

When given an example design to emulate: Always analyze the presentation's typography and colors first using the methods below:

  1. Read theme file: Check ppt/theme/theme1.xml for colors (<a:clrScheme>) and fonts (<a:fontScheme>)
  2. Sample slide content: Examine ppt/slides/slide1.xml for actual font usage (<a:rPr>) and colors
  3. Search for patterns: Use grep to find color (<a:solidFill>, <a:srgbClr>) and font references across all XML files

Creating a new PowerPoint presentation without a template

When creating a new PowerPoint presentation from scratch, use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.

Design Principles

CRITICAL: Before creating any presentation, analyze the content and choose appropriate design elements:

  1. Consider the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
  2. Check for branding: If the user mentions a company/organization, consider their brand colors and identity
  3. Match palette to content: Select colors that reflect the subject
  4. State your approach: Explain your design choices before writing code

Requirements:

  • ✅ State your content-informed design approach BEFORE writing code
  • ✅ Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
  • ✅ Create clear visual hierarchy through size, weight, and color
  • ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
  • ✅ Be consistent: repeat patterns, spacing, and visual language across slides
Color Palette Selection

Choosing colors creatively:

  • Think beyond defaults: What colors genuinely match this specific topic? Avoid autopilot choices.
  • Consider multiple angles: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)
  • Be adventurous: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy
  • Build your palette: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)
  • Ensure contrast: Text must be clearly readable on backgrounds

Example color palettes (use these to spark creativity - choose one, adapt it, or create your own):

  1. Classic Blue: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
  2. Teal & Coral: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
  3. Bold Red: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
  4. Warm Blush: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
  5. Burgundy Luxury: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
  6. Deep Purple & Emerald: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
  7. Cream & Forest Green: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
  8. Pink & Purple: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
  9. Lime & Plum: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
  10. Black & Gold: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
  11. Sage & Terracotta: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
  12. Charcoal & Red: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
  13. Vibrant Orange: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
  14. Forest Green: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
  15. Retro Rainbow: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
  16. Vintage Earthy: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
  17. Coastal Rose: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
  18. Orange & Turquoise: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)
Visual Details Options

Geometric Patterns:

  • Diagonal section dividers instead of horizontal
  • Asymmetric column widths (30/70, 40/60, 25/75)
  • Rotated text headers at 90° or 270°
  • Circular/hexagonal frames for images
  • Triangular accent shapes in corners
  • Overlapping shapes for depth

Border & Frame Treatments:

  • Thick single-color borders (10-20pt) on one side only
  • Double-line borders with contrasting colors
  • Corner brackets instead of full frames
  • L-shaped borders (top+left or bottom+right)
  • Underline accents beneath headers (3-5pt thick)

Typography Treatments:

  • Extreme size contrast (72pt headlines vs 11pt body)
  • All-caps headers with wide letter spacing
  • Numbered sections in oversized display type
  • Monospace (Courier New) for data/stats/technical content
  • Condensed fonts (Arial Narrow) for dense information
  • Outlined text for emphasis

Chart & Data Styling:

  • Monochrome charts with single accent color for key data
  • Horizontal bar charts instead of vertical
  • Dot plots instead of bar charts
  • Minimal gridlines or none at all
  • Data labels directly on elements (no legends)
  • Oversized numbers for key metrics

Layout Innovations:

  • Full-bleed images with text overlays
  • Sidebar column (20-30% width) for navigation/context
  • Modular grid systems (3×3, 4×4 blocks)
  • Z-pattern or F-pattern content flow
  • Floating text boxes over colored shapes
  • Magazine-style multi-column layouts

Background Treatments:

  • Solid color blocks occupying 40-60% of slide
  • Gradient fills (vertical or diagonal only)
  • Split backgrounds (two colors, diagonal or vertical)
  • Edge-to-edge color bands
  • Negative space as a design element

Layout Tips

When creating slides with charts or tables:

  • Two-column layout (PREFERRED): Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.
  • Full-slide layout: Let the featured content (chart/table) take up the entire slide for maximum impact and readability
  • NEVER vertically stack: Do not place charts/tables below text in a single column - this causes poor readability and layout issues

Workflow

  1. MANDATORY - READ ENTIRE FILE: Read html2pptx.md completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.
  2. Create an HTML file for each slide with proper dimensions (e.g., 720pt × 405pt for 16:9)
    • Use <p>, <h1>-<h6>, <ul>, <ol> for all text content
    • Use class="placeholder" for areas where charts/tables will be added (render with gray background for visibility)
    • CRITICAL: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML
    • LAYOUT: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability
  3. Create and run a JavaScript file using the html2pptx.js library to convert HTML slides to PowerPoint and save the presentation
    • Use the html2pptx() function to process each HTML file
    • Add charts and tables to placeholder areas using PptxGenJS API
    • Save the presentation using pptx.writeFile()
  4. Visual validation: Generate thumbnails and inspect for layout issues
    • Create thumbnail grid: python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
    • Read and carefully examine the thumbnail image for:
      • Text cutoff: Text being cut off by header bars, shapes, or slide edges
      • Text overlap: Text overlapping with other text or shapes
      • Positioning issues: Content too close to slide boundaries or other elements
      • Contrast issues: Insufficient contrast between text and backgrounds
    • If issues found, adjust HTML margins/spacing/colors and regenerate the presentation
    • Repeat until all slides are visually correct

Editing an existing PowerPoint presentation

When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.

Workflow

  1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.
  2. Unpack the presentation: skills/pptx/ooxml/scripts/unpack.py <office_file> <output_dir>
  3. Edit the XML files (primarily ppt/slides/slide{N}.xml and related files)
  4. CRITICAL: Validate immediately after each edit and fix any validation errors before proceeding: skills/pptx/ooxml/scripts/validate.py <dir> --original <file>
  5. Pack the final presentation: skills/pptx/ooxml/scripts/pack.py <input_directory> <office_file>

Creating a new PowerPoint presentation using a template

When you need to create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.

Workflow

  1. Extract template text AND create visual thumbnail grid:

    • Extract text: python -m markitdown template.pptx > template-content.md
    • Read template-content.md: Read the entire file to understand the contents of the template presentation. NEVER set any range limits when reading this file.
    • Create thumbnail grids: python scripts/thumbnail.py template.pptx
    • See Creating Thumbnail Grids section for more details
  2. Analyze template and save inventory to a file:

    • Visual Analysis: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure
    • Create and save a template inventory file at template-inventory.md containing:
      # Template Inventory Analysis
      **Total Slides: [count]**
      **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**
      
      ## [Category Name]
      - Slide 0: [Layout code if available] - Description/purpose
      - Slide 1: [Layout code] - Description/purpose
      - Slide 2: [Layout code] - Description/purpose
      [... EVERY slide must be listed individually with its index ...]
      
    • Using the thumbnail grid: Reference the visual thumbnails to identify:
      • Layout patterns (title slides, content layouts, section dividers)
      • Image placeholder locations and counts
      • Design consistency across slide groups
      • Visual hierarchy and structure
    • This inventory file is REQUIRED for selecting appropriate templates in the next step
  3. Create presentation outline based on template inventory:

    • Review available templates from step 2.
    • Choose an intro or title template for the first slide. This should be one of the first templates.
    • Choose safe, text-based layouts for the other slides.
    • CRITICAL: Match layout structure to actual content:
      • Single-column layouts: Use for unified narrative or single topic
      • Two-column layouts: Use ONLY when you have exactly 2 distinct items/concepts
      • Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts
      • Image + text layouts: Use ONLY when you have actual images to insert
      • Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis
      • Never use layouts with more placeholders than you have content
      • If you have 2 items, don't force them into a 3-column layout
      • If you have 4+ items, consider breaking into multiple slides or using a list format
    • Count your actual content pieces BEFORE selecting the layout
    • Verify each placeholder in the chosen layout will be filled with meaningful content
    • Select one option representing the best layout for each content section.
    • Save outline.md with content AND template mapping that leverages available designs
    • Example template mapping:
      # Template slides to use (0-based indexing)
      # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
      # Mapping: slide numbers from outline -> template slide indices
      template_mapping = [
          0,   # Use slide 0 (Title/Cover)
          34,  # Use slide 34 (B1: Title and body)
          34,  # Use slide 34 again (duplicate for second B1)
          50,  # Use slide 50 (E1: Quote)
          54,  # Use slide 54 (F2: Closing + Text)
      ]
      
  4. Duplicate, reorder, and delete slides using rearrange.py:

    • Use the scripts/rearrange.py script to create a new presentation with slides in the desired order:
      python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
      
    • The script handles duplicating repeated slides, deleting unused slides, and reordering automatically
    • Slide indices are 0-based (first slide is 0, second is 1, etc.)
    • The same slide index can appear multiple times to duplicate that slide
  5. Extract ALL text using the inventory.py script:

    • Run inventory extraction:

      python scripts/inventory.py working.pptx text-inventory.json
      
    • Read text-inventory.json: Read the entire text-inventory.json file to understand all shapes and their properties. NEVER set any range limits when reading this file.

    • The inventory JSON structure:

        {
          "slide-0": {
            "shape-0": {
              "placeholder_type": "TITLE",  // or null for non-placeholders
              "left": 1.5,                  // position in inches
              "top": 2.0,
              "width": 7.5,
              "height": 1.2,
              "paragraphs": [
                {
                  "text": "Paragraph text",
                  // Optional properties (only included when non-default):
                  "bullet": true,           // explicit bullet detected
                  "level": 0,               // only included when bullet is true
                  "alignment": "CENTER",    // CENTER, RIGHT (not LEFT)
                  "space_before": 10.0,     // space before paragraph in points
                  "space_after": 6.0,       // space after paragraph in points
                  "line_spacing": 22.4,     // line spacing in points
                  "font_name": "Arial",     // from first run
                  "font_size": 14.0,        // in points
                  "bold": true,
                  "italic": false,
                  "underline": false,
                  "color": "FF0000"         // RGB color
                }
              ]
            }
          }
        }
      
    • Key features:

      • Slides: Named as "slide-0", "slide-1", etc.
      • Shapes: Ordered by visual position (top-to-bottom, left-to-right) as "shape-0", "shape-1", etc.
      • Placeholder types: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
      • Default font size: default_font_size in points extracted from layout placeholders (when available)
      • Slide numbers are filtered: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory
      • Bullets: When bullet: true, level is always included (even if 0)
      • Spacing: space_before, space_after, and line_spacing in points (only included when set)
      • Colors: color for RGB (e.g., "FF0000"), theme_color for theme colors (e.g., "DARK_1")
      • Properties: Only non-default values are included in the output
  6. Generate replacement text and save the data to a JSON file Based on the text inventory from the previous step:

    • CRITICAL: First verify which shapes exist in the inventory - only reference shapes that are actually present
    • VALIDATION: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory
      • If you reference a non-existent shape, you'll get an error showing available shapes
      • If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist
      • All validation errors are shown at once before the script exits
    • IMPORTANT: The replace.py script uses inventory.py internally to identify ALL text shapes
    • AUTOMATIC CLEARING: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them
    • Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")
    • Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically
    • Paragraphs with bullets will be automatically left aligned. Don't set the alignment property on when "bullet": true
    • Generate appropriate replacement content for placeholder text
    • Use shape size to determine appropriate content length
    • CRITICAL: Include paragraph properties from the original inventory - don't just provide text
    • IMPORTANT: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically
    • ESSENTIAL FORMATTING RULES:
      • Headers/titles should typically have "bold": true
      • List items should have "bullet": true, "level": 0 (level is required when bullet is true)
      • Preserve any alignment properties (e.g., "alignment": "CENTER" for centered text)
      • Include font properties when different from default (e.g., "font_size": 14.0, "font_name": "Lora")
      • Colors: Use "color": "FF0000" for RGB or "theme_color": "DARK_1" for theme colors
      • The replacement script expects properly formatted paragraphs, not just text strings
      • Overlapping shapes: Prefer shapes with larger default_font_size or more appropriate placeholder_type
    • Save the updated inventory with replacements to replacement-text.json
    • WARNING: Different template layouts have different shape counts - always check the actual inventory before creating replacements

    Example paragraphs field showing proper formatting:

    "paragraphs": [
      {
        "text": "New presentation title text",
        "alignment": "CENTER",
        "bold": true
      },
      {
        "text": "Section Header",
        "bold": true
      },
      {
        "text": "First bullet point without bullet symbol",
        "bullet": true,
        "level": 0
      },
      {
        "text": "Red colored text",
        "color": "FF0000"
      },
      {
        "text": "Theme colored text",
        "theme_color": "DARK_1"
      },
      {
        "text": "Regular paragraph text without special formatting"
      }
    ]
    

    Shapes not listed in the replacement JSON are automatically cleared:

    {
      "slide-0": {
        "shape-0": {
          "paragraphs": [...] // This shape gets new text
        }
        // shape-1 and shape-2 from inventory will be cleared automatically
      }
    }
    

    Common formatting patterns for presentations:

    • Title slides: Bold text, sometimes centered
    • Section headers within slides: Bold text
    • Bullet lists: Each item needs "bullet": true, "level": 0
    • Body text: Usually no special properties needed
    • Quotes: May have special alignment or font properties
  7. Apply replacements using the replace.py script

    python scripts/replace.py working.pptx replacement-text.json output.pptx
    

    The script will:

    • First extract the inventory of ALL text shapes using functions from inventory.py
    • Validate that all shapes in the replacement JSON exist in the inventory
    • Clear text from ALL shapes identified in the inventory
    • Apply new text only to shapes with "paragraphs" defined in the replacement JSON
    • Preserve formatting by applying paragraph properties from the JSON
    • Handle bullets, alignment, font properties, and colors automatically
    • Save the updated presentation

    Example validation errors:

    ERROR: Invalid shapes in replacement JSON:
      - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
      - Slide 'slide-999' not found in inventory
    
    ERROR: Replacement text made overflow worse in these shapes:
      - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
    

Creating Thumbnail Grids

To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:

python scripts/thumbnail.py template.pptx [output_prefix]

Features:

  • Creates: thumbnails.jpg (or thumbnails-1.jpg, thumbnails-2.jpg, etc. for large decks)
  • Default: 5 columns, max 30 slides per grid (5×6)
  • Custom prefix: python scripts/thumbnail.py template.pptx my-grid
    • Note: The output prefix should include the path if you want output in a specific directory (e.g., workspace/my-grid)
  • Adjust columns: --cols 4 (range: 3-6, affects slides per grid)
  • Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
  • Slides are zero-indexed (Slide 0, Slide 1, etc.)

Use cases:

  • Template analysis: Quickly understand slide layouts and design patterns
  • Content review: Visual overview of entire presentation
  • Navigation reference: Find specific slides by their visual appearance
  • Quality check: Verify all slides are properly formatted

Examples:

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combine options: custom name, columns
python scripts/thumbnail.py template.pptx analysis --cols 4

Converting Slides to Images

To visually analyze PowerPoint slides, convert them to images using a two-step process:

  1. Convert PPTX to PDF:

    soffice --headless --convert-to pdf template.pptx
    
  2. Convert PDF pages to JPEG images:

    pdftoppm -jpeg -r 150 template.pdf slide
    

    This creates files like slide-1.jpg, slide-2.jpg, etc.

Options:

  • -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
  • -jpeg: Output JPEG format (use -png for PNG if preferred)
  • -f N: First page to convert (e.g., -f 2 starts from page 2)
  • -l N: Last page to convert (e.g., -l 5 stops at page 5)
  • slide: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for PPTX operations:

  • Write concise code
  • Avoid verbose variable names and redundant operations
  • Avoid unnecessary print statements

Dependencies

Required dependencies (should already be installed):

  • markitdown: pip install "markitdown[pptx]" (for text extraction from presentations)
  • pptxgenjs: npm install -g pptxgenjs (for creating presentations via html2pptx)
  • playwright: npm install -g playwright (for HTML rendering in html2pptx)
  • react-icons: npm install -g react-icons react react-dom (for icons)
  • sharp: npm install -g sharp (for SVG rasterization and image processing)
  • LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
  • Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
  • defusedxml: pip install defusedxml (for secure XML parsing)

Presentation Master

World-class presentation creation skill that embodies best practices from presentation masters and adapts to your needs.

Philosophy

Key Innovation: This isn't just a presentation generator—it's a presentation coach that teaches world-class design while creating slides.

Principles from:

  • Garr Reynolds (Presentation Zen) - Simplicity and visual storytelling
  • Nancy Duarte (Resonate) - Story structure and audience as hero
  • Guy Kawasaki - 10/20/30 rule (10 slides, 20 minutes, 30pt fonts)
  • Seth Godin - 6 words maximum per slide
  • TED - Visual-first, minimal text, high impact
  • Edward Tufte - Data integrity and information design
  • Steve Jobs - Rule of Three and surprise moments

Workflow: Guided Creation with Checkpoints

Phase 1: Discovery & Context Analysis

User provides: Topic + Audience + Duration

Skill analyzes:

  • Presentation type (board update, keynote, training, TED-style)
  • Audience level (technical, executive, general public)
  • Key message and desired transformation
  • Story framework recommendation

Checkpoint 1: Present 3 structure options with rationale → user approves

Phase 2: Content Development

Skill develops:

  • Research topic if needed (web search, Obsidian knowledge)
  • Extract maximum 10 core concepts (Kawasaki rule)
  • Apply "what is / what could be" alternation (Duarte)
  • Draft slide outline with one concept per slide
  • Identify slides needing visuals

Checkpoint 2: Present outline + visual plan → user approves

Phase 3: Visual Strategy

Skill proposes for each visual slide:

  • Image type (infographic, photo, diagram, data visualization)
  • Visual concept/metaphor
  • Aesthetic direction (colors from brand, style, mood)
  • Estimated generation cost ($0.13-$0.24 per image)

Checkpoint 3: Present visual strategy → user approves images to generate

Phase 4: Generation & Validation

Skill executes:

  1. Generate approved images in parallel using image-gen skill
  2. Build slides using selected adapter (PPTX/Google Slides/Canva)
  3. Apply design rules automatically:
    • 30pt+ fonts minimum
    • <6 words per slide (Godin standard)
    • High contrast (4.5:1 minimum)
    • No bullet points
    • No paragraphs
  4. Run validation scoring (0-100 scale)
  5. Generate quality report

Checkpoint 4: Present presentation + quality report → user reviews

Phase 5: Iteration & Refinement (if needed)

Skill refines:

  • Apply requested changes
  • Re-validate quality score
  • Save final presentation to Obsidian Research folder
  • Document learnings and metadata

Validation Scoring (0-100)

CRITICAL Violations (Auto-fail)

  • Font size < 30pt
  • 10 core concepts

  • Bullet points detected
  • Paragraphs (>2 consecutive sentences)
  • Poor contrast ratio (<4.5:1)
  • Default template usage

WARNING Flags

  • 6 words per slide

  • 15 slides for 20-min presentation

  • No images in presentation
  • Text-heavy slides (>3 lines)
  • Inconsistent fonts (>2 families)
  • Low-resolution images

Quality Score Breakdown

  • Simplicity (10pts): Word count, visual clutter
  • Visual Dominance (10pts): Image quality, text-to-visual ratio
  • Story Structure (10pts): Narrative arc, emotional beats
  • One Idea/Slide (10pts): Concept clarity
  • Typography (8pts): Size, consistency
  • Layout (7pts): Hierarchy, whitespace, alignment
  • Color/Contrast (7pts): Readability, brand consistency
  • Media Quality (8pts): Image resolution, relevance
  • Cognitive Load (20pts): Mayer's 12 multimedia principles
  • Data Integrity (10pts): Tufte principles (if data present)

Target Score: 85+ for high-quality presentations

Slide Pattern Library

Six Core Patterns

  1. Title Slide - Minimal text, strong visual, sets tone
  2. One Big Idea - Single word/number/image, max 6 words
  3. Visual + Caption - Large high-quality image, short caption
  4. Data Visualization - Charts following Tufte principles (maximize data-ink ratio)
  5. Timeline/Process - Linear flow, minimal text per step
  6. Transition/Section Break - Single word or phrase, signals shift

Adaptive Pattern Selection

Board/Executive Update: Patterns 3, 4, 6 (data-focused, professional) Keynote/TED-style: Patterns 1, 2, 3 (story-focused, visual-first) Training/Education: Patterns 4, 5 (process-focused, clarity) Pitch/Demo: Patterns 2, 3, 4 (impact-focused, evidence-based)

Story Frameworks

Nancy Duarte's Sparkline

  • Alternate "what is" (current reality) with "what could be" (aspiration)
  • Build tension through contrast between present and future
  • End with transformation and new reality

The Rule of Three (Steve Jobs)

  • Break presentation into 3 main sections
  • 3 key features/points per section
  • Memorable and dramatic

TED Structure

  • Hook (first 30 seconds) - Grab attention
  • Personal connection - Why this matters to you
  • Core idea with evidence - The meat
  • Call to action - What next
  • Strong close - Never end with Q&A

Output Format Support

Current: PPTX (Phase 1)

  • Uses existing pptx skill
  • Direct PptxGenJS API for simple slides
  • html2pptx.js for complex layouts
  • Saves to Obsidian Research folder
  • Generates quality validation report

Coming: Google Slides (Phase 2)

  • Google Slides API v1
  • Integrates with google-workspace skill
  • Supports all 3 accounts (psd, kh, hrg)
  • Returns shareable link

Future: Canva (Phase 3)

  • Canva REST API
  • Auto-apply brand kits
  • Returns shareable link

Image Generation Integration

Intelligent Visual Recommendations

For each slide, analyzes:

  • Numeric data → Infographic recommendation
  • Abstract concepts → Conceptual image/metaphor (especially for keynotes)
  • Concrete examples → Photo/realistic imagery
  • Processes/flows → Diagram recommendation
  • Trends/comparisons → Chart/data visualization

Prompt Generation (6-Step Process)

From image-gen skill:

  1. Extract narrative from slide content
  2. Choose visual concept/metaphor
  3. Apply aesthetic (brand colors, presentation style)
  4. Construct detailed prompt
  5. Execute generation
  6. Validate output

Cost Management

  • Show total estimated cost before generating
  • Allow opt-out of specific images
  • Cache generated images for reuse
  • Track spending in presentation metadata

Naming Convention

{presentation-id}-slide-{number}-{type}.png

Examples:
cybersecurity-2025-slide-02-threat-timeline.png
port-ai-2025-slide-04-breakthroughs.png

Brand Integration

Automatically detects and applies branding:

  • PSD presentations: Use psd-brand-guidelines skill (Sea Glass, Pacific, etc.)
  • Personal presentations: Use personal brand (if defined)
  • Client presentations: Custom brand kit (future)

Applies to:

  • Color palettes
  • Typography choices
  • Logo placement
  • Overall aesthetic

Learning & Metadata Tracking

After each presentation, save metadata to Obsidian:

{
  "presentation_id": "cybersecurity-2025-board",
  "type": "board-update",
  "audience": "school-board",
  "duration": "15min",
  "slides": 10,
  "quality_score": 91,
  "images_generated": 7,
  "generation_cost": 0.94,
  "validation_warnings": 1,
  "user_edits": ["slide-8-wording"],
  "effectiveness": "approved-minor-changes",
  "created": "2025-11-24",
  "tools_used": ["research", "image-gen", "pptx"],
  "learnings": "Board prefers data charts over concept graphics"
}

Integration with Existing Skills

Dependencies:

  • image-gen - Visual content generation
  • pptx - PowerPoint creation (Phase 1)
  • google-workspace - Google Slides (Phase 2)
  • psd-brand-guidelines - Brand colors/logos
  • research - Content development
  • obsidian-manager - Knowledge storage

Coordination Pattern:

presentation-master (orchestrator)
├── calls research for content depth
├── calls image-gen for visuals
├── calls pptx/slides/canva adapter for output
├── calls psd-brand-guidelines for colors/logos
└── calls obsidian-manager to save final + metadata

Usage Examples

Example 1: Board Update

User: "Create presentation on cybersecurity trends for school board, 15 minutes"

Geoffrey: I'll create a board update presentation on cybersecurity trends.

**Context Analysis**
- Type: Board/Executive Update
- Audience: School board (non-technical)
- Duration: 15 minutes
- Purpose: Inform + Recommend action

**Recommended Structures**
1. Problem → Solution → Action (8 slides)
2. Current State → Trends → Implications → Recommendations (10 slides) ⭐
3. Story: Recent incident → Broader context → Our response (7 slides)

Which structure resonates?

[User selects #2]

**Draft Outline** (10 slides, one concept each)
1. Title: Cybersecurity Trends 2025
2. Current Threat Landscape [visual: threat timeline]
3. Trend 1: AI-Powered Attacks [visual: concept illustration]
4. Trend 2: Ransomware Evolution [visual: data chart]
5. Trend 3: Supply Chain Risks [visual: network diagram]
6. Impact on Education Sector [visual: stat infographic]
7. Our Current Posture [visual: assessment chart]
8. Gaps & Vulnerabilities [text-focused, high contrast]
9. Recommended Actions [visual: roadmap]
10. Investment & Timeline [visual: budget chart]

**Visual Strategy**
- 7 images recommended
- Estimated cost: $0.94 (2K resolution)
- Mix: 3 infographics, 2 charts, 1 diagram, 1 illustration

Approve and proceed?

[User approves]

Generating 7 visuals in parallel...
✓ All generated (0.94 total)

Building presentation with PSD brand colors...
Validating against best practices...

**Quality Score: 91/100**
✓ All fonts 36pt+
✓ Avg 4.2 words/slide
✓ High contrast (8.5:1)
✓ Story arc present
✓ Cognitive load optimized
⚠ Slide 8 has 7 words (rec: 6 max)

Created: /Obsidian/Research/cybersecurity-trends-2025-board.pptx

Example 2: Keynote

User: "Create keynote on future of education for conference, 30 minutes"

Geoffrey: I'll create a TED-style keynote on the future of education.

**Context Analysis**
- Type: Keynote/TED-style
- Audience: Education professionals + parents
- Duration: 30 minutes
- Purpose: Inspire + Shift perspective

**Recommended Structures** (Nancy Duarte's Sparkline)
1. What education is today → What it could be → Transformation (12 slides) ⭐
2. Steve Jobs Rule of Three: Past → Present → Future (9 slides)
3. Hero's Journey: Problem → Trials → New reality (10 slides)

Which framework?

[Continues with guided creation...]

Quality Checklist

Before presenting to user, verify:

Content

  • One main idea per slide
  • Clear story arc (beginning/middle/end)
  • Audience positioned as hero
  • Emotional connection established
  • Maximum 10 core concepts

Design

  • All fonts 30pt+ minimum
  • High contrast (4.5:1+)
  • No bullet points
  • No paragraphs
  • Maximum 6 words per slide (or justified exception)
  • All images high-resolution
  • Consistent fonts/colors/alignment
  • No transitions or animations

Data Visualization (if applicable)

  • Lie factor 0.95-1.05
  • Maximum data-ink ratio
  • Clear, detailed labeling
  • No chart junk (3D effects, unnecessary borders)

Structure

  • Follows chosen framework (Duarte/Jobs/TED)
  • Creates tension and resolution
  • Includes surprise/memorable moments
  • Ends strong (not with Q&A)
  • Appropriate length for time

Advanced Features

Context Detection

Automatically infers presentation type from cues:

  • "board meeting" → Board update (data-focused)
  • "keynote" or "conference" → Keynote (story-focused)
  • "training" or "workshop" → Educational (process-focused)
  • "pitch" or "investor" → Pitch (evidence-focused)

Smart Defaults

Based on detected type:

  • Board update: 10 slides, 8 with visuals, professional tone
  • Keynote: 12-15 slides, minimal text, emotional arc
  • Training: 15-20 slides, process diagrams, step-by-step
  • Pitch: 10 slides (Kawasaki rule), data-driven, ROI focus

Accessibility

Ensures presentations are accessible:

  • High contrast text (4.5:1 minimum, aim for 7:1)
  • Large fonts (30pt minimum, 36pt+ preferred)
  • Clear hierarchy and flow
  • Alt text for images (future enhancement)

Limitations & Future Enhancements

Current Limitations:

  • No animation support (by design - Godin principle)
  • No video embedding yet (future enhancement)
  • No speaker notes generation (Phase 2)
  • No slide master editing (uses templates)

Future Enhancements:

  • Auto-generate speaker notes from slide content
  • Suggest rehearsal timing
  • A/B test different structures
  • Track presentation effectiveness scores
  • Build personal pattern library from successful presentations

References

Full principles documentation in:

  • principles/masters.md - Expert best practices
  • principles/validation-rules.md - Quality scoring system
  • principles/slide-patterns.md - Template library
  • principles/story-frameworks.md - Narrative structures

Scripts and adapters:

  • scripts/analyze-context.js - Type detection
  • adapters/pptx-adapter.js - PowerPoint output
  • adapters/slides-adapter.js - Google Slides (Phase 2)
  • adapters/canva-adapter.js - Canva (Phase 3)

Remember: The best presentations are simple, visual, story-driven, and focused on the audience's transformation—not the speaker's information.

PSD Athletics Schedule

Retrieve and present athletics schedules for Peninsula School District's two high schools.

SchoolMascotAbbreviationOfficial Site
Gig Harbor High SchoolTidesGHHStidesathletics.com
Peninsula High SchoolSeahawksPHSpeninsulaathletics.com

Data Source

Official sites (PlayOn/Next.js) are JavaScript-rendered and unreadable via web search. Use MaxPreps schedule pages instead — they embed JSON-LD structured data in server-rendered HTML.

Data pipeline: ArbiterSports (scheduling) → PlayOn Sites → MaxPreps

Base URLs:

  • GHHS: https://www.maxpreps.com/wa/gig-harbor/gig-harbor-tides/
  • PHS: https://www.maxpreps.com/wa/gig-harbor/peninsula-seahawks/

Sport-specific schedule URLs are in references/sport-urls.md.

Workflow

1. Parse the Request

Determine from the user's request:

ParameterDefaultExamples
Date rangeNext 7 days"today", "this week", "next two weeks", "March schedule"
School filterBoth"GHHS only", "Peninsula games", "Tides baseball"
Sport filterAll in-season"baseball", "soccer", "track"

2. Determine Active Season

Only fetch sports currently in season. Overlap periods check both seasons.

SeasonMonthsSports
FallSep–NovFootball, Volleyball, Cross Country, Girls Swimming, Water Polo, Girls Soccer (Fall)
WinterDec–FebBasketball, Boys Swimming, Wrestling, Bowling, Flag Football
SpringMar–JunBaseball, Softball, Soccer, Tennis, Golf, Track & Field, Lacrosse, Water Polo (Girls), Dance

If the user asks for a specific sport that's out of season, check it anyway — schedules may be posted early.

3. Fetch Schedule Data

Read references/sport-urls.md to get the MaxPreps schedule URLs for the active season.

For each relevant sport URL:

  1. Use web search to visit the MaxPreps schedule page
  2. Extract events within the requested date range
  3. For each event, capture: date, time, sport/level, opponent, home/away, link
  4. Skip pages that 404 or have no data — move on

Parsing rules:

  • "vs" prefix = Home game
  • "@" prefix = Away game
  • Times are Pacific Time
  • If cancelled/postponed, note in output

4. Present Results

Combine all events into a single markdown table sorted by date/time:

| Date | Time | School | Sport | Opponent | Home/Away | Details |

Formatting rules:

  • Group by date with bold date headers
  • School column: "GHHS" or "PHS"
  • Details column: [View](maxpreps-url) link
  • Footer: event counts per school + total
  • Footer: "Schedule data sourced from MaxPreps. For official schedules: tidesathletics.com | peninsulaathletics.com"

If no events found for the date range, state that clearly and link to official sites.

PSD Brand Guidelines Skill

This skill applies Peninsula School District's official brand identity to artifacts including presentations, documents, graphics, and other materials.

CRITICAL: Enforcement Rules

NEVER Generate

NEVER use image-gen or any AI tool to generate:

  • District logos or emblems
  • "Peninsula School District" in stylized/logo text
  • Bridge/landscape imagery meant to represent the district logo
  • Any official-looking district branding elements
  • District seals or official marks

Why? AI-generated logos are inconsistent and may hallucinate incorrect details (wrong colors, wrong name, made-up imagery). Always use actual logo files.

ALWAYS Use Actual Files

For any branded materials:

  1. Use logo files from assets/ directory
  2. Use colors from brand-config.json
  3. Use brand.py utilities to select the right assets

Programmatic Access

Machine-readable brand data: brand-config.json Python utilities: brand.py

# Get colors
uv run brand.py colors

# Get appropriate logo path
uv run brand.py logo light wide
uv run brand.py logo dark small

# Validate prompt before image generation
uv run brand.py validate "create an infographic about enrollment"

Image Generation with Brand

When generating images for PSD materials, always use the --brand flag:

# This validates the prompt and blocks logo generation attempts
uv run generate.py "school campus scene" campus.png --brand psd

Purpose

Ensure professional and consistent use of the Peninsula School District brand across all communications. The brand reflects the stunning beauty of the Pacific Northwest and the Puget Sound region.

Typography

Headings & Logo Text: Josefin Sans

Modern geometric, elegant font with a vintage 1920s feel. Use Bold weight for district name and all headings.

Body Text: Josefin Slab

Perfect pairing to Josefin Sans, highly legible at smaller sizes due to slab serif and typewriter-style attributes.

Color Palette

Logo Colors (Primary)

NameHexRGBUsage
Sea Glass#6CA18Argb(108, 161, 138)Primary green, landscape elements
Pacific#25424Crgb(37, 66, 76)Primary dark blue, text, headers
Driftwood#D7CDBErgb(215, 205, 190)Neutral tan, backgrounds

Supporting Brand Colors

NameHexRGBUsage
Cedar#466857rgb(70, 104, 87)Dark green accent
Whulge#346780rgb(52, 103, 128)Medium blue (Coast Salish word for sound of waves)
Sea Foam#EEEBE4rgb(238, 235, 228)Light background
Meadow#5D9068rgb(93, 144, 104)Green accent
Ocean#7396A9rgb(115, 150, 169)Light blue accent
Skylight#FFFAECrgb(255, 250, 236)Off-white/cream background

Color Selection Guidelines

  • Light backgrounds: Use Pacific (#25424C) or 2-color logo
  • Dark backgrounds: Use Sea Glass (#6CA18A) or white logo
  • Neutral backgrounds: Choose based on contrast needs
  • When adding colors, choose natural, complementary colors that reflect Pacific Northwest landscape tones

Logo Options

Available Formats

  1. Full Landscape - Bridge connecting peninsula landscape, district name contained within
  2. Horizontal - For when name/tagline would be too small
  3. Emblem - Round versions, perfect for square spaces or tight fits
  4. Stacked - Vertical layout with name separated from brandmark

Color Variants

  • 2-color - Sea Glass + Pacific (primary use)
  • 1-color Pacific Blue - For light backgrounds
  • 1-color Sea Glass - For medium backgrounds
  • White - For dark backgrounds

File Types

FormatUse Cases
EPS (Vector)Professional printing, large scaling, Adobe programs
PNG (Raster)Microsoft Office, websites, social media, email signatures

Logo Location

Local assets folder: skills/psd-brand-guidelines/assets/

PNG files (19) - for web, Office, email:

  • psd_logo-2color-{emblem,fulllandscape,stacked,horizontal,square}.png
  • psd_logo-1color-blue-{emblem,fulllandscape,stacked,horizontal,square}.png
  • psd_logo-1color-green-{emblem,fulllandscape,stacked,horizontal,square}.png
  • psd_logo-white-{emblem,stacked,horizontal,square}.png

EPS files (19) - for professional printing, Adobe programs:

  • Same variants as PNG, with .eps extension

Reference:

  • PSD_Branding_Guide.pdf - full brand guide document

Google Drive source:

  • Logos Folder ID: 1YhjxX_pOwZJppZebIIC7QW_UHF4bvo79
  • Brand Guide Folder: 1ufOB6rrKDbAaH7HapdLadJzWy8ho5hTb

Logo Usage Rules

Do's

  • Maintain original proportions
  • Ensure sufficient contrast with background
  • Use appropriate color variant for background
  • Use emblem/stacked logo for small sizes

Don'ts

  • Don't shrink full landscape logo below 1.5" wide (print) or 300px (web)
  • Don't rotate the logo
  • Don't apply effects (drop shadows, mirroring, etc.)
  • Don't stretch or squish
  • Don't use non-brand fonts with logo
  • Don't place on backgrounds with insufficient contrast

Applying Brand to Artifacts

Presentations

/* Title slides */
background-color: #25424C;  /* Pacific */
color: #FFFAEC;             /* Skylight */
font-family: 'Josefin Sans', Arial, sans-serif;

/* Content slides */
background-color: #EEEBE4;  /* Sea Foam */
color: #25424C;             /* Pacific */
font-family: 'Josefin Slab', Georgia, serif;

/* Accent elements */
border-color: #6CA18A;      /* Sea Glass */

Documents

  • Headings: Josefin Sans Bold, Pacific (#25424C)
  • Body: Josefin Slab, Pacific (#25424C)
  • Links/Highlights: Whulge (#346780)
  • Backgrounds: Sea Foam (#EEEBE4) or Skylight (#FFFAEC)

Digital/Web

  • Primary buttons: Sea Glass (#6CA18A)
  • Secondary buttons: Whulge (#346780)
  • Text on light: Pacific (#25424C)
  • Text on dark: Skylight (#FFFAEC)

Brand Contact

For questions or special needs:

Quick Reference

Programmatic API (Python)

from brand import get_logo_path, get_colors, validate_prompt, get_color

# Get all colors as hex dict
colors = get_colors()  # {'seaGlass': '#6CA18A', 'pacific': '#25424C', ...}

# Get single color with metadata
color = get_color('pacific')  # {'hex': '#25424C', 'rgb': [37, 66, 76], 'usage': '...'}

# Get logo path based on context
logo = get_logo_path(background='dark', space='wide')   # Returns white-horizontal path
logo = get_logo_path(background='light', space='small')  # Returns 2color-emblem path

# Validate prompt before image generation
valid, errors = validate_prompt("create a school event banner")
if not valid:
    print(errors)  # Lists violations and suggestions

Machine-Readable Config

All brand data is available in brand-config.json:

  • Colors with hex, RGB, and usage notes
  • Typography specifications
  • Logo paths with selection rules
  • Forbidden generation patterns
  • Application guidelines per context

Legacy Quick Reference

const PSD_BRAND = {
  colors: {
    // Logo colors
    seaGlass: '#6CA18A',
    pacific: '#25424C',
    driftwood: '#D7CDBE',
    // Supporting colors
    cedar: '#466857',
    whulge: '#346780',
    seaFoam: '#EEEBE4',
    meadow: '#5D9068',
    ocean: '#7396A9',
    skylight: '#FFFAEC'
  },
  fonts: {
    heading: "'Josefin Sans', Arial, sans-serif",
    body: "'Josefin Slab', Georgia, serif"
  },
  logos: {
    localPath: 'skills/psd-brand-guidelines/assets/',
    driveFolder: '1YhjxX_pOwZJppZebIIC7QW_UHF4bvo79'
  }
};

Last updated: January 14, 2025 Source: PSD Branding Guide 06.14.2024.pdf, brand-config.json

PSD Instructional Vision

Peninsula School District's framework for rigorous, inclusive, and future-focused learning.

Full Reference: See references/playbook.md for complete details, classroom examples, and role-based responsibilities.


Vision Statement

We are dedicated to providing rigorous, standards-based instruction that ensures every student achieves grade-level proficiency and is prepared for future success.


The Four Instructional Essentials

EssentialCore Belief
Rigor & InclusionAll students access grade-level content through responsive, high-expectation instruction
Data-Driven DecisionsMultiple sources of evidence inform real-time instructional adjustments
Continuous GrowthOngoing reflection, collaboration, and professional learning deepen outcomes
InnovationForward-thinking instruction integrates real-world connections and student voice

The 8 Tier 1 Practices

Rigor & Inclusion

1. Building Academic Background

  • Connect new learning to prior knowledge, culture, and identity
  • Use shared experiences, culturally relevant hooks, multimodal vocabulary

2. Scaffolding & Differentiation

  • Flexible grouping based on data
  • Temporary supports that maintain rigor
  • Multiple paths to same high expectations

Data-Driven Decisions

3. Formative Assessment & Feedback

  • Frequent checks for understanding
  • Specific, actionable feedback aligned to success criteria
  • Instruction adjusts based on data patterns

4. Student Self-Assessment

  • Clear learning targets in student-friendly language
  • Regular reflection routines
  • Students set goals and track progress

Continuous Growth

5. Collaborative Professional Learning

  • Student work anchors PLC discussions
  • Reflective practice individually and collectively
  • New learning applied and reported back

6. Actionable Observation & Feedback Cycles

  • Evidence-based, non-evaluative feedback
  • Short-cycle model with timely response
  • Two-way dialogue and goal setting

Innovation

7. Real-World Connections

  • Authentic problems and contexts
  • Student voice and choice
  • Community, career, and cultural connections

8. Intentional Use of Technology

  • Tech personalizes learning paths
  • Tools enable collaboration and creation
  • Accessibility features ensure universal access

Quick Reference for Graphics & Communications

When creating visuals about PSD instruction, include:

Key Terms:

  • Instructional Essentials (the framework)
  • Tier 1 Practices (the 8 strategies)
  • Grade-level rigor with appropriate scaffolds
  • Evidence-informed instruction
  • Student agency and voice

Core Messages:

  • Every student deserves engaging, rigorous, inclusive learning every day
  • High expectations WITH high support
  • Data informs—not just documents—instruction
  • Innovation serves learning, not the other way around

Visual Framework: The four essentials form a cycle around the PSD logo:

  • Rigor & Inclusion (top-left, green)
  • Data-Driven Decisions (top-right, blue-gray)
  • Continuous Growth (bottom-right, light blue)
  • Innovation (bottom-left, dark green)

For AI Assistants & External Systems

When building an AI assistant that should embody PSD's instructional philosophy, inject these beliefs:

System Prompt Injection

You are aligned with Peninsula School District's Instructional Essentials:

CORE BELIEF: Every student deserves engaging, rigorous, and inclusive learning every day.

INSTRUCTIONAL PRINCIPLES:
1. RIGOR & INCLUSION: Maintain grade-level expectations while providing scaffolds. Never lower the bar—build the ladder.
2. DATA-DRIVEN: Recommendations should be based on evidence. Suggest formative checks and adjustment strategies.
3. CONTINUOUS GROWTH: Model reflection. Ask "What worked? What could improve?" Frame feedback constructively.
4. INNOVATION: Connect to real-world contexts. Encourage student voice and choice. Technology serves learning.

PEDAGOGICAL STANCE:
- Scaffolds are temporary supports, not permanent crutches
- Differentiation means different paths to the SAME high standard
- Feedback should be specific, actionable, and tied to success criteria
- Student self-assessment builds agency and metacognition
- Collaboration among educators improves outcomes for ALL students

Key Practices to Reference

If the assistant is about...Emphasize these practices
Lesson planningBuilding academic background, scaffolding, formative assessment
AssessmentFormative feedback, student self-assessment, data patterns
Coaching/PDCollaborative learning, observation cycles, reflective practice
Student engagementReal-world connections, technology, student voice
DifferentiationFlexible grouping, scaffolding, multiple paths to standards

When to Load Full Playbook

Read references/playbook.md when you need:

  • Specific classroom examples for a practice
  • Role-based responsibilities (teachers, principals, central office)
  • Indicators of success for a practice
  • Educator reflection questions
  • Implementation guidance

Red Rover Manager Skill

Overview

Red Rover is an absence management system used by PSD to track staff absences and substitute coverage. This skill provides access to absence data for reporting and analysis.

Configuration

  • Base URL: https://connect.redroverk12.com/
  • Org ID: 1305 (Peninsula School District)
  • Authentication: HTTP Basic Auth + API Key header
  • Credentials: Stored in 1Password as "RedRover"
  • Rate Limit: 100 requests/minute

Authentication

All requests require both:

  1. Authorization: Basic [base64(username:password)] header
  2. apiKey: [key] header (obtained from organization endpoint)

The organization endpoint returns a dynamic API key that should be used for subsequent requests.

Scripts

All scripts are in skills/redrover-manager/scripts/. Run with bun:

get_organization.js

Fetch organization info and validate credentials.

bun get_organization.js

Returns: Organization ID, name, and API key.

get_absences.js

Fetch raw absence/vacancy data for a date range.

bun get_absences.js <start_date> <end_date> [filled|unfilled|all]

Examples:

bun get_absences.js 2026-01-20 2026-01-27
bun get_absences.js 2026-01-27 2026-01-27 unfilled

Note: Max date range is 31 days.

get_daily_summary.js

Get daily absence summary (all staff) with counts by school, reason, and fill status.

bun get_daily_summary.js [date]

Date options:

  • today (default)
  • yesterday
  • Day names: monday, tuesday, etc.
  • last wednesday, last friday
  • Specific date: 2026-01-27

get_certificated_summary.js

Get daily absence summary for certificated staff only (Teachers, ESA, CTE).

bun get_certificated_summary.js [date]

Same date options as above. This is the most commonly requested report - focuses on classroom coverage.

get_weekly_summary.js

Get weekly trends and patterns.

bun get_weekly_summary.js [weeks_ago]

Options:

  • 0 = this week (default)
  • 1 = last week
  • 2 = two weeks ago

API Endpoints Used

Organization

GET /api/v1/organization
Security: Basic Auth
Returns: Array with org info including dynamic apiKey

Vacancy Details (Primary data endpoint)

GET /api/v1/{orgId}/Vacancy/details
Security: Basic Auth + apiKey header
Query Params:
  - fromDate: datetime (required)
  - toDate: datetime (required)
  - filled: boolean (optional - filter filled/unfilled)
  - pageSize: int (default 10, max 100)
  - page: int (default 1)
Returns: Paginated vacancy/absence data

Common Workflows

"How many absences yesterday?"

bun get_daily_summary.js yesterday

"Show unfilled positions for today"

bun get_daily_summary.js today
# Look at unfilled_positions array in output

"Weekly absence trends"

bun get_weekly_summary.js

"Last week's summary"

bun get_weekly_summary.js 1

Output Format

Daily Summary

{
  "date": "yesterday",
  "date_iso": "2026-01-26",
  "total_absences": 110,
  "filled": 75,
  "unfilled": 35,
  "fill_rate": 68,
  "by_school": {
    "PENINSULA HIGH SCHOOL": 13,
    "GIG HARBOR HIGH SCHOOL": 10
  },
  "by_reason": {
    "SICK LV > 1 SICK": 54,
    "OTH PAID LV > PERSONAL": 15
  },
  "by_position_type": {
    "Teacher": 55,
    "Paraprofessional": 36
  },
  "unfilled_positions": [
    {
      "school": "PENINSULA HIGH SCHOOL",
      "position": "MATH",
      "employee": "JANE DOE",
      "start": "2026-01-26T07:00:00",
      "end": "2026-01-26T14:30:00"
    }
  ]
}

Weekly Summary

{
  "week": "Jan 20-24, 2026",
  "week_label": "this week",
  "total_absences": 450,
  "daily_average": 90,
  "filled": 380,
  "unfilled": 70,
  "fill_rate": 84,
  "peak_day": { "day": "Monday", "count": 120 },
  "slow_day": { "day": "Friday", "count": 65 },
  "by_day": {
    "Monday": 120,
    "Tuesday": 95,
    "Wednesday": 90,
    "Thursday": 80,
    "Friday": 65
  },
  "trends": [
    { "type": "info", "message": "Monday had 120 absences (50%+ above average)" }
  ]
}

Data Fields

Key fields in vacancy data:

  • absenceDetail.employee - Employee who is absent
  • absenceDetail.reasons[0].name - Reason category (SICK, PERSONAL, etc.)
  • location.name - School name
  • position.title - Position title
  • position.positionType.name - Position category (Teacher, Paraprofessional, etc.)
  • substitute - If present, position is filled
  • start / end - Absence time range
  • needsReplacement - Whether sub is required

Schools in PSD

Common school names in data:

  • PENINSULA HIGH SCHOOL
  • GIG HARBOR HIGH SCHOOL
  • HENDERSON BAY HIGH SCHOOL
  • GOODMAN MIDDLE SCHOOL
  • HARBOR RIDGE MIDDLE SCHOOL
  • KEY PENINSULA MIDDLE SCHOOL
  • KOPACHUCK MIDDLE SCHOOL
  • ARTONDALE ELEMENTARY SCHOOL
  • DISCOVERY ELEMENTARY SCHOOL
  • EVERGREEN ELEMENTARY SCHOOL
  • HARBOR HEIGHTS ELEMENTARY SCHOOL
  • MINTER CREEK ELEMENTARY SCHOOL
  • PIONEER ELEMENTARY SCHOOL
  • PURDY ELEMENTARY SCHOOL
  • SWIFT WATER ELEMENTARY SCHOOL
  • VAUGHN ELEMENTARY SCHOOL
  • VOYAGER ELEMENTARY SCHOOL

Research Skill

Discovery-driven, exhaustive research using parallel LLM agents for comprehensive, current information gathering.

Core Principles

CRITICAL: These principles define how research works.

1. Discovery-Driven, Not List-Driven

  • Find the BEST sources, not just known sources
  • Don't limit to predefined source lists
  • The internet is huge - explore it
  • Value is in finding what user doesn't already know

2. Context-Aware

  • Load user's domain context from preferences
  • Research is RELEVANT to their specific situation
  • But context doesn't limit WHERE you search

3. Exhaustive

  • No time limits - can take 30 minutes to 3 hours
  • Don't stop at first page of results
  • Keep going until topic is exhausted
  • Follow promising links deeper

4. Multimedia

  • Not just text articles
  • Videos (YouTube), TikTok, podcasts
  • Real user experiences from forums

5. Highly Cited

  • Every claim must have a citation
  • Multiple sources for important claims
  • Note when sources conflict

6. Clarifying Questions First

Before diving into research, ask deep, thought-provoking questions to understand:

  • What's the actual goal? (not just the surface request)
  • What constraints exist? (budget, time, preferences)
  • What would success look like?
  • What have they already tried or considered?
  • Are there hidden requirements?

Example: "Research Japan ski trip" should prompt:

  • "What skill level are you and Carrie? Blue runs, black diamonds?"
  • "Is après-ski culture important, or pure skiing focus?"
  • "Do you need English-friendly areas, or comfortable with Japanese-only?"
  • "Any specific dates that are fixed vs flexible?"
  • "Besides skiing, anything else you want to do (onsen, food tours)?"

Domain Context Loading

Research automatically loads relevant context from preferences based on detected domain.

How It Works

  1. Detect domain from query (travel, shopping, work, etc.)
  2. Load research_domains.[domain] from preferences
  3. Load referenced context keys
  4. Fetch any dynamic data (point balances, etc.)
  5. Apply domain-specific research patterns

Available Domains

  • travel - Loads loyalty programs, credit cards, ski passes, fetches point balances
  • work_education - Loads PSD context, CoSN membership, K-12 patterns
  • shopping - Price comparison, quality patterns
  • ai_coding - Tech stack, GitHub/HN patterns
  • consulting - Strategic recommendations patterns

Dynamic Data Fetching

For travel research, use browser-control to fetch current:

  • Marriott points balance
  • Alaska miles balance
  • Chase points balance
  • Active transfer bonus promotions

When to Activate

Use this skill when user needs:

  • Current information (credit card perks, travel deals, policies)
  • Multi-perspective analysis (comparing options)
  • Deep investigation of complex topics
  • Fact-checking or verification
  • Market research or trend analysis

Travel Research Requirements

CRITICAL: Travel research MUST include user-generated content:

Required Sections for Travel

  1. User Reviews - TripAdvisor, FlyerTalk, Reddit feedback
  2. "What I Wish I Knew" - Common mistakes and gotchas
  3. Real Experiences - Actual trip reports from similar travelers
  4. Restaurant/Hotel Reviews - With prices and quality feedback
  5. Transportation Tips - Real user experiences with logistics

Sources to Search

  • TripAdvisor reviews and forums
  • FlyerTalk (for points/miles properties)
  • Reddit (r/JapanTravel, r/skiing, r/churning, etc.)
  • Ski forums and trip reports
  • Points/miles blogs with personal reviews

Browser Access for Deep Research

Use the browser-control skill to scrape full threads and reviews that require:

  • JavaScript rendering (Reddit, modern forums)
  • Authentication (FlyerTalk, logged-in content)
  • Dynamic content loading

Prerequisites:

  1. Brave must be running: cd skills/browser-control && ./scripts/launch-chrome.sh
  2. User must be logged into relevant sites in the Brave Geoffrey profile

Available Scripts (in skills/browser-control/scripts/):

# Navigate and get page content
bun navigate.js "https://www.reddit.com/r/JapanTravel/comments/..."

# Extract specific content
bun extract.js "https://flyertalk.com/forum/thread" ".post-content" --all

# Search travel sites directly
bun search.js reddit "Hakuba ski resort tips"
bun search.js flyertalk "Marriott Bonvoy Japan redemption"

# Capture current page without navigating
bun capture.js /tmp/screenshot.png

When to Use Browser Control:

  • Reddit threads (full comments, not just preview)
  • FlyerTalk forum posts (complete thread content)
  • Hotel/airline pages requiring login (availability, points pricing)
  • Sites that block web scraping but allow browsers

Research Tool Decision Tree

Start with WebSearch/WebFetch for:

  • General facts and information
  • Blog posts and news articles
  • Static content that's publicly accessible
  • Quick lookups

Escalate to browser-control when:

  • WebFetch returns truncated/incomplete content (JS-rendered sites)
  • Need authenticated access (user's Marriott/Alaska account)
  • Need real-time prices or availability
  • Forum threads show only previews
  • Site blocks scraping but allows browsers

Example Flow:

  1. User asks: "What do people say about Westin Rusutsu?"
  2. Start with WebSearch for blog reviews
  3. Find promising Reddit/FlyerTalk threads
  4. Use browser-control to get full thread content
  5. Synthesize findings with citations

Citation Requirements

CRITICAL: All research output MUST include citations.

Inline Citations

Every factual claim must link to its source:

  • "The Westin Rusutsu costs 70,000 points peak (Point Hacks)"
  • "Shinkansen to Nagano takes 1.5 hours (Corritrip)"

Source Section

Every research report must end with a complete "Sources" section listing all URLs used.

Why This Matters

  • User needs to verify information
  • Information changes frequently (credit card perks, prices)
  • Establishes credibility
  • Allows deeper exploration

No Citation = Don't Include

If you can't cite a source for a claim, either:

  1. Find a source
  2. Mark it as "unverified"
  3. Don't include it

Architecture

Query Decomposition

Break complex questions into 3-7 sub-queries covering different angles:

  • Factual/definitional
  • Comparative
  • Current state
  • Expert opinions
  • User experiences
  • Edge cases

Parallel Agent Execution

Launch multiple researcher agents simultaneously:

  • Perplexity - Best for current web information, citations
  • Gemini - Good for multi-perspective synthesis
  • OpenAI - Strong structured analysis
  • Claude - Deep reasoning, nuanced analysis

Result Synthesis

  • Collect all findings
  • Identify consensus vs conflicts
  • Score confidence per finding
  • Cite sources
  • Provide actionable recommendations

Available Agents

Agents are in ./agents/ directory:

AgentBest ForAPI Required
perplexity-researcher.mdCurrent web info, citationsPERPLEXITY_API_KEY
gemini-researcher.mdMulti-angle comparisonGEMINI_API_KEY
openai-researcher.mdStructured analysisOPENAI_API_KEY
claude-researcher.mdDeep reasoningNative (Claude Code)

Usage

Basic Research

User: "Research the best ways to maximize Alaska Airlines miles for Japan flights"

Geoffrey:
1. Decomposes into sub-queries:
   - Current Alaska redemption rates to Japan
   - Partner airline options (JAL, etc.)
   - Sweet spots and award availability patterns
   - Credit card earning strategies
   - Recent devaluations or changes

2. Launches 4 agents in parallel

3. Synthesizes findings with confidence scores

Workflow Command

Use /conduct-research [topic] to trigger full parallel research workflow.

Output Format

## Research: [Topic]

### Context Applied
- Domain: [travel/shopping/work/etc]
- User context loaded: [what was loaded from preferences]
- Dynamic data fetched: [current point balances, etc]

### Executive Summary
[2-3 paragraph overview of key findings and main recommendation]

### Detailed Findings

#### Sub-topic 1
Information with citations throughout. For example, "The Westin Rusutsu
costs 70,000 points peak" ([Point Hacks](url)) and "offers ski-in/ski-out
access" ([Marriott](url)).

#### Sub-topic 2
More information with inline citations...

### Multimedia Resources
- [Video: Title](url) - brief description
- [Podcast: Episode](url) - brief description
- [TikTok: @user](url) - brief description

### What I Discovered You Might Not Know
- Surprising finding 1 that user likely didn't know
- Surprising finding 2
- New source or perspective discovered

### Recommendations
1. Actionable recommendation specific to user's context
2. Another action based on their situation

### Confidence Assessment
- High confidence: [topics with multiple agreeing sources]
- Needs verification: [topics with limited sources]
- Conflicting information: [where sources disagree]

### All Sources
Complete list of every URL referenced:
- [Source Name 1](full-url)
- [Source Name 2](full-url)
- [Source Name 3](full-url)

Note: Every factual claim needs an inline citation. The "All Sources" section at the end provides a consolidated reference list.

Saving Research Reports

ALWAYS save research reports to Google Docs after completing research.

Default Behavior

  1. Create Google Doc in Geoffrey/Research folder
  2. Use appropriate account (hrg for personal, psd for work)
  3. Apply markdown formatting (headers, bold, links)
  4. Return link to user

How to Save

cd skills/google-workspace
bun docs/create_doc.js <account> --title "<Research Topic>" --folder Research --content "<markdown>"

Account Selection

  • hrg - Personal travel, consulting
  • psd - Work-related research
  • kh - Personal projects

Future: Obsidian Integration

Will also save to local Obsidian vault (when skill is built).

API Configuration

Keys stored in: ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env

PERPLEXITY_API_KEY=pplx-...
GEMINI_API_KEY=...
OPENAI_API_KEY=sk-...
# Note: Claude runs natively in Claude Code, no API key needed

Performance

  • Time: 30 minutes to 3 hours for exhaustive research (not 15-45 seconds)
  • Depth: Exhaustive - multiple search pages, follow links, multimedia
  • Sources: Discover new sources, not just known lists
  • Accuracy: Cross-referenced with confidence scoring, all claims cited

Limitations

  • API rate limits may throttle parallel requests
  • Costs accrue per API call
  • Not all agents may have access to same sources
  • Real-time data (stock prices, availability) needs direct API access

Future Enhancements

  • Caching frequent research topics
  • Learning which agents are best for which domains
  • Automatic source credibility scoring
  • Research history and versioning

Seven Advisors Decision Council

Structured multi-perspective deliberation framework adapted from de Bono's Six Thinking Hats with a 7th Stakeholder perspective. Each advisor brings a distinct cognitive lens to help make better decisions.

The Seven Advisors

#AdvisorColorFocusCore Question
1FacilitatorBlueProcess & framing"What exactly are we deciding?"
2AnalystWhiteFacts & data"What do we actually know?"
3IntuitiveRedEmotions & gut feel"How does this feel?"
4InnovatorGreenCreative alternatives"What else could we do?"
5AdvocateYellowBenefits & optimism"What's the best case?"
6CriticBlackRisks & pitfalls"What could go wrong?"
7StakeholderOrangeAffected parties"Who is impacted and how?"

Modes

Full Council (Default)

All 7 advisors deliberate, followed by facilitator synthesis. Use this for important decisions where thoroughness matters.

Individual Advisor

Consult a single advisor when you need one specific perspective. User specifies which advisor by name or color.

Example: "What would the Critic say about this plan?" or "Give me the Red Hat perspective."

Deliberation Sequence

The Facilitator opens by framing the decision. Then all six advisors analyze simultaneously — each works only from the Facilitator's framing, not from each other's output. This parallel structure is intentional: it prevents groupthink and anchoring bias. Each advisor delivers an independent perspective uncontaminated by the others.

Finally, the Facilitator returns to synthesize all six perspectives into a single recommendation with cross-references, a decision matrix, and concrete next steps.

Execution flow:

  1. Facilitator (Blue) — Frames the decision, lists options, defines success criteria, assesses stakes
  2. Six Advisors in parallel:
    • Analyst (White) — Facts, evidence quality, assumptions audit, data gaps
    • Intuitive (Red) — Emotions, gut reactions, unspoken concerns, emotional forecast
    • Innovator (Green) — Alternatives, constraint inversion, hybrid approaches, wild cards
    • Advocate (Yellow) — Best cases, hidden strengths, compounding benefits, values alignment
    • Critic (Black) — Pre-mortem, failure modes, mitigation paths, reversibility assessment
    • Stakeholder (Orange) — Power/interest map, equity audit, missing voices, communication needs
  3. Facilitator Synthesis (Blue) — Cross-references all six, builds decision matrix, delivers recommendation

Why parallel? Sequential deliberation causes anchoring — the Analyst's facts shape the Intuitive's feelings, the Critic's fears constrain the Innovator's ideas. Parallel execution means each advisor gives their honest, independent read.

AI Studio: A JSON export is available for running this council in PSD AI Studio, where the parallel execution is handled natively. See ~/Downloads/seven-advisors-council.json.

Workflow

Step 1: Receive the Decision

User presents a decision or dilemma. Can be:

  • A binary choice ("Should I X or Y?")
  • An open question ("How should I approach X?")
  • A strategic direction ("What's the right move for X?")

Step 2: Determine Mode

  • If user asks for a specific advisor → Individual Advisor mode
  • Otherwise → Full Council mode

Step 3: Load Advisor Profiles

Read skills/seven-advisors/references/advisor-profiles.md for detailed advisor personas.

Step 4: Execute Deliberation

Full Council: Run through all 8 steps (facilitator open → 6 advisors → facilitator synthesis). Each advisor speaks in their distinct voice and provides structured analysis (400-600 words per advisor, 800-1200 words for synthesis).

Individual Advisor: Only the requested advisor speaks.

Step 5: Invite Follow-Up

After the council delivers its recommendation, invite the user to:

  • Ask a specific advisor to elaborate
  • Challenge a particular point
  • Run the council on a follow-up question
  • Request the dissenting view

Output Format

Each Advisor's Entry

Each advisor provides structured sections specific to their lens (not just prose + bullets). See advisor profiles for section details. General format:

### [Emoji] [Advisor Name] ([Color]) — [Core Question]

**1. [Section Name]**
[Structured analysis]

**2. [Section Name]**
[Structured analysis]

... (5-7 sections per advisor, 400-600 words total)

Advisor Emojis:

  • Facilitator: 🔵
  • Analyst: ⚪
  • Intuitive: 🔴
  • Innovator: 🟢
  • Advocate: 🟡
  • Critic: ⚫
  • Stakeholder: 🟠

Facilitator Synthesis (Final Step)

The synthesis is the crown jewel — the longest and most detailed output (800-1200 words). It cross-references advisor arguments by name and builds a decision matrix.

---

## 🔵 Facilitator Synthesis

### Advisor Highlights
[Single most critical insight from each advisor, cited by name]

### Consensus
[Points of convergence across 3+ advisors]

### Key Tensions
[Where advisors disagree, naming specific advisors and their arguments]

### Decision Matrix
| Option | Feasibility | Risk Level | Stakeholder Impact | Upside Potential | Values Alignment |
|--------|------------|------------|-------------------|-----------------|-----------------|

### Recommendation
[Decisive recommended path — WHAT, WHY (citing advisors), WHEN]

### The Strongest Counter-Argument
[Best argument AGAINST the recommendation, citing which advisor made it, and why this path is still recommended despite it]

### Conditions for Success
[Critical assumptions and prerequisites]

### Risk Mitigation Plan
[Critic's top 3 concerns with specific mitigation actions]

### Stakeholder Safeguards
[Stakeholder's equity concerns with protective actions]

### What We Still Don't Know
[Analyst's unresolved unknowns that could change the recommendation]

### Next Steps
1. [Concrete, specific, time-bound action]
2. [Concrete, specific, time-bound action]
3. [Concrete, specific, time-bound action]

Skill Creator

A skill for creating new skills and iteratively improving them.

At a high level, the process of creating a skill goes like this:

  • Decide what you want the skill to do and roughly how it should do it
  • Write a draft of the skill
  • Create a few test prompts and run claude-with-access-to-the-skill on them
  • Help the user evaluate the results both qualitatively and quantitatively
    • While the runs happen in the background, draft some quantitative evals if there aren't any. Then explain them to the user
    • Use the eval-viewer/generate_review.py script to show the user the results, and also let them look at the quantitative metrics
  • Rewrite the skill based on feedback from the user's evaluation
  • Repeat until satisfied
  • Expand the test set and try again at larger scale

Your job is to figure out where the user is in this process and help them progress. Maybe they want to make a skill from scratch, or maybe they already have a draft and want to iterate.

Be flexible -- if the user says "I don't need to run a bunch of evaluations, just vibe with me", do that instead.

After the skill is done (order is flexible), run the skill description improver to optimize triggering.

Communicating with the user

Pay attention to context cues to understand how to phrase communication. In the default case:

  • "evaluation" and "benchmark" are borderline, but OK
  • for "JSON" and "assertion" you want to see cues from the user that they know what those things are before using them without explaining

It's OK to briefly explain terms if you're in doubt.


Creating a skill

Capture Intent

Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first -- the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill gaps, and should confirm before proceeding.

  1. What should this skill enable Claude to do?
  2. When should this skill trigger? (what user phrases/contexts)
  3. What's the expected output format?
  4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation) benefit from test cases. Skills with subjective outputs (writing style, art) often don't. Suggest the appropriate default based on skill type, but let the user decide.

Interview and Research

Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.

Check available MCPs -- if useful for research, research in parallel via subagents if available.

Initialize the Skill

When creating a new skill from scratch, run the init_skill.py script to scaffold the directory structure:

uv run scripts/init_skill.py <skill-name> --path <output-directory>

The script:

  • Creates the skill directory at the specified path
  • Generates a SKILL.md template with proper frontmatter and TODO placeholders
  • Creates example resource directories: scripts/, references/, and assets/
  • Automatically registers the skill in CLAUDE.md's Available Skills table

Skip this step if the skill already exists and you're iterating or packaging.

Manual Registration

If not using init_skill.py, register in CLAUDE.md manually:

  1. Find the "Available Skills" table in the "Skill Locations" section
  2. Add a new row: | {skill-name} | \skills/{skill-name}/SKILL.md` |`
  3. Keep the table alphabetically sorted

Write the SKILL.md

Based on the user interview, fill in these components:

  • name: Skill identifier (kebab-case)
  • description: When to trigger, what it does. This is the primary triggering mechanism -- include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: Claude tends to "undertrigger" skills. To combat this, make descriptions a little bit "pushy" -- e.g., "Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
  • the rest of the skill :)

Skill Writing Guide

Anatomy of a Skill
skill-name/
+-- SKILL.md (required)
|   +-- YAML frontmatter (name, description required)
|   +-- Markdown instructions
+-- Bundled Resources (optional)
    +-- scripts/    - Executable code for deterministic/repetitive tasks
    +-- references/ - Docs loaded into context as needed
    +-- assets/     - Files used in output (templates, icons, fonts)

scripts/: Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. Scripts may be executed without loading into context, but can still be read by Claude for patching.

references/: Documentation intended to be loaded as needed into context. Keep in references/ when content is detailed (schemas, API docs, policies). If files are large (>300 lines), include a table of contents. Include grep search patterns in SKILL.md for very large files (>10k words).

assets/: Files NOT intended to be loaded into context, but used within output Claude produces (templates, images, fonts, boilerplate).

Avoid duplication: Information should live in either SKILL.md or references, not both. Keep SKILL.md lean.

Progressive Disclosure

Skills use a three-level loading system:

  1. Metadata (name + description) - Always in context (~100 words)
  2. SKILL.md body - In context whenever skill triggers (<500 lines ideal)
  3. Bundled resources - As needed (unlimited, scripts can execute without loading)

Key patterns:

  • Keep SKILL.md under 500 lines; split content when approaching this limit
  • Reference files clearly from SKILL.md with guidance on when to read them
  • For large reference files (>300 lines), include a table of contents
  • Avoid deeply nested references -- keep one level deep from SKILL.md

Domain organization: When a skill supports multiple domains/frameworks, organize by variant:

cloud-deploy/
+-- SKILL.md (workflow + selection)
+-- references/
    +-- aws.md
    +-- gcp.md
    +-- azure.md

Claude reads only the relevant reference file.

For more patterns, see references/workflows.md (sequential/conditional workflows) and references/output-patterns.md (template and example patterns).

What Not to Include

A skill should only contain files that directly support its functionality. Do NOT create:

  • README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md, etc.
  • Setup and testing procedures, user-facing documentation
  • Auxiliary context about the process that went into creating it
Writing Style

Try to explain to the model why things are important in lieu of heavy-handed MUSTs. Use theory of mind and try to make the skill general rather than narrow to specific examples. If you find yourself writing ALWAYS or NEVER in all caps, reframe and explain the reasoning so the model understands why it matters. That's more humane, powerful, and effective.

Use imperative form in instructions. Prefer examples over verbose explanations.

Defining output formats:

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Examples pattern:

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Test Cases

After writing the skill draft, come up with 2-3 realistic test prompts -- the kind of thing a real user would actually say. Share them with the user: "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.

Save test cases to evals/evals.json. Don't write assertions yet -- just the prompts. Draft assertions in the next step while the runs are in progress.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

See references/schemas.md for the full schema (including assertions).

Running and evaluating test cases

This section is one continuous sequence -- don't stop partway through. Do NOT use /skill-test or any other testing skill.

Put results in <skill-name>-workspace/ as a sibling to the skill directory. Within the workspace, organize results by iteration (iteration-1/, iteration-2/, etc.) and within that, each test case gets a directory (eval-0/, eval-1/, etc.). Create directories as you go.

Step 1: Spawn all runs (with-skill AND baseline) in the same turn

For each test case, spawn two subagents in the same turn -- one with the skill, one without. Launch everything at once so it all finishes around the same time.

With-skill run:

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about>

Baseline run (same prompt, but depends on context):

  • Creating a new skill: no skill at all. Same prompt, save to without_skill/outputs/.
  • Improving an existing skill: the old version. Before editing, snapshot the skill, point baseline at the snapshot. Save to old_skill/outputs/.

Write an eval_metadata.json for each test case with a descriptive name. If this iteration uses new/modified eval prompts, create these files for each new eval directory.

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

Step 2: While runs are in progress, draft assertions

Draft quantitative assertions for each test case and explain them to the user. Good assertions are objectively verifiable and have descriptive names. Subjective skills are better evaluated qualitatively -- don't force assertions.

Update eval_metadata.json files and evals/evals.json with the assertions.

Step 3: As runs complete, capture timing data

When each subagent task completes, you receive total_tokens and duration_ms. Save immediately to timing.json in the run directory:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

This is the only opportunity to capture this data -- process each notification as it arrives.

Step 4: Grade, aggregate, and launch the viewer

Once all runs are done:

  1. Grade each run -- spawn a grader subagent that reads agents/grader.md and evaluates assertions against outputs. Save to grading.json. The grading.json expectations array must use fields text, passed, and evidence. For programmatically checkable assertions, write and run a script.

  2. Aggregate into benchmark:

    python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
    

    Produces benchmark.json and benchmark.md. Put each with_skill version before its baseline.

  3. Do an analyst pass -- read agents/analyzer.md ("Analyzing Benchmark Results" section) for patterns the aggregate stats might hide.

  4. Launch the viewer:

    nohup python <skill-creator-path>/eval-viewer/generate_review.py \
      <workspace>/iteration-N \
      --skill-name "my-skill" \
      --benchmark <workspace>/iteration-N/benchmark.json \
      > /dev/null 2>&1 &
    VIEWER_PID=$!
    

    For iteration 2+, also pass --previous-workspace <workspace>/iteration-<N-1>.

    Headless environments: Use --static <output_path> for standalone HTML.

  5. Tell the user the results are in their browser with Outputs and Benchmark tabs.

Step 5: Read the feedback

When the user is done, read feedback.json. Empty feedback means the user thought it was fine. Focus improvements on test cases with specific complaints.

Kill the viewer server when done: kill $VIEWER_PID 2>/dev/null


Improving the skill

How to think about improvements

  1. Generalize from feedback. We're creating skills used across many prompts. Don't put in fiddly overfitty changes or oppressively constrictive MUSTs. If there's a stubborn issue, try different metaphors or patterns.

  2. Keep the prompt lean. Remove things not pulling their weight. Read the transcripts -- if the skill makes the model waste time on unproductive steps, trim those parts.

  3. Explain the why. Today's LLMs are smart. When given a good harness they can go beyond rote instructions. Transmit understanding into instructions rather than rigid structures.

  4. Look for repeated work across test cases. If all test runs independently wrote similar helper scripts, bundle that script in scripts/.

The iteration loop

After improving:

  1. Apply improvements to the skill
  2. Rerun all test cases into a new iteration-<N+1>/ directory, including baseline runs
  3. Launch the reviewer with --previous-workspace pointing at previous iteration
  4. Wait for user review
  5. Read new feedback, improve again, repeat

Keep going until the user is happy, feedback is all empty, or you're not making meaningful progress.


Advanced: Blind comparison

For rigorous comparison between two skill versions, read agents/comparator.md and agents/analyzer.md. The basic idea: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.

Optional, requires subagents, most users won't need it.


Description Optimization

The description field is the primary mechanism determining whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering.

Step 1: Generate trigger eval queries

Create 20 eval queries -- a mix of should-trigger (8-10) and should-not-trigger (8-10). Save as JSON:

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

Queries must be realistic -- concrete, specific, with file paths, personal context, column names. Some should be casual, have typos, abbreviations. Focus on edge cases rather than clear-cut.

For should-not-trigger queries, the most valuable ones are near-misses -- queries sharing keywords with the skill but actually needing something different. Don't make them obviously irrelevant.

Step 2: Review with user

Present the eval set using the HTML template:

  1. Read assets/eval_review.html
  2. Replace placeholders: __EVAL_DATA_PLACEHOLDER__, __SKILL_NAME_PLACEHOLDER__, __SKILL_DESCRIPTION_PLACEHOLDER__
  3. Write to a temp file and open it
  4. User edits, then clicks "Export Eval Set" which downloads to ~/Downloads/eval_set.json

Step 3: Run the optimization loop

Tell the user this will take some time, then run in background:

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

The loop splits the eval set into 60% train / 40% test, evaluates descriptions (3 runs per query), uses Claude with extended thinking to propose improvements, and iterates up to 5 times. Selects by test score to avoid overfitting.

How skill triggering works

Skills appear in Claude's available_skills list with name + description. Claude only consults skills for tasks it can't easily handle on its own -- simple one-step queries may not trigger even if the description matches. Eval queries should be substantive enough that Claude would benefit from consulting a skill.

Step 4: Apply the result

Take best_description from JSON output and update the skill's SKILL.md frontmatter. Show before/after and report scores.


Package and Present (only if present_files tool is available)

Check for present_files tool. If available, package and present:

python -m scripts.package_skill <path/to/skill-folder>

The packaging script validates the skill first, then creates a distributable .skill file (zip format).


Reference files

The agents/ directory contains instructions for specialized subagents:

  • agents/grader.md -- Evaluate assertions against outputs
  • agents/comparator.md -- Blind A/B comparison between two outputs
  • agents/analyzer.md -- Analyze why one version beat another, or analyze benchmark patterns

The references/ directory has additional documentation:

  • references/schemas.md -- JSON structures for evals.json, grading.json, benchmark.json, etc.
  • references/workflows.md -- Sequential and conditional workflow patterns
  • references/output-patterns.md -- Template and example output patterns

Core loop for emphasis:

  • Figure out what the skill is about
  • Draft or edit the skill
  • Run claude-with-access-to-the-skill on test prompts
  • With the user, evaluate the outputs (create benchmark.json and run eval-viewer/generate_review.py)
  • Repeat until satisfied
  • Package the final skill

PSD Standard Operating Procedure Creator

Interview-driven SOP generator that matches the format, conventions, and quality of existing Peninsula School District operational documents.

Workflow

Phase 1: Interview — Identify the Procedure

Start with the core question: "What procedure or process do you need documented?"

Based on the answer, ask follow-ups to determine the SOP category:

Round 1 — Basics:

  1. What specific process or procedure needs documenting?
  2. Which department owns this? (Athletics & Activities, Teaching & Learning, Employee Support Services, Safety & Security, Finance & Operations, Technology, Communications, Governance & Leadership)
  3. Who is the primary audience? (all employees, specific roles, building-level staff, etc.)

Round 2 — Process Details: 4. Walk me through the procedure step by step — what happens first, then what? 5. Are there decision points where different paths are taken? (e.g., severity levels, different scenarios) 6. Who is responsible at each step? (specific roles, not people) 7. What triggers this procedure? (event, request, schedule, incident) 8. What's the expected outcome when the procedure is completed?

Round 3 — Compliance & Safety: 9. Are there board policies, RCWs, WACs, or CBA sections that apply? 10. Are there safety considerations or risks involved? 11. Who monitors compliance? How often? What does auditing look like? 12. Are there related SOPs this should cross-reference?

Round 4 — Complexity Assessment: 13. Does this need a classification system? (e.g., Minor/Moderate/Severe) 14. Are there forms, checklists, or templates needed? 15. Does this involve multiple PSD systems? Which ones? (Freshservice, PowerSchool, Skyward, RedRover, ParentSquare, Nav360, etc.) 16. Are there roles that need defining in a glossary?

Do NOT ask all 16 questions at once. Ask Rounds 1-2 first. Based on the complexity of answers, decide whether Rounds 3-4 are needed or if enough info has been gathered.

Phase 2: Determine Complexity & Draft

Read references/template-guide.md for the complete template, conventions, department-specific patterns, and examples.

Based on the interview, select the appropriate complexity level:

Simple (5-10 steps, single path):

  • Template sections only: Title, Scope, Procedure, Safety, QC, References, Revision History
  • Examples: Suspicious Vehicle reporting, Badge Photo standards, Building Safety Committee setup

Moderate (multi-step with branching or system walkthroughs):

  • Add: Purpose, sub-steps, cross-references to other SOPs, compliance section
  • Examples: Substitute Release Request, Fingerprinting, Clock Hours, Amazon Business ordering

Complex (multi-section with classifications, tables, forms):

  • Add: Definitions, Roman numeral sections, severity/classification tables, flowcharts, glossary, addendums, forms
  • Examples: Clubs & Athletics, Staff/Student Investigations, Inclement Weather, Emergency Supplies

Phase 3: Present Draft & Iterate

Present the draft SOP and ask:

  • "Are there steps I've missed or gotten wrong?"
  • "Are the role assignments correct?"
  • "Should any sections have more detail?"
  • Mark sections needing stakeholder input with [NEEDS INPUT: description] placeholders

Phase 4: Finalize & Output

End every SOP with LH_swoop footer element.

CRITICAL: SOPs are ONLY created as Google Docs in the shared drive. NEVER write SOPs to the Obsidian vault, local filesystem, or any other location — not even as an intermediate draft. Draft directly in memory during the interview/iteration phases, then create the Google Doc as the single output.

Save to the Drafts folder (1PLeCQ6DaxWehEbzjzbXU2wLsaLTgv6Ku) in the SOP shared drive using the Google Workspace skill's drive/create_file.js with --folder 1PLeCQ6DaxWehEbzjzbXU2wLsaLTgv6Ku. The shared drive requires supportsAllDrives: true in API calls. SOPs go through a review process before being moved to their department folder.

Alternative output: Create as .docx using /docx skill and upload to the Drafts folder.

Department Subfolder IDs

DepartmentFolder ID
Athletics & Activities1E-fmzIAfAXLMVL6brEHkCy1yeZXw-_PC
Appendices & Templates180TB_nkv87qU2lwRkCXiWCmzsYgzOyjM
Teaching and Learning1lAfAp7FMQJRFL9g-_IaP_fafEnt4d4pG
Employee Support Services1ENy54q8vJJ3oekBUXYKiigtLf_aKWBPK
Communications & Public Relations1FETCQTIijsSPRj3Kil62qrr0TvGuGDvN
Safety and Security1W2bhVKqdWzSVp0B3LD_EQai_M-ur5E92
Finance and Operations1XonFKeTqSH_1qBDbLHMWRILr-hb2Pm1Q
Technology1j3235TyAzJ2pbNPaSn7dweIvizKmzN5Q
Governance and Leadership172c_1A2bXUE14bDNoOIJAeErOocx9auI
Drafts1PLeCQ6DaxWehEbzjzbXU2wLsaLTgv6Ku

Strategic Planning Manager Skill

Organizational strategic planning system for K-12 school districts using a research-backed 4-stage process. Synthesizes best practices from Education Elements, Hanover Research, AASA, ThoughtExchange, and facilitation methodology.

Start Here: New to this skill? Read guides/leader-overview.md for a full introduction to the 4-stage process, superintendent roles, team formation, and readiness assessment.

Note: For personal life/work strategic planning, use the personal-strategic-planning skill instead.

When to Activate

This skill activates when the user requests:

Full Strategic Planning Process:

  • "Help me create a strategic plan for our district"
  • "We need to do strategic planning"
  • "Let's start the district strategic planning process"
  • "Facilitate our strategic planning retreat"

Stage-Specific Work:

  • "Analyze our survey data for strategic planning"
  • "Help me process focus group transcripts"
  • "Generate a SWOT analysis"
  • "Help define our strategic directions"
  • "Build our implementation timeline"
  • "Set up progress monitoring"

Plan Update Mode:

  • "Update our existing strategic plan"
  • "It's time to refresh our strategic plan"
  • "Annual strategic plan review"

Skill Modes

Mode 1: Full Process Guide

Walk through all 4 stages sequentially, prompting for data inputs and facilitating each step.

  • Best for: New strategic plans, comprehensive planning retreats

Mode 2: Stage-Specific Entry

Jump directly into any specific stage with appropriate inputs.

  • Best for: Working on one component, picking up where you left off

Mode 3: Data Analysis Only

Process surveys, transcripts, and documents without running the full planning process.

  • Best for: Pre-work, discovery, feeding data into existing processes

Mode 4: Plan Update

Start from an existing plan, analyze progress, update for a new cycle.

  • Best for: Annual reviews, mid-cycle adjustments, refresh cycles

The 4-Stage Strategic Planning Process

Stage 1: Engage & Assess

Key Question: Where are we now? AI Role: Data analysis, synthesis, draft preparation Human Role: Data collection, stakeholder engagement, validation

What Happens:

  • Gather and analyze data (surveys, focus groups, document review)
  • Engage stakeholders across the community
  • Conduct SWOT analysis with prioritization
  • Identify investment opportunities and critical barriers

Available Scripts:

# Analyze survey data
uv run skills/strategic-planning-manager/scripts/analyze_surveys.py \
  --input survey_results.csv \
  --output-dir ./discovery

# Process focus group transcripts
uv run skills/strategic-planning-manager/scripts/process_transcripts.py \
  --input-dir ./transcripts \
  --output ./discovery/transcript-themes.json

# Generate SWOT from discovery data
uv run skills/strategic-planning-manager/scripts/generate_swot.py \
  --discovery-dir ./discovery \
  --output ./outputs/swot-analysis.md

Outputs:

  • Discovery Report (templates/discovery-report.md)
  • SWOT Analysis (templates/swot-template.md)
  • Stakeholder input summary
  • Key findings synthesis

Guide: guides/stage1-engage-assess-guide.md


Stage 2: Set Direction

Key Question: Where do we want to go? AI Role: Provide prompts, capture input, map alignment Human Role: Visioning, decision-making, prioritization

What Happens:

  • Define or reaffirm Mission, Vision, and Values
  • Identify 3-6 district priority areas
  • Define long-term outcome goals
  • Develop 4-6 strategic directions

Optional Deeper Work:

  • Deep participatory visioning exercise → guides/appendix-a-vision-development.md
  • Organizational tension analysis → guides/appendix-b-tension-analysis.md
  • Developing a Profile of a Graduate → guides/appendix-c-graduate-profile.md

Outputs:

  • Mission/Vision/Values statements
  • Priority areas with outcome goals
  • Strategic Directions Framework (templates/strategic-directions.md)
  • Direction-to-priority alignment matrix

Guide: guides/stage2-set-direction-guide.md


Stage 3: Build the Plan & Align Resources

Key Question: How will we get there? AI Role: Structure creation, timeline drafting, metric suggestions Human Role: Reality testing, commitment making, ownership assignment

What Happens:

  • Develop three-column plans (Current Reality → 1-Year → 3-Year)
  • Define measurable goals and success indicators
  • Choose strategies/initiatives per direction
  • Assign ownership and align resources
  • Build Year 1 quarterly timeline
  • Cross-direction integration check

Outputs:

  • Implementation Tables (templates/focused-implementation.md)
  • Success indicator matrix
  • First-Year Timeline (templates/first-year-timeline.md)
  • Resource alignment plan
  • Ownership chart

Guide: guides/stage3-build-plan-guide.md


Stage 4: Implement, Monitor & Improve

Key Question: Are we making progress? AI Role: Dashboard creation, report drafting, data analysis Human Role: Implementation leadership, decision-making, accountability

What Happens:

  • Develop annual action plans
  • Track leading and lagging indicators
  • Report to board and community on regular cadence
  • Make mid-course adjustments when data warrants
  • Conduct annual reviews and mid-plan refreshes

Available Scripts:

# Generate strategic plan document from all stage outputs
uv run skills/strategic-planning-manager/scripts/synthesize_plan.py \
  --work-dir ./planning \
  --output ./outputs/strategic-plan.md \
  --format full  # or 'executive', 'board', 'staff', 'community'

Outputs:

  • Full Strategic Plan Document (templates/full-strategic-plan.md)
  • Executive Summary (templates/executive-summary.md)
  • Annual action plans
  • Progress dashboards
  • Board reports

Guide: guides/stage4-implement-improve-guide.md


Available Scripts

Survey Analysis

uv run skills/strategic-planning-manager/scripts/analyze_surveys.py \
  --input data.csv \
  --format csv \
  --output-dir ./discovery

Supported formats: CSV, JSON, Excel (.xlsx, .xls)

Analysis includes:

  • Response distribution statistics
  • Sentiment analysis per question
  • Theme extraction from open-ended responses
  • Stakeholder group comparisons (if demographics provided)
  • Word frequency and phrase analysis

Transcript Processing

uv run skills/strategic-planning-manager/scripts/process_transcripts.py \
  --input-dir ./transcripts \
  --output ./discovery/transcript-themes.json

Analysis includes:

  • Theme extraction using NLP
  • Sentiment patterns
  • Speaker/stakeholder attribution (if labeled)
  • Quote extraction for evidence
  • Cross-transcript pattern identification

SWOT Generation

uv run skills/strategic-planning-manager/scripts/generate_swot.py \
  --discovery-dir ./discovery \
  --output ./outputs/swot-analysis.md

Generates:

  • Data-driven SWOT matrix
  • Supporting evidence citations
  • Investment priority recommendations
  • Barrier analysis

Plan Synthesis

uv run skills/strategic-planning-manager/scripts/synthesize_plan.py \
  --work-dir ./planning \
  --output ./outputs/strategic-plan.md \
  --format full  # or 'executive', 'board', 'staff', 'community'

Generates:

  • Complete strategic plan document
  • Multiple stakeholder versions
  • Executive summary
  • Board presentation outline

Facilitator Guides

GuidePurposeDuration
leader-overview.mdFull process overview for superintendentsReference
stage1-engage-assess-guide.mdData collection + SWOT workshop2-6 weeks + 2.5 hrs
stage2-set-direction-guide.mdVision, priorities, strategic directions3-4 hours
stage3-build-plan-guide.mdImplementation planning workshop3-4 hours
stage4-implement-improve-guide.mdMonitoring and continuous improvementOngoing
appendix-a-vision-development.mdDeep participatory visioning exercise3-4 hours
appendix-b-tension-analysis.mdOrganizational tension analysis2-3 hours
appendix-c-graduate-profile.mdProfile of a Graduate development processMulti-session
six-month-timeline.mdMonth-by-month planning timelineReference
retreat-agenda-2day.mdFull 2-day retreat (all 4 stages)2 days
retreat-agenda-condensed.mdCondensed 1-day (Stages 1-3)1 day

Each guide includes:

  • Detailed agenda with timing
  • Facilitator prompts and questions
  • Small group and large group activities
  • Materials needed
  • Expected outputs
  • Common challenges and solutions

Data Storage (Obsidian)

Strategic plans are stored in the Obsidian vault:

Personal_Notes/Geoffrey/Strategic-Plans/
├── {District-Name}/
│   ├── {Year}-Strategic-Plan.md
│   ├── Discovery-Report.md
│   ├── SWOT-Analysis.md
│   ├── Strategic-Directions.md
│   ├── Implementation-Plan.md
│   ├── Progress-Reports/
│   │   └── [Quarterly/annual reports]
│   └── Facilitator-Guides/
│       └── [Generated guides for this district]

Frontmatter:

---
type: strategic-plan
district: {District Name}
year: {YYYY}
stage: {1-4 or complete}
status: draft | in-progress | final
created: {date}
updated: {date}
---

Common K-12 Strategic Themes

Pre-loaded from config/k12-themes.yaml:

ThemePrevalenceKey Metrics
Student Achievement90%+Test scores, graduation rates, college readiness
Equity & Access90%Gap reduction, program access, representation
Staff Quality & Retention80%Hiring, development, turnover rates
Parent/Community Engagement80%Participation, satisfaction, partnerships
Facilities & Technology75%Infrastructure, device ratios, connectivity
Fiscal Sustainability70%Budget balance, reserves, cost efficiency
Social-Emotional LearningGrowingSEL metrics, climate surveys, wellness
Safety & SecurityVariableIncident rates, preparedness, climate

Research Foundations

This skill synthesizes best practices from:

ThoughtExchange 3 Models:

  • Plan on a Page
  • VMOSA (Vision → Mission → Objectives → Strategies → Action Plan)
  • Five-Step Model

Education Elements (7 Steps):

  • Pre-Planning Assessment
  • Community Engagement Strategy
  • Strategic Planning Team Formation
  • Build Common Understanding
  • Design Solutions (prioritization matrix)
  • Communication Planning
  • Monitoring and Adaptation

Hanover Research (5 Phases):

  • Discovery (surveys, benchmarking)
  • Analysis (SWOT synthesis)
  • Visioning (workshops)
  • Goal Setting (SMART goals)
  • Implementation Roadmap (KPIs)

AASA 10-Step Framework:

  • Comprehensive district leadership approach
  • Emphasis on board/superintendent buy-in
  • Quarterly monitoring, annual evaluation

Facilitation Methodology:

  • ORID Method (Objective → Reflective → Interpretive → Decisional)
  • Focused Conversation
  • Consensus Workshop
  • Strategic Planning Matrix

Example Workflow

Starting a New Strategic Plan

User: "Help me create a strategic plan for our district"

Geoffrey:
1. Ask which mode: Full Process, Stage-Specific, or Data Analysis
2. If Full Process:
   - Ask about available data (surveys, transcripts, existing docs)
   - Ask about timeline (retreat dates, board presentation date)
   - Ask about stakeholder groups to involve
3. Begin Stage 1: Engage & Assess
   - Ingest provided data files
   - Generate Discovery Report and SWOT
4. Continue through stages with appropriate AI/human balance
5. Generate final plan documents
6. Save to Obsidian vault

Analyzing Survey Data Only

User: "I have survey results I need to analyze for strategic planning"

Geoffrey:
1. Ask for data file(s) and format
2. Run analyze_surveys.py
3. Present findings:
   - Key themes
   - Stakeholder differences
   - Sentiment analysis
   - Suggested SWOT inputs
4. Ask if user wants to continue to SWOT generation

Updating an Existing Plan

User: "We need to update our strategic plan for year 2"

Geoffrey:
1. Load existing plan from Obsidian
2. Ask about progress on Year 1 accomplishments
3. Collect new data/feedback
4. Identify what's on track, at risk, off track
5. Recommend adjustments to timeline/directions
6. Generate updated plan document

Error Handling

1. No data provided for discovery:

  • Offer to conduct discovery interviews directly
  • Suggest data collection templates
  • Proceed with qualitative input only

2. Insufficient stakeholder representation:

  • Flag which groups are missing
  • Recommend targeted data collection
  • Note limitation in final report

3. Conflicting stakeholder priorities:

  • Surface tensions explicitly
  • Use as input for strategic direction decisions
  • Document minority viewpoints

4. Unrealistic implementation timeline:

  • Flag capacity concerns
  • Suggest prioritization/phasing
  • Recommend reducing scope or extending timeline

5. Plan update with no progress data:

  • Conduct progress interview
  • Use qualitative assessment
  • Note "self-reported" vs "measured" progress

Version History

v2.0.1 (2026-02-02)

  • Added Appendix C: Developing a Profile of a Graduate
  • Community workshop and student voice facilitation scripts
  • Common competency categories reference table
  • Guidance on connecting profile to strategic plan
  • Updated facilitation prompts with graduate_profile section

v2.0.0 (2026-02-02)

  • Restructured from 7-phase to 4-stage process
  • 4 stages: Engage & Assess → Set Direction → Plan & Align → Implement & Improve
  • New leader overview with readiness self-assessment
  • New Stage 4 guide (monitoring, board reporting, review cycles)
  • New 6-month planning timeline
  • New fillable strategic planning template
  • Deep visioning moved to Appendix A
  • Tension analysis moved to Appendix B (rebranded from "contradictions")
  • Retreat agendas restructured around 4 stages
  • Removed methodology-specific branding throughout

v1.0.0 (2026-01-26)

  • Initial release
  • 7-phase methodology
  • 4 skill modes (Full, Phase-Specific, Data Analysis, Update)
  • Python scripts for data analysis
  • Facilitator guides for human sessions
  • Obsidian integration for plan storage
  • K-12 themes and metrics library
  • Research-backed framework synthesis

Writer Skill

Generate content in your authentic voice by analyzing writing samples and applying learned voice patterns through adaptive interviewing and voice-matched generation.

Philosophy

Key Innovation: This isn't a generic AI writer - it's YOUR voice, learned from YOUR writing.

Unlike generic AI content generation, this skill:

  • Learns from 6 distinct voice profiles (work email, personal email, blog, LinkedIn, Twitter, reports)
  • Interviews you like a Pulitzer-winning journalist to deeply understand your message
  • Validates output against your authentic patterns (not generic "good writing")
  • Saves versioned drafts to Obsidian for iteration and history

Simplicity: Geoffrey's native LLM capabilities analyze your voice. Scripts just fetch samples. No complex NLP libraries - clean, maintainable architecture.


When to Activate

Use this skill when you need to:

  • Write emails that sound like you (not generic AI)
  • Draft blog posts in your established voice
  • Create social media content consistent with your style
  • Generate reports matching your professional tone
  • Ensure content authentically represents your perspective and voice

DON'T use for:

  • Quick factual responses (use native Claude)
  • Content in someone else's voice
  • Generic templates

Voice Profiles

Six distinct profiles capture different contexts:

ProfileSourceSample TargetStatus
email_workPSD Gmail (sent emails, 6mo)50+ emailsCheck writing-voice.json
email_personalPersonal/HRG Gmail (sent, 6mo)50+ emailsCheck writing-voice.json
blog_technicalpsd401.ai + blog.krishagel.com10+ postsCheck writing-voice.json
social_linkedinLinkedIn profile posts30+ postsCheck writing-voice.json
social_twitterX/Twitter posts30+ postsCheck writing-voice.json
report_formalUser-provided samples5-10 reportsCheck writing-voice.json

Confidence Levels:

  • High (0.85+): 50+ samples - voice well established
  • Moderate (0.70-0.84): 20-49 samples - patterns emerging
  • Low (<0.70): <20 samples - insufficient data, warn user

6-Phase Workflow

Phase 1: Voice Profile Selection & Validation

Goal: Load the right voice profile and verify it's ready

Process:

  1. Detect content type from user request:

    • "write email" → email_work or email_personal (ask which)
    • "blog post" → blog_technical
    • "LinkedIn post" → social_linkedin
    • "tweet" → social_twitter
    • "report" → report_formal
  2. Load voice profile:

    cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/writing-voice.json
    
  3. Check confidence and sample count:

    • If confidence ≥ 0.85: Proceed with confidence
    • If confidence 0.70-0.84: Proceed with note
    • If confidence < 0.70: Warn user, offer options

Low Confidence Response:

Only {sample_count} {content_type} samples (confidence: {confidence}).
Target: {target_samples}+ samples for 0.85+ confidence.

Options:
1. Gather more samples (recommended)
2. Use {alternative_profile} voice as proxy (confidence: {alt_confidence})
3. Proceed anyway (may not fully match your voice)

Preference?

Checkpoint 1: User confirms profile or gathers more samples


Phase 2: Deep Interview (Adaptive)

Goal: Deeply understand what you want to communicate

Process:

  1. Load interview questions from templates/interview-questions.json

  2. Adapt depth to content type:

    • Tweet/Social: 3-5 questions (~2-3 min)
    • Email Quick: 4 questions (~3 min)
    • Email Complex: 8 questions (~5 min)
    • Blog: 8-12 questions (~5-8 min)
    • Report: 15+ questions (~10-15 min)
  3. Interview like a journalist:

    • Ask follow-up questions for vague answers
    • Probe for examples, data, evidence
    • Clarify ambiguities
    • Build structured understanding

Email Interview Example (complex):

1. Who are the recipient(s) and what's the context?
   → [User answers]

2. What's the primary goal?
   → [User answers]
   [If vague: "Can you be more specific about the outcome you want?"]

3. What background do they need?
   → [User answers]

4. What are the key points? (Max 3-5)
   → [User answers]
   [If >5: "Let's focus on the most critical 3-5 points."]

... continue through 8 questions

Blog Interview Example:

1. What's your central message?
2. Why does this matter right now?
3. What should readers do/think/feel after?
4. What evidence supports this?
5. Any stories or case studies?
6. Main counterarguments?
7. How should it open?
8. Key sections (3-5)?
9. How should it close?
10. Primary audience and technical level?
11. Desired tone?

Checkpoint 2: Review interview summary, add missing details


Phase 3: Content Planning & Outline

Goal: Create a clear structure before writing

Process:

  1. Create outline based on:

    • Interview responses
    • Content type structure (email: intro + points + ask, blog: hook + body + conclusion)
    • Voice profile preferences (e.g., blog uses chronological flow, staff quotes)
  2. Apply voice-specific patterns:

    • Email: Opening pattern, bullet points for key points, clear ask
    • Blog: Subheadings for scannability, narrative flow, reflective close
    • Social: Hook first line, call-to-action
  3. Suggest length from profile:

    • Email avg: Check profile examples
    • Blog avg: Check profile examples
    • Social: Platform limits (LinkedIn 1300 chars, Twitter 280 chars)

Email Outline Example:

## Email Plan

**Subject**: [Based on purpose]

**Opening**: [Use opening pattern from profile, e.g., "I've reviewed {topic}..."]

**Body**:
- Point 1: [From interview]
- Point 2: [From interview]
- Point 3: [From interview]

**Ask**: [Specific call-to-action from interview]

**Closing**: [Use closing pattern from profile, e.g., "Let me know if..."]

**Tone**: Direct, professional, action-oriented
**Length**: ~200 words (typical for email_work)

Blog Outline Example:

## Blog Plan

**Title**: [Derived from central message]

**Structure**:
1. Opening: [Hook strategy - context-setting or reflective quote]
2. Background & Context
3. [Main section 1]
4. [Main section 2]
5. [Main section 3]
6. Impact & Results
7. Closing: [Forward-looking reflection]

**Voice elements**:
- Staff quotes (use throughout)
- Chronological narrative flow
- Subheadings for scannability
- Accessible but authoritative tone

**Length**: ~850 words (typical for blog_technical)

Checkpoint 3: User approves outline


Phase 4: Draft Generation

Goal: Write content that authentically sounds like you

Process:

  1. Load identity context:

    cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/identity-core.json
    

    Use for personality alignment:

    • communication_preferences.style → Direct, no-nonsense, concise
    • decision_framework → Analytical, evidence-based
    • telos_summary.top_3_values → Equity, excellence, empathy
  2. Apply voice characteristics as generation guidelines:

    • Tone: From voice_characteristics.tone
    • Sentence structure: From voice_characteristics.sentence_structure
    • Vocabulary: Common terms, avoided terms
    • Formatting: Bullet points, markdown, emphasis patterns
    • Opening: Use patterns from opening_patterns
    • Closing: Use patterns from closing_patterns
    • Argument structure: Lead with conclusion, use evidence
  3. Write content naturally:

    • Use Geoffrey's native writing capabilities
    • Guided by voice profile (not rigid pattern matching)
    • Weave in interview content (examples, data, stories)
    • Match typical length from profile examples
  4. Reference example emails/posts from profile for inspiration

Generation Approach (Hybrid):

  • Write naturally with rich voice context
  • Don't mechanically apply patterns
  • Let voice characteristics inform style, not constrain creativity

Phase 5: Validation & Refinement

Goal: Ensure draft authentically matches your voice

Native LLM Validation (no script needed):

  1. Geoffrey self-validates by comparing draft to voice profile:

    • Read the draft I just generated
    • Read the voice profile (voice_characteristics + examples)
    • Compare tone, structure, vocabulary, formatting
    • Score alignment 0-100
  2. Scoring criteria (weighted):

    • Tone match (20%)
    • Sentence structure - length, complexity (15%)
    • Vocabulary - common/avoided terms (15%)
    • Formatting - bullets, markdown, emphasis (10%)
    • Opening pattern match (10%)
    • Closing pattern match (10%)
    • Argument structure - conclusion placement, evidence use (10%)
    • Stylistic markers - contractions, punctuation, framing (10%)
  3. Identify specific deviations:

    • "Sentences 15% longer than typical (avg 16 words vs typical 14)"
    • "Missing characteristic bullet points (you use them 67% of time)"
    • "Tone slightly more formal than usual"
  4. Scoring thresholds:

    • 85-100: Excellent match, present draft
    • 70-84: Good match with minor deviations, note them
    • <70: Significant deviations, propose refinements

Refinement (if score < 85):

Voice Validation: {score}/100

Issues:
- {Issue 1 with specific evidence}
- {Issue 2 with specific evidence}
- {Issue 3 with specific evidence}

Should I refine to better match your voice?

If user approves refinement:

  • Apply specific fixes identified
  • Re-validate
  • Present refined draft

Checkpoint 4: User accepts, requests refinement, or manually edits


Phase 6: Storage & Versioning

Goal: Save draft to Obsidian with proper versioning

Process:

  1. Determine file path:

    ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/Geoffrey/Writing/{ContentType}/{date}-{slug}.md
    

    Content types:

    • Blog → Geoffrey/Writing/Blog/
    • Email → Geoffrey/Writing/Email/
    • Social → Geoffrey/Writing/Social/
    • Reports → Geoffrey/Writing/Reports/
  2. Generate frontmatter:

    ---
    created: 2025-12-06
    type: blog
    profile: blog_technical
    topic: AI implementation
    status: draft
    version: 1.0
    validation_score: 87
    word_count: 847
    tags: [geoffrey, writing, ai]
    source: geoffrey-writer
    interview_date: 2025-12-06
    ---
    
  3. Save file using Obsidian MCP tools:

    mcp__obsidian-vault__create_vault_file
    
  4. Also return text directly (copy-paste ready)

  5. Offer to open in Obsidian:

    mcp__obsidian-vault__show_file_in_obsidian
    

Versioning:

  • Initial: version: 1.0
  • Refinements: version: 1.1, 1.2
  • Major rewrites: version: 2.0

Output to user:

## Draft Complete

**Validation Score**: 87/100 ✓
**Word Count**: 847
**Profile**: blog_technical

**Saved to**: Geoffrey/Writing/Blog/2025-12-06-ai-implementation.md

[Full draft text here]

Actions:
1. Open in Obsidian
2. Request refinements
3. Mark as final

Voice Learning Process

Initial Setup (Before First Use)

Required: Gather writing samples for each profile you'll use

Step 1: Email Samples (3 accounts)

# PSD work emails
bun scripts/extract-email-samples.js \
  --account psd \
  --date-range "2024-06-01:2025-12-06" \
  --max-samples 100 \
  --output "/tmp/email-samples-psd.json"

# Personal emails
bun scripts/extract-email-samples.js \
  --account kh \
  --date-range "2024-06-01:2025-12-06" \
  --max-samples 50 \
  --output "/tmp/email-samples-kh.json"

# Business/consulting emails
bun scripts/extract-email-samples.js \
  --account hrg \
  --date-range "2024-06-01:2025-12-06" \
  --max-samples 50 \
  --output "/tmp/email-samples-hrg.json"

Step 2: Blog Samples

# Launch Geoffrey Chrome (for personal blog access)
cd ~/non-ic-code/geoffrey/skills/browser-control
./scripts/launch-chrome.sh

# Extract blog posts
cd ~/non-ic-code/geoffrey/skills/writer
bun scripts/extract-blog-samples.js \
  --urls "https://psd401.ai/blog/stanford-ai-tinkery-2025,https://psd401.ai/blog/why-this-website,https://blog.krishagel.com/post1,https://blog.krishagel.com/post2" \
  --output "/tmp/blog-samples.json"

Step 3: Social Media Samples (requires login)

# IMPORTANT: Manually log into LinkedIn and X in Geoffrey Chrome first

# LinkedIn
bun scripts/extract-social-samples.js \
  --platform linkedin \
  --profile-url "https://linkedin.com/in/krishagel" \
  --max-posts 50 \
  --output "/tmp/social-linkedin.json"

# Twitter/X
bun scripts/extract-social-samples.js \
  --platform twitter \
  --profile-url "https://x.com/KrisHagel" \
  --max-posts 50 \
  --output "/tmp/social-twitter.json"

Step 4: Geoffrey Analyzes

Tell Geoffrey:

Analyze my writing samples and create voice profiles.

Email samples: /tmp/email-samples-psd.json, /tmp/email-samples-kh.json, /tmp/email-samples-hrg.json
Blog samples: /tmp/blog-samples.json
Social samples: /tmp/social-linkedin.json, /tmp/social-twitter.json

Geoffrey will:

  1. Read all sample files
  2. Analyze each profile's:
    • Tone and voice
    • Sentence structure patterns
    • Vocabulary (common/avoided terms)
    • Formatting preferences
    • Opening/closing patterns
    • Argument structure
    • Distinctive markers
  3. Select representative examples
  4. Calculate confidence scores
  5. Write to writing-voice.json:
    ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/knowledge/writing-voice.json
    

Estimated time: 30-45 min initial setup


Integration Points

knowledge-manager → Identity Context

When: Phase 4 (Draft Generation)

Purpose: Ensure voice reflects personality (analytical, direct, impact-driven)

How:

cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/identity-core.json

Use:

  • communication_preferences → Tone, style, dislikes
  • decision_framework → Analytical, evidence-based approach
  • telos_summary → Values (equity, excellence, empathy), mission
  • strengths_essence → Input (collector), Significance (impact), Analytical

google-workspace → Email Samples

When: Initial voice creation + quarterly refresh

Scripts: search_messages.js, read_message.js

Process:

  1. Search sent emails
  2. Filter automated, short, quoted
  3. Clean signatures, HTML
  4. Extract plain text + metadata
  5. Save to JSON for Geoffrey to analyze

browser-control → Blog/Social Samples

When: Initial voice creation + ad-hoc updates

Prerequisites: Geoffrey Chrome running with logins

Process:

  1. Navigate to blog/profile URL
  2. Extract article/post content
  3. Handle scrolling/lazy-loading (social)
  4. Parse and clean content
  5. Save to JSON

obsidian-manager → Draft Storage

When: Phase 6 (Storage)

Folder structure:

Geoffrey/Writing/
├── Blog/
├── Email/
├── Social/
└── Reports/

File format: YYYY-MM-DD-{slug}.md with frontmatter


Edge Cases & Handling

Insufficient Samples

Scenario: User requests email, but only 12 samples (confidence 0.62)

Response:

Only 12 email_work samples (0.62 confidence). Target: 50+ for 0.85+ confidence.

Options:
1. Gather ~40 more email samples from recent sent (recommended)
2. Use email_personal as proxy (if similar, confidence: 0.88)
3. Proceed with low confidence (may not fully match your voice)

Note: Voice profiles improve with more samples. I can still write, but authenticity may vary.

Preference?

Voice Drift (Outdated Profile)

Scenario: Profile last updated 18 months ago

Detection: Check last_updated in writing-voice.json

Response:

Your email_work profile is 18 months old (last updated: 2024-06-15).
Writing styles evolve over time.

Recommendation: Refresh with recent samples (past 6 months)

Run:
bun scripts/extract-email-samples.js --account psd --date-range "2024-06-01:2025-12-06" --max-samples 100 --output "/tmp/email-refresh.json"

Then ask me to analyze and update the profile.

Proceed with current profile or refresh first?

Contradictory Samples

Scenario: Email samples vary significantly (45% formal, 35% casual, 20% mixed)

Geoffrey analyzes and responds:

Your email_work voice varies significantly across samples:
- 45% formal (board, superintendent, external)
- 35% casual (staff, peers, project teams)
- 20% mixed

Options:
1. Split into email_work_formal and email_work_casual profiles
2. Choose dominant style (formal) as default
3. Let me dynamically adjust based on recipient (you specify each time)

Preference?

Low Validation Score

Scenario: Draft scores 62/100

Response:

Voice Validation: 62/100 ⚠️

Issues:
- Tone too formal (target: direct, action-oriented)
  Example: "It would be appreciated if you could consider..." vs typical "Please review and confirm."

- Sentences 35% longer (avg 19 words vs typical 14)
  Example: Draft paragraph 2 avg 21 words, your emails avg 14 words.

- Missing bullet points (you use bullets 67% of the time for key points)
  Draft uses prose for 5 key points, you typically bullet them.

Should I refine to better match your voice?

New Content Type

Scenario: User requests "write a press release"

Response:

I don't have a press_release voice profile yet.

Options:
1. Use report_formal profile as starting point (confidence: 0.83)
2. Provide 5-10 past press releases for me to analyze
3. Write without voice matching (generic professional press release style)

Note: If you provide samples, I can create a new press_release profile.

Preference?

Usage Examples

Example 1: Quick Work Email

User: "Write email to my team about next week's leadership meeting"

Geoffrey:

I'll use your email_work profile (confidence: 0.92, 156 samples).

Quick interview (4 questions):

1. Who's the team and what's your relationship?
   → [User: Direct reports - IT leadership team]

2. Purpose? (inform, request, respond, update)
   → [User: Inform and request prep]

3. Key information?
   → [User: Meeting Tuesday 2pm, agenda items: budget, staffing, AI roadmap. Need their input on AI priorities.]

4. Tone?
   → [User: Professional but casual - these are my directs]

[Generates outline] → User approves

[Generates draft, validates (score: 89), presents to user]


Example 2: Blog Post

User: "Write blog post about our AI implementation journey"

Geoffrey:

I'll use your blog_technical profile (confidence: 0.78, 4 samples).

Note: Only 4 blog samples. Recommend 6+ more for 0.85+ confidence.
Proceed or gather more samples first?

→ [User: Proceed]

Standard interview (11 questions):

1. Central message?
   → [User: ...]

2. Why now?
   → [User: ...]

[... continues through 11 questions ...]

[Creates detailed outline] → User approves

[Generates ~850 word draft with staff quotes, chronological flow, reflective close]

[Validates (score: 87), presents draft]

[Saves to Geoffrey/Writing/Blog/2025-12-06-ai-implementation-journey.md]


Example 3: LinkedIn Post

User: "LinkedIn post about Stanford AI Tinkery visit"

Geoffrey:

I'll use your social_linkedin profile (confidence: 0.91, 48 posts).

Quick interview (5 questions):

1. Main point (1-2 sentences)?
   → [User: Visited Stanford's AI Tinkery with district team. Collaborative learning happening everywhere, not just at elite institutions.]

2. Target audience?
   → [User: Ed tech leaders, superintendents]

3. Tone?
   → [User: Inspirational, reflective]

4. Call-to-action?
   → [User: Encourage others to build their own learning networks]

5. Link or visual?
   → [User: No link, maybe photo but I'll add later]

[Generates ~180 word LinkedIn post]

[Validates (score: 92), presents]


Limitations

Known Constraints

  1. Sample Dependency: Voice quality directly tied to sample quantity and quality

    • Low samples (<20) = low accuracy
    • Poor quality samples = poor voice matching
  2. Voice Drift: Styles evolve over time

    • Recommend quarterly refresh (every 3 months)
    • Auto-warn if profile >12 months old
  3. New Contexts: No profile for content types you haven't written before

    • Press releases, technical docs, grant proposals require new samples
    • Can adapt existing profiles but may not match perfectly
  4. Platform Nuances: Social media scraping limitations

    • LinkedIn/X may change selectors
    • Requires manual login
    • May violate ToS (user accepted risk)
  5. Multilingual: Currently English only

    • No Spanish email profile (even though you write Spanish emails)
    • Could add with Spanish samples
  6. Collaborative Writing: Single voice only

    • Can't blend your voice + co-author
    • Future enhancement

Validation & Quality

Success Metrics

Quantitative:

  • Voice alignment: 85+ for established profiles (0.85+ confidence)
  • Sample size: 50+ emails, 10+ blogs, 30+ social per profile
  • User acceptance: >80% drafts accepted with minor/no edits
  • Refinement iterations: <2 average

Qualitative:

  • User feedback: "This sounds like me"
  • Consistent voice across topics within profile
  • Authentic, not mechanical or formulaic

Quality Checklist

Before presenting draft:

  • ✓ Matches tone from voice profile
  • ✓ Sentence structure within 20% of typical length
  • ✓ Uses common vocabulary, avoids avoided terms
  • ✓ Follows formatting preferences (bullets, markdown)
  • ✓ Opening/closing match typical patterns
  • ✓ Argument structure aligned (conclusion placement, evidence use)
  • ✓ Validation score ≥85 (or explained deviations if <85)
  • ✓ Word count within typical range for content type

Future Enhancements (Out of Scope)

  1. Real-time Learning: Auto-analyze new sent emails monthly
  2. A/B Testing: Generate 2 versions, learn from user choices
  3. Collaborative Voice: Blend user + co-author voices
  4. Multi-language: Spanish voice profiles
  5. Performance Tracking: Voice drift detection over time
  6. Audience-Aware: Sub-profiles (email_work_superintendent vs email_work_staff)
  7. Feedback Loop: User rates content, Geoffrey learns from scores

Troubleshooting

"No voice profile found"

Cause: writing-voice.json doesn't exist or profile type missing

Solution:

  1. Check if file exists:
    cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/writing-voice.json
    
  2. If missing: Run initial setup (extract samples + ask Geoffrey to analyze)
  3. If file exists but profile missing: Add samples for that content type

"Low confidence warning"

Cause: Fewer than 20 samples for profile

Solution:

  1. Gather more samples using extraction scripts
  2. Ask Geoffrey to re-analyze with new samples
  3. Or: Proceed with caveat that voice may not fully match

"Geoffrey Chrome not running"

Cause: Social/blog extraction requires Geoffrey Chrome with remote debugging

Solution:

cd ~/non-ic-code/geoffrey/skills/browser-control
./scripts/launch-chrome.sh

"Failed to extract social posts"

Cause: Not logged into LinkedIn/X, or selectors changed

Solution:

  1. Open Geoffrey Chrome manually
  2. Navigate to LinkedIn/X and log in
  3. Verify posts load
  4. Re-run extraction script
  5. If still fails: Platform may have changed selectors (update script)

Notes

  • Progressive Disclosure: Load only the profile needed for current task (not all 6)
  • Identity Alignment: Always cross-reference identity-core.json for personality consistency
  • Checkpoints: 4 user approval points prevent wasted effort
  • Versioning: All drafts saved to Obsidian with version numbers
  • Native Analysis: Geoffrey's LLM capabilities analyze voice - no complex libraries needed

Requirements for Outputs

All Excel files

Zero Formula Errors

  • Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)

Preserve Existing Templates (when updating templates)

  • Study and EXACTLY match existing format, style, and conventions when modifying files
  • Never impose standardized formatting on files with established patterns
  • Existing template conventions ALWAYS override these guidelines

Financial models

Color Coding Standards

Unless otherwise stated by the user or existing template

Industry-Standard Color Conventions
  • Blue text (RGB: 0,0,255): Hardcoded inputs, and numbers users will change for scenarios
  • Black text (RGB: 0,0,0): ALL formulas and calculations
  • Green text (RGB: 0,128,0): Links pulling from other worksheets within same workbook
  • Red text (RGB: 255,0,0): External links to other files
  • Yellow background (RGB: 255,255,0): Key assumptions needing attention or cells that need to be updated

Number Formatting Standards

Required Format Rules
  • Years: Format as text strings (e.g., "2024" not "2,024")
  • Currency: Use $#,##0 format; ALWAYS specify units in headers ("Revenue ($mm)")
  • Zeros: Use number formatting to make all zeros "-", including percentages (e.g., "$#,##0;($#,##0);-")
  • Percentages: Default to 0.0% format (one decimal)
  • Multiples: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)
  • Negative numbers: Use parentheses (123) not minus -123

Formula Construction Rules

Assumptions Placement
  • Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells
  • Use cell references instead of hardcoded values in formulas
  • Example: Use =B5*(1+$B$6) instead of =B5*1.05
Formula Error Prevention
  • Verify all cell references are correct
  • Check for off-by-one errors in ranges
  • Ensure consistent formulas across all projection periods
  • Test with edge cases (zero values, negative numbers)
  • Verify no unintended circular references
Documentation Requirements for Hardcodes
  • Comment or in cells beside (if end of table). Format: "Source: [System/Document], [Date], [Specific Reference], [URL if applicable]"
  • Examples:
    • "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"
    • "Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]"
    • "Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity"
    • "Source: FactSet, 8/20/2025, Consensus Estimates Screen"

XLSX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.

Important Requirements

LibreOffice Required for Formula Recalculation: You can assume LibreOffice is installed for recalculating formula values using the recalc.py script. The script automatically configures LibreOffice on first run

Reading and analyzing data

Data analysis with pandas

For data analysis, visualization, and basic operations, use pandas which provides powerful data manipulation capabilities:

import pandas as pd

# Read Excel
df = pd.read_excel('file.xlsx')  # Default: first sheet
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict

# Analyze
df.head()      # Preview data
df.info()      # Column info
df.describe()  # Statistics

# Write Excel
df.to_excel('output.xlsx', index=False)

Excel File Workflows

CRITICAL: Use Formulas, Not Hardcoded Values

Always use Excel formulas instead of calculating values in Python and hardcoding them. This ensures the spreadsheet remains dynamic and updateable.

❌ WRONG - Hardcoding Calculated Values

# Bad: Calculating in Python and hardcoding result
total = df['Sales'].sum()
sheet['B10'] = total  # Hardcodes 5000

# Bad: Computing growth rate in Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth  # Hardcodes 0.15

# Bad: Python calculation for average
avg = sum(values) / len(values)
sheet['D20'] = avg  # Hardcodes 42.5

✅ CORRECT - Using Excel Formulas

# Good: Let Excel calculate the sum
sheet['B10'] = '=SUM(B2:B9)'

# Good: Growth rate as Excel formula
sheet['C5'] = '=(C4-C2)/C2'

# Good: Average using Excel function
sheet['D20'] = '=AVERAGE(D2:D19)'

This applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.

Common Workflow

  1. Choose tool: pandas for data, openpyxl for formulas/formatting
  2. Create/Load: Create new workbook or load existing file
  3. Modify: Add/edit data, formulas, and formatting
  4. Save: Write to file
  5. Recalculate formulas (MANDATORY IF USING FORMULAS): Use the recalc.py script
    skills/xlsx/recalc.py output.xlsx
    
  6. Verify and fix any errors:
    • The script returns JSON with error details
    • If status is errors_found, check error_summary for specific error types and locations
    • Fix the identified errors and recalculate again
    • Common errors to fix:
      • #REF!: Invalid cell references
      • #DIV/0!: Division by zero
      • #VALUE!: Wrong data type in formula
      • #NAME?: Unrecognized formula name

Creating new Excel files

# Using openpyxl for formulas and formatting
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

# Add data
sheet['A1'] = 'Hello'
sheet['B1'] = 'World'
sheet.append(['Row', 'of', 'data'])

# Add formula
sheet['B2'] = '=SUM(A1:A10)'

# Formatting
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')

# Column width
sheet.column_dimensions['A'].width = 20

wb.save('output.xlsx')

Editing existing Excel files

# Using openpyxl to preserve formulas and formatting
from openpyxl import load_workbook

# Load existing file
wb = load_workbook('existing.xlsx')
sheet = wb.active  # or wb['SheetName'] for specific sheet

# Working with multiple sheets
for sheet_name in wb.sheetnames:
    sheet = wb[sheet_name]
    print(f"Sheet: {sheet_name}")

# Modify cells
sheet['A1'] = 'New Value'
sheet.insert_rows(2)  # Insert row at position 2
sheet.delete_cols(3)  # Delete column 3

# Add new sheet
new_sheet = wb.create_sheet('NewSheet')
new_sheet['A1'] = 'Data'

wb.save('modified.xlsx')

Recalculating formulas

Excel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided recalc.py script to recalculate formulas:

skills/xlsx/recalc.py <excel_file> [timeout_seconds]

Example:

skills/xlsx/recalc.py output.xlsx 30

The script:

  • Automatically sets up LibreOffice macro on first run
  • Recalculates all formulas in all sheets
  • Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)
  • Returns JSON with detailed error locations and counts
  • Works on both Linux and macOS

Formula Verification Checklist

Quick checks to ensure formulas work correctly:

Essential Verification

  • Test 2-3 sample references: Verify they pull correct values before building full model
  • Column mapping: Confirm Excel columns match (e.g., column 64 = BL, not BK)
  • Row offset: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)

Common Pitfalls

  • NaN handling: Check for null values with pd.notna()
  • Far-right columns: FY data often in columns 50+
  • Multiple matches: Search all occurrences, not just first
  • Division by zero: Check denominators before using / in formulas (#DIV/0!)
  • Wrong references: Verify all cell references point to intended cells (#REF!)
  • Cross-sheet references: Use correct format (Sheet1!A1) for linking sheets

Formula Testing Strategy

  • Start small: Test formulas on 2-3 cells before applying broadly
  • Verify dependencies: Check all cells referenced in formulas exist
  • Test edge cases: Include zero, negative, and very large values

Interpreting recalc.py Output

The script returns JSON with error details:

{
  "status": "success",           // or "errors_found"
  "total_errors": 0,              // Total error count
  "total_formulas": 42,           // Number of formulas in file
  "error_summary": {              // Only present if errors found
    "#REF!": {
      "count": 2,
      "locations": ["Sheet1!B5", "Sheet1!C10"]
    }
  }
}

Best Practices

Library Selection

  • pandas: Best for data analysis, bulk operations, and simple data export
  • openpyxl: Best for complex formatting, formulas, and Excel-specific features

Working with openpyxl

  • Cell indices are 1-based (row=1, column=1 refers to cell A1)
  • Use data_only=True to read calculated values: load_workbook('file.xlsx', data_only=True)
  • Warning: If opened with data_only=True and saved, formulas are replaced with values and permanently lost
  • For large files: Use read_only=True for reading or write_only=True for writing
  • Formulas are preserved but not evaluated - use recalc.py to update values

Working with pandas

  • Specify data types to avoid inference issues: pd.read_excel('file.xlsx', dtype={'id': str})
  • For large files, read specific columns: pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])
  • Handle dates properly: pd.read_excel('file.xlsx', parse_dates=['date_column'])

Code Style Guidelines

IMPORTANT: When generating Python code for Excel operations:

  • Write minimal, concise Python code without unnecessary comments
  • Avoid verbose variable names and redundant operations
  • Avoid unnecessary print statements

For Excel files themselves:

  • Add comments to cells with complex formulas or important assumptions
  • Document data sources for hardcoded values
  • Include notes for key calculations and model sections

Commands 1

Preferences Command

Read and display all stored preferences from Geoffrey's knowledge base.

What This Command Does

The /preferences command shows you everything Geoffrey has learned about you, including:

  • All stored preferences organized by category
  • Confidence scores for each preference
  • When each preference was learned
  • How each preference was learned (explicit, pattern, conversation)

Location

Preferences are stored in:

~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/knowledge/preferences.json

How to Use

View all preferences:

/preferences

Shows all preferences across all categories with confidence scores.

View by category:

/preferences travel
/preferences work
/preferences communication

Shows only preferences in the specified category.

What You'll See

Geoffrey's Knowledge Base
Last updated: 2025-11-17 10:30 AM

Travel Preferences:
  Hotels:
    - Primary chain: Marriott
    - Loyalty tier: Platinum Elite
    - Room preferences: High floor, away from elevator
    - Confidence: 1.0 (explicitly stated)
    - Learned from: explicit:2025-11-17

  Airlines:
    - Primary: Alaska Airlines
    - Seat preference: Aisle
    - Time preference: Morning flights
    - Confidence: 0.8 (strong pattern)
    - Learned from: booking:2025-10-15, booking:2025-09-20

Work Preferences:
  Communication:
    - Email tone: Professional but friendly
    - Confidence: 0.6 (moderate pattern)
    - Learned from: conversation:2025-11-10

Total preferences: 8
High confidence (>0.8): 5
Moderate confidence (0.6-0.8): 2
Low confidence (<0.6): 1

Actions You Can Take

After viewing preferences, you can:

  1. Teach Geoffrey something new:

    "I prefer window seats on flights, not aisle"
    
  2. Update existing preferences:

    "Actually, I prefer Hilton over Marriott now"
    
  3. Delete preferences:

    "Forget my airline preferences"
    
  4. Ask questions:

    "Why do you think I prefer morning flights?"
    "How confident are you about my hotel preferences?"
    

File Format

The preferences.json file has this structure:

{
  "version": "1.0",
  "last_updated": "2025-11-17T10:30:00Z",
  "preferences": {
    "travel": {
      "hotels": {
        "primary_chain": "Marriott",
        "loyalty_tier": "Platinum Elite",
        "room_preferences": ["high floor", "away from elevator"],
        "confidence": 1.0,
        "learned_from": ["explicit:2025-11-17"],
        "last_updated": "2025-11-17T10:30:00Z"
      }
    }
  }
}

Privacy & Security

  • Local storage only: Preferences stored in your iCloud, not on any server
  • Syncs across your devices: Via iCloud Drive
  • You control the data: Edit or delete the JSON file directly if needed
  • No analytics: Geoffrey never sends your preferences anywhere

Troubleshooting

If /preferences shows nothing:

  • Check if the knowledge file exists
  • Initialize with: mkdir -p ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge
  • Teach Geoffrey something to create initial file

If file is corrupted:

  • Backup: cp preferences.json preferences.backup.json
  • Fix JSON formatting or reset to empty: {}

If preferences not syncing:

  • Verify iCloud Drive is enabled
  • Check iCloud storage space
  • Wait a few minutes for sync

Implementation Notes

This command should:

  1. Read the preferences.json file
  2. Parse and format for display
  3. Show confidence scores with visual indicators
  4. Group by category
  5. Provide summary statistics
  6. Offer next action suggestions

Sponsors

Details

Marketplace
krishagel/geoffrey
Category
Productivity
Keywords
personal-ai, learning, preferences, assistant, travel, productivity, strategic-planning, omnifocus