
geoffrey
Personal AI infrastructure with learning-enabled assistance for work, travel, and personal tasks
- version
- 0.26.0
- GitHub stars
- 9
Install
/plugin install geoffrey@geoffreyRun it inside Claude Code after adding the marketplace with /plugin marketplace add krishagel/geoffrey.
Contents
Discovered from sourceSkills 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:
| Element | Maps To |
|---|---|
| Text input boxes | short_text (single line) or long_text (multi-line) |
| Dropdowns/select menus | select with choices from visible options |
| Checkboxes/multi-select | multi_select |
| File upload areas | file_upload |
| Field labels | label property |
| Placeholder text | options.placeholder |
| Visible instructions | system_context or prompt content |
| Step numbers/tabs | Multiple 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:
-
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
-
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") -
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 For | Maps 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:
| Decision | Default |
|---|---|
| Model | gpt-4o (complex tasks), gpt-4o-mini (simple Q&A) |
| Field type for text | long_text with 6 rows |
| Execution | Sequential (single prompt unless steps mentioned) |
| Timeouts | null (system default) |
| Required fields | true 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 screenshot | Extract them exactly |
| Field matches a Common Field Library | Use the library options |
| Field is domain-specific (e.g., "Department", "Building", "Program") | ASK the user for the list |
| Unclear what options should be | ASK 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:
| Decision | Options |
|---|---|
| Execution pattern | Sequential (default) / Parallel / Multi-level |
| Model selection | gpt-4o (complex) / gpt-4o-mini (simple) / claude-3-5-sonnet |
| Input fields | short_text, long_text, select, multi_select, file_upload |
| Timeouts | Default 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:
-
versionis"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 -
positionvalues are sequential starting from 0 - All
${variables}match input field names,prompt_N_output, or slugified prompt names - CRITICAL: Every
selectandmulti_selectfield hasoptions.choicesarray 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 Case | Model |
|---|---|
| Complex analysis | gpt-4o |
| Simple tasks | gpt-4o-mini |
| Long context | claude-3-5-sonnet |
| Fast responses | gemini-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:
| Pattern | Field Type |
|---|---|
| "Select...", "Choose...", dropdown arrow | select |
| "Pick one", "Which...", finite list | select |
| "Check all that apply", multiple checkboxes | multi_select |
| Grade level, subject, state, language, format | select (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 Type | Assumption Strategy |
|---|---|
| Grade/Subject/State | Use Common Field Libraries |
| Standards | Use domain-level dropdowns (ELA, Math, Science domains) + text for specific codes |
| Roles/Positions | Use Educator Role library |
| Time/Duration | Use Lesson Duration or Grading Period library |
| Assessment | Use Assessment Type library |
| Instructional approach | Use Instructional Model library |
| Student groups | Use Student Population library |
| Cognitive rigor | Use 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:
- Terminal: Summary displayed immediately
- 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_absencesclassified_filled = all_filled - cert_filledclassified_unfilled = all_unfilled - cert_unfilledclassified_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:
- Get the output from
get_recent_bill_activity.js - WebFetch each bill URL (batch 5-6 in parallel for speed)
- Extract latest action date from each bill page
- Filter to bills where latest_action_date >= lookback_start
- Prioritize bills with FISCAL impact type - these get detailed treatment
- 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):
K-12 school district finance budget funding news past 24 hours [MONTH YEAR]Washington state education funding levy bond news [MONTH YEAR]WASBO Washington school business officials news [MONTH YEAR]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):
-
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."
-
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"
-
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
-
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
-
Finance/WASBO/OSPI News (~200 words)
- 2-3 articles with financial relevance
- Why each matters for PSD's budget or operations
-
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 ascid: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/Tool | Required For | Fallback |
|---|---|---|
| redrover-manager | Absence data | Skip absence sections |
| freshservice-manager | Department tickets | Skip ticket sections |
| legislative-tracker | Fiscal legislation | Skip legislative section |
| local-tts | Audio podcast | Email without attachment |
| image-gen | Absence infographic | Email without inline image |
| google-workspace | Email delivery | Display summary in terminal only |
| WebSearch | Weather, finance news | Skip 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
| Aspect | Clawdbot | Geoffrey |
|---|---|---|
| Scope | Multi-channel messaging hub (WhatsApp, Discord, etc.) | Claude Code plugin for personal AI |
| Skills | 60+ (CLI wrappers, platform integrations) | 26 (specialized workflows) |
| Hooks | Event-driven TypeScript handlers | hooks.json configuration |
| Memory | Hybrid vector + BM25 with SQLite-vec | Obsidian vault + knowledge-manager |
| Releases | Weekly (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 philosophyCLAUDE.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 guidelinesREADME.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 declarationsrequires.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:
| Area | Description | Geoffrey Equivalent |
|---|---|---|
| skills/ | 60+ modular skills | skills/ (26) |
| Hooks | Event-driven TypeScript | hooks.json |
| Extensions | Plugin architecture | (none currently) |
| Memory | Hybrid vector + BM25 | Obsidian vault |
| Channels | WhatsApp, Discord, etc. | N/A (Claude Code only) |
Key Differences from PAI Monitor
| Aspect | PAI | Clawdbot |
|---|---|---|
| Update frequency | Less frequent | Weekly releases |
| Architecture | Packs + CLI | Daemon + extensions |
| Skill count | 24 packs | 60+ skills |
| Memory model | File-based | Vector DB (SQLite-vec) |
| Target | Personal AI | Messaging hub |
Execution Notes
- Start with Phase 1 - Always fetch fresh Clawdbot data, don't rely on cached knowledge
- Be thorough in Phase 2 - Accurate self-assessment is critical for gap analysis
- Prioritize in Phase 3 - Not all gaps need filling; focus on high-value opportunities for Geoffrey's use case
- Actionable Phase 4 - Every recommendation should have clear next steps
- 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 contentsword/comments.xml- Comments referenced in document.xmlword/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
- 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. - 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)
- 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
- 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. - Unpack the document:
skills/docx/ooxml/scripts/unpack.py <office_file> <output_directory> - Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
- 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
-
Get markdown representation: Convert document to markdown with tracked changes preserved:
pandoc --track-changes=all path-to-file.docx -o current.md -
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"
-
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.
- MANDATORY - READ ENTIRE FILE: Read
-
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.xmlto verify how text is split across<w:r>elements.b. Create and run script: Use
get_nodeto find nodes, implement changes, thendoc.save(). See "Document Library" section in ooxml.md for patterns.Note: Always grep
word/document.xmlimmediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run. -
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 -
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
- Convert final document to markdown:
Converting Documents to Images
To visually analyze Word documents, convert them to images using a two-step process:
-
Convert DOCX to PDF:
soffice --headless --convert-to pdf document.docx -
Convert PDF pages to JPEG images:
pdftoppm -jpeg -r 150 document.pdf pageThis 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-pngfor PNG if preferred)-f N: First page to convert (e.g.,-f 2starts from page 2)-l N: Last page to convert (e.g.,-l 5stops 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:
- Export & Analyze - Drafts exports inbox → Geoffrey analyzes → presents suggestions
- 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 processdestination- "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 Type | Folder | Frontmatter |
|---|---|---|
| Meeting notes | Meetings/ | date, attendees, topics |
| Ideas/brainstorms | Geoffrey/Inbox/ | tags, created |
| Research | Reference/ | source, tags, related |
| Journal | Journal/ | date |
| General notes | Geoffrey/Inbox/ | tags, created |
Frontmatter template:
---
created: {{date}}
source: drafts
tags: [from-drafts]
related: []
---
Main Workflow: Triage Drafts
Phase 1: Export & Analyze
-
Trigger export:
open "drafts://x-callback-url/runAction?action=Geoffrey%20Export%20Inbox" -
Wait for export file (2-3 seconds)
-
Read exported JSON:
cat ~/Library/Mobile\ Documents/iCloud~com~agiletortoise~Drafts5/Documents/geoffrey-export.json -
Analyze each draft using content signals above
-
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
-
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" -
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
- Open Drafts
- Go to Actions → Manage Actions
- Import from
actions/geoffrey-export-inbox.draftsAction - Import from
actions/geoffrey-process-draft.draftsAction
Option B: Create manually
- Open Drafts
- Create new action "Geoffrey Export Inbox"
- Add Script step with code from
actions/geoffrey-export-inbox.js - 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 OmniFocusnote- Force route to Obsidianarchive- Keep in Drafts archivedelete- 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 Type | Destination | Obsidian Folder | OmniFocus Details |
|---|---|---|---|
| Meeting notes | Obsidian | Meetings/2025/ | - |
| Conference notes | Obsidian | Meetings/2025/ | - |
| Development roadmap | Obsidian | Work/[Project]/Roadmap.md | Format as checklist |
| API keys/credentials | Delete | - | Security risk |
| Error logs/JSON junk | Delete | - | Cruft |
| Random passwords | Delete | - | Cruft |
| Contact info | Contacts app | - | Also create follow-up task |
| Book recommendations | OmniFocus | - | Tags: Reading |
| Gift ideas | OmniFocus | - | Tags: Chores, Shopping |
| Action items from meetings | OmniFocus | - | Tags: Follow Up |
| Reference links (AI, UDL) | Obsidian | Reference/ | - |
| Personal project ideas | OmniFocus | - | Tags: Coding |
| Presentation schedules | Obsidian | Work/Presentations/ | Future dates → tasks |
| Survey links | OmniFocus | - | 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 notesWork/AI-Studio/- AI Studio development docsWork/Jocular-Kangaroo/- Jocular Kangaroo projectWork/Presentations/- Presentation archivesGeoffrey/- Geoffrey roadmap and ideasReference/- 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:
| Argument | Description | Default |
|---|---|---|
--text | Text content to convert | - |
--file | Path to text file | - |
--voice | Voice name or ID | Rachel |
--model | Model ID | eleven_multilingual_v2 |
--output | Output 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:
| Argument | Description | Default |
|---|---|---|
--all | Show all voices (not just premade) | false |
--json | Output as JSON | false |
Curated Voices
Six voices selected for variety (see references/voices.md for details):
| Voice | Style | Best For |
|---|---|---|
| Rachel | Calm, clear | Narration, podcasts (default) |
| Bella | Soft, gentle | Storytelling, meditation |
| Elli | Young, expressive | Casual content, tutorials |
| Josh | Deep, authoritative | News, professional content |
| Adam | Middle-aged, clear | Business, documentaries |
| Antoni | Warm, versatile | General purpose |
Use list_voices.py to discover additional voices.
Models
| Model | ID | Best For | Char Limit |
|---|---|---|---|
| Multilingual v2 | eleven_multilingual_v2 | Long-form (default) | 10,000 |
| Flash v2.5 | eleven_flash_v2_5 | Quick, real-time | 40,000 |
| Turbo v2.5 | eleven_turbo_v2_5 | Balanced | 40,000 |
| Eleven v3 | eleven_v3 | Maximum expression | 3,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
| ID | Name |
|---|---|
| 2 | Technology (primary) |
| 3 | Employee Support Services |
| 4 | Business Services |
| 5 | Teaching & Learning |
| 6 | Maintenance |
| 8 | Investigations |
| 9 | Transportation |
| 10 | Safety & Security |
| 11 | Communications |
| 13 | Software 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 week2= 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"
- Find Jodi's agent ID:
bun list_agents.js jodi→ 6000542935 - Add note:
bun add_note.js 151501 '{"body": "...", "notify_emails": ["miloj@psd401.net"]}'
"Assign ticket to Mark"
- Find Mark's ID:
bun list_agents.js mark - Update ticket:
bun update_ticket.js <id> '{"responder_id": <mark_id>}'
"What approvals do I have?"
- Get approvals:
bun get_approvals.js - 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
| Code | Status |
|---|---|
| 2 | Open |
| 3 | Pending |
| 4 | Resolved |
| 5 | Closed |
Priority Codes
| Code | Priority |
|---|---|
| 1 | Low |
| 2 | Medium |
| 3 | High |
| 4 | Urgent |
Google Workspace Skill
Overview
Unified Google Workspace integration for managing email, calendar, files, and communication across three accounts:
| Alias | Purpose | |
|---|---|---|
psd | Work | PSD district email |
kh | Personal | Personal Gmail |
hrg | Business | Consulting & 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
| Script | Description | Example |
|---|---|---|
list_messages.js | List inbox, unread, by label | "show unread psd emails" |
read_message.js | Get full message content | "read that email" |
send_message.js | Compose and send | "send email to John about..." |
send_with_attachment.js | Send with file attachment | "email report with PDF attached" |
search_messages.js | Search with Gmail operators | "find emails from Sarah last week" |
get_unread_summary.js | Unread count + top messages | "how many unread emails?" |
Calendar
| Script | Description | Example |
|---|---|---|
list_events.js | Get upcoming events | "what's on my calendar today" |
create_event.js | Schedule new events | "schedule meeting tomorrow at 2pm" |
update_event.js | Modify existing events | "move that meeting to 3pm" |
search_events.js | Find by criteria | "find meetings with Mike" |
Drive
| Script | Description | Example |
|---|---|---|
list_files.js | Browse/search files | "find budget spreadsheet" |
read_file.js | Get file content | "show me that document" |
create_file.js | Create new docs/sheets | "create a new spreadsheet" |
upload_file.js | Upload local file | "upload this to drive" |
Tasks
| Script | Description | Example |
|---|---|---|
list_tasks.js | Get task lists | "show my google tasks" |
create_task.js | Add new task | "add task to google tasks" |
complete_task.js | Mark done | "complete that task" |
Chat
| Script | Description | Example |
|---|---|---|
list_spaces.js | Get available spaces | "list chat spaces" |
send_message.js | Post to space | "send message to team chat" |
read_messages.js | Get 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:
- Complete Google Cloud Console setup (see
auth/GOOGLE_CLOUD_SETUP.md) - Add credentials to
~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env - Authenticate all three accounts
- 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:- senderto:- recipientsubject:- subject linehas:attachment- with attachmentsafter:/before:- date rangeis:unread- unread onlylabel:- 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:
- Extract narrative - Understand the complete story/concept
- Derive visual concept - Single metaphor with 2-3 physical objects
- Apply aesthetic - Define style, colors, mood
- Construct prompt - Build detailed generation instructions
- Generate - Execute via script
- 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:
- Generate image with script
- Return file path to user
- 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
| Size | Cost per Image |
|---|---|
| 1K | Free 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:
-
Read current preferences:
cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/preferences.json -
Parse and validate the user's statement
-
Update the JSON with new preference:
- Add to appropriate category
- Set confidence based on how it was learned
- Record the source
- Update timestamp
-
Write back to the file
-
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":
-
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
-
Extract key data:
- Point/mile balances
- Credit usage status
- Expiring benefits with dates
- Free night certificates
-
Save to status file in iCloud
-
Generate alerts for items expiring within 30 days
-
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:
| Committee | Chamber | Query |
|---|---|---|
| Education | House | All bills - no filtering |
| Early Learning & K-12 Education | Senate | All bills - no filtering |
Tier 2: Indirect Impact Bills (Candidates)
Query these committees and filter via WebFetch:
| Committee | Chamber |
|---|---|
| Appropriations | House |
| Capital Budget | House |
| Labor & Workplace Standards | House |
| Ways & Means | Senate |
| Labor & Commerce | Senate |
| State Government, Tribal Affairs & Elections | Senate |
Workflow: The SOAP API returns only bill IDs. Geoffrey must:
- Get all bill IDs from Tier 2 committees (~700 bills)
- WebFetch each bill's summary page to get the title/description
- Filter for education keywords in the description
- 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:
- WebFetch the bill summary page
- Check if title/description contains education keywords
- 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
| Level | Symbol | Criteria |
|---|---|---|
| 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
| Category | Keywords | Description |
|---|---|---|
| FISCAL | levy, bond, funding, appropriation | Funding formulas, levies, bonds, appropriations |
| OPERATIONAL | procurement, transportation, facilities | Day-to-day operations, contracts, services |
| WORKFORCE | staff, salary, certification, benefits | Staffing, compensation, certification requirements |
| GOVERNANCE | reporting, accountability, board | Compliance, reporting, board authority |
Fiscal Impact Indicators
| Indicator | Symbol | Meaning |
|---|---|---|
| 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/
| Service | Method | Purpose |
|---|---|---|
| CommitteeService | GetActiveHouseCommittees | List House committee names |
| CommitteeService | GetActiveSenateCommittees | List Senate committee names |
| CommitteeActionService | GetInCommittee | Bills currently in committee |
| CommitteeActionService | GetCommitteeReferralsByCommittee | All 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
| Scenario | Response |
|---|---|
| SOAP timeout/error | Fall back to WebSearch (Tier 3) |
| Committee not found | Check exact name via get_committees.js |
| No bills in committee | Normal - committee may not have active bills |
| Bill page unavailable | Skip 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
| Parameter | Required | Default | Description |
|---|---|---|---|
--text | One of text/file | - | Text to convert |
--file | One of text/file | - | Path to text file |
--voice | No | af_heart | Voice preset |
--output | Yes | - | Output file path (.mp3, .wav) |
--model | No | Kokoro-82M-bf16 | Model to use |
--list-voices | No | - | Show available voices |
Voice Presets
American English Female (prefix: af_)
af_heart- Warm, friendly (default)af_bella- Soft, calmaf_nova- Clear, professionalaf_river- Clear, confidentaf_sarah- Soft, expressive
American English Male (prefix: am_)
am_adam- Clear, professionalam_echo- Deep, smootham_liam- Articulate, conversationalam_michael- Soft, measured
British English (prefix: bf_, bm_)
bf_emma- Clear, refined femalebm_daniel- Clear, professional malebm_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
| Hardware | Speed | Notes |
|---|---|---|
| M3 Pro 36GB | ~3-4x realtime | First run slower (model loading) |
| M1/M2 Mac Mini 8GB | ~1.5x realtime | Works well for briefings |
| M1/M2 Mac Mini 16GB | ~2x realtime | Comfortable 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
-
MUST use
--withflags - Do not use PEP 723 inline deps. mlx-audio requires uv's cached environment. -
First run is slower - Model downloads ~200MB and espeak dependencies initialize.
-
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:
- Terminal: Summary displayed immediately
- Obsidian: Full briefing saved to daily note
- 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):
- Use WebFetch to read the full article
- 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):
- Use WebFetch to read the full article
- 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):
- Use WebFetch to read the full article
- 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):
- Use WebFetch to read the full article
- 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
senderfield 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:
- Examine the raw JSON output from the script
- List the exact
sendervalues returned - 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:
- Name: Who posted (use EXACTLY the name from
senderfield) - Location(s): Where they worked (WFH, DCRC, school sites)
- Key accomplishments: Specific tasks completed (not just "tickets")
- Notable items: Interesting problems solved, projects worked on
- 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
senderfield 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:
- Examine the raw JSON output from the script
- List the exact
sendervalues returned - 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
byAgentsection 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:
- Examine the raw JSON output from
get_daily_summary.js - List the exact agent names from
byAgentfield - 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:
- Get the output from
get_recent_bill_activity.js - WebFetch each bill URL (batch 5-6 in parallel for speed)
- Extract latest action date from each bill page
- Filter to bills where latest_action_date >= lookback_start
- Apply priority framework (HIGH/MEDIUM/LOW based on district impact)
- 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=2025https://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):
-
Opening (~100 words)
- Day, date, weather summary
- Quick preview of key items
-
Calendar & Schedule (~150 words)
- Today's events with context
- Highlight key meetings/events
- Note any conflicts or prep needed
-
Tasks & Priorities (~150 words)
- Overdue items that need attention
- Due today items
- Flagged priorities
-
Tickets & Service Desk (~150 words)
- Open Technology tickets
- Software Development tickets
- Pending approvals
-
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
senderfields - Use ONLY ticket counts from the
get_daily_summary.jsoutput - If script returned no messages, say "No EOD messages were posted"
- NEVER invent names, locations, or accomplishments
-
EdTech News (~200 words)
- 2-3 articles with synopses
- Why each matters for K-12
-
AI News (~200 words)
- 2-3 articles with synopses
- Industry impact and relevance
-
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
-
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
-
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:

4.3 Save Briefing File
Use Obsidian MCP tools:
-
Check if daily note exists:
mcp__obsidian-vault__get_vault_file filename: "Geoffrey/Daily Briefings/[YYYY-MM-DD].md" -
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 ascid: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/Tool | Required For | Fallback |
|---|---|---|
| google-workspace | Calendar, email, team EOD | Skip sections |
| omnifocus-manager | Tasks | Skip section |
| freshservice-manager | Tickets, approvals, team stats | Skip section |
| local-tts | Audio podcast | Text-only briefing |
| obsidian-vault (MCP) | Save briefing | Display only |
| WebSearch | News, weather | Skip 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 rulesprompts/system_prompts.yaml- Per-model system promptsprompts/peer_review.md- Peer review templateprompts/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 Type | Folder | Naming Pattern |
|---|---|---|
| Research results | Geoffrey/Research/ | YYYY-MM-DD-topic.md |
| Reports | Geoffrey/Reports/{org}/{topic}/ | Descriptive name with date |
| Images/Infographics | Same as parent report | Descriptive Name YYYY-MM-DD.png |
| Meeting notes | Meetings/ | Topic - YYYY-MM-DD.md |
| Daily summaries | Geoffrey/Daily-Logs/ | YYYY-MM-DD.md |
| Learnings | Geoffrey/Learnings/ | topic-slug.md |
| Decisions | Geoffrey/Decisions/ | YYYY-MM-DD-decision.md |
| Person updates | People/ | Existing file name |
Naming Rules:
- All images/infographics MUST include date in filename
- Format:
Descriptive Name YYYY-MM-DD.pngorDescriptive Name YYYY-MM-DD to YYYY-MM-DD.pngfor 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:
- Search before creating: Find related notes first
- Use wiki-links:
[[Note Title]]format - Add to frontmatter: List in
related:field - 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
- Search before creating: Always check for existing content
- Link generously: Create connections between notes
- Use consistent tags: Match existing tag patterns
- Keep notes atomic: One idea per note in Learnings
- Include sources: Always cite Readwise/Snipd sources
- 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
| Pitfall | Why It Happens | Solution |
|---|---|---|
| Projects created at root instead of in folder | JXA parentFolder property doesn't work externally | Use AppleScript with tell folder blocks |
| Duplicate empty folders | Script creates folder but projects fail to nest | Always verify count of projects of folder after creation |
| "Can't convert types" errors | JXA type mismatch between app objects and JavaScript | Use AppleScript for complex operations |
| Projects appear created but aren't | Script reports success but verification shows 0 projects | Always verify after creation, never trust script output alone |
| Can't delete folders via script | Folders don't support deletion commands | Manual 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:
- STOP - Don't create more until you understand the problem
- VERIFY - Check actual state:
projects of folder "X" - CLEAN UP - Drop wrong projects:
mark dropped proj - NOTE - Empty folders must be manually deleted in UI
- FIX - Use correct method (AppleScript for folders)
- 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 tasksapp.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 projcommand - 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:
- Generate AppleScript string with folder + projects + tasks structure
- Write to temp file:
/tmp/create_projects_TIMESTAMP.applescript - Execute:
osascript /tmp/create_projects_TIMESTAMP.applescript - Verify: Check
count of projects of folder "Folder Name"returns expected count - 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:
-
Check for existing folders:
tell application "OmniFocus" tell default document set folderNames to name of every folder return folderNames end tell end tell -
Verify folder doesn't already exist to avoid duplicates
-
Plan the complete structure - folder name, all project names, all tasks
During Creation
CRITICAL RULES:
- Use AppleScript, NOT JXA for external scripts creating projects in folders
- Create folder FIRST using
make new folder - Use
tell folderblock for all project creation - Nest
tell projectblocks 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:
- Drop projects:
mark dropped projfor each wrong project - Empty folders cannot be deleted via script - must delete manually in OmniFocus UI
- 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 Type | Project | Default Due |
|---|---|---|
| Discussions with people | Meetings | 7 days |
| Phone calls | Meetings | 7 days |
| CoSN-related | CoSN Work | 7 days |
| Digital Promise work | Digital Promise | 7 days |
| AI/automation projects | AI Studio | 7 days |
| Coding/development | Coding Projects | 7 days |
| Research/learning | Research for Future Plans | 7 days |
| SOP/process development | Standard Operating Procedures | 14 days |
| Form/procedure updates | Department Procedures | 7 days |
| District reimbursements | Purchasing & Acquisitions | 7 days |
| Travel approvals | (appropriate project) | 14 days |
| Data governance | Data Governance | 14 days |
| Tech support issues | → Freshservice ticket | N/A |
By Task Type → Tags
| Task Type | Tags |
|---|---|
| Discussion with person | [Person name], Follow Up |
| Phone call | Phone, Follow Up |
| Research tasks | Research |
| AI-assistable tasks | Geoffrey |
| Focus time needed | Full Focus |
| Admin/organizational | Organization |
| 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
-
Parse user request for: task name, person (if any), context clues
-
Apply routing rules above to determine:
- Project - based on task type
- Tags - person + communication method + activity type
- Due date - based on task type timing
-
If tag doesn't exist, create it with
create_tag.js -
Run
add_task.jswith parameters -
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
-
Get inbox tasks:
osascript -l JavaScript ./scripts/get_inbox.jsThis returns only remaining tasks (no project, not completed, not dropped, not deferred)
-
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
-
Ask clarifying questions:
- Who is [person/acronym]?
- Which project for [ambiguous task]?
- Should this be skipped (needs email context)?
-
Batch update confirmed tasks:
osascript -l JavaScript ./scripts/update_task.js '{"name":"...", "project":"...", "tags":[...], "dueDate":"..."}' -
Create missing tags/projects as needed:
osascript -l JavaScript ./scripts/create_tag.js '{"name":"PersonName", "parent":"ESC"}' -
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
- Find tasks that are:
- Overdue
- Stale (no activity)
- Missing tags
- In wrong project
- 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 philosophyCLAUDE.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 guidelinesREADME.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:
| Area | Description | Geoffrey Equivalent |
|---|---|---|
| Packs/ | 24+ modular capability packages | skills/ |
| Releases/ | Full system snapshots | plugin versions |
| Hook System | 14+ event types | hooks.json |
| Memory System | Knowledge persistence | Obsidian vault |
| Algorithm System | ISC tracking, metrics | compound learnings |
| Validation | .pai-protected.json | (none currently) |
Execution Notes
- Start with Phase 1 - Always fetch fresh PAI data, don't rely on cached knowledge
- Be thorough in Phase 2 - Accurate self-assessment is critical for gap analysis
- Prioritize in Phase 3 - Not all gaps need filling; focus on high-value opportunities
- 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
| Flag | Description |
|---|---|
--no-llm | Skip LLM processing (faster, images become [Image] placeholders) |
--force-ocr | Force 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-llmflag 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
| Task | Best Tool | Command/Code |
|---|---|---|
| Merge PDFs | pypdf | writer.add_page(page) |
| Split PDFs | pypdf | One page per file |
| Extract text | pdfplumber | page.extract_text() |
| Extract tables | pdfplumber | page.extract_tables() |
| Create PDFs | reportlab | Canvas or Platypus |
| Command line merge | qpdf | qpdf --empty --pages ... |
| OCR scanned PDFs | pytesseract | Convert to image first |
| Fill PDF forms | pdf-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-managerskill 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:
- CIO Role (day job - Technology, Communications, Safety/Security)
- Consulting/Speaking (reputation building, CoSN board, conferences)
- Product Development (AI products: voice app, survey tool)
- Real Estate Investing (portfolio management)
- 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:
-
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)
-
Asks: "Which domain(s) do you want to review?" (allow multi-select for first run)
-
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:
- "What requests have you said no to—or wish you had?"
- "What did you consider but decide against?"
- "If someone proposed adding [new initiative], what would you tell them?"
- "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:
- Curious: "Say more?" / "What would that look like?"
- Gentle push: "Help me see this concretely. If I walked into your office in December [next year], what would I notice?"
- Direct challenge: "This is staying abstract. Let's get specific—what's one concrete outcome?"
- 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:
-
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")
-
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?"
-
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
-
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:
- 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:
-
Display Complete Annual Review
- Use
templates/annual-review-template.mdformat - Show full markdown output for review
- Use
-
Get User Approval
- "Does this capture your strategic plan for [year]?"
- "What would you adjust?"
- Iterate until confirmed
-
Save to Obsidian
- Run
scripts/generate_annual_review.py - Save to
Personal_Notes/Reviews/Annual/{YEAR}-Annual-Review.md
- Run
-
Ask about OmniFocus
- "Create OmniFocus projects from your Priority Goals now or later?"
- If now: Run
scripts/sync_to_omnifocus.js
-
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
- Read current User Guide:
-
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:
- Run
scripts/generate_quarterly_review.py - Save to
Personal_Notes/Reviews/Quarterly/{YEAR}-Q{N}-Review.md - Update annual review frontmatter with link to quarterly review
- 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 referencesppt/slides/slide{N}.xml- Individual slide contents (slide1.xml, slide2.xml, etc.)ppt/notesSlides/notesSlide{N}.xml- Speaker notes for each slideppt/comments/modernComment_*.xml- Comments for specific slidesppt/slideLayouts/- Layout templates for slidesppt/slideMasters/- Master slide templatesppt/theme/- Theme and styling informationppt/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:
- Read theme file: Check
ppt/theme/theme1.xmlfor colors (<a:clrScheme>) and fonts (<a:fontScheme>) - Sample slide content: Examine
ppt/slides/slide1.xmlfor actual font usage (<a:rPr>) and colors - 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:
- Consider the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
- Check for branding: If the user mentions a company/organization, consider their brand colors and identity
- Match palette to content: Select colors that reflect the subject
- 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):
- Classic Blue: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
- Teal & Coral: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
- Bold Red: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
- Warm Blush: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
- Burgundy Luxury: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
- Deep Purple & Emerald: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
- Cream & Forest Green: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
- Pink & Purple: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
- Lime & Plum: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
- Black & Gold: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
- Sage & Terracotta: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
- Charcoal & Red: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
- Vibrant Orange: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
- Forest Green: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
- Retro Rainbow: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
- Vintage Earthy: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
- Coastal Rose: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
- 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
- MANDATORY - READ ENTIRE FILE: Read
html2pptx.mdcompletely 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. - 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
- Use
- Create and run a JavaScript file using the
html2pptx.jslibrary 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()
- Use the
- 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
- Create thumbnail grid:
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
- 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. - Unpack the presentation:
skills/pptx/ooxml/scripts/unpack.py <office_file> <output_dir> - Edit the XML files (primarily
ppt/slides/slide{N}.xmland related files) - CRITICAL: Validate immediately after each edit and fix any validation errors before proceeding:
skills/pptx/ooxml/scripts/validate.py <dir> --original <file> - 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
-
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
- Extract text:
-
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.mdcontaining:# 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
-
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.mdwith 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) ]
-
Duplicate, reorder, and delete slides using
rearrange.py:- Use the
scripts/rearrange.pyscript 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
- Use the
-
Extract ALL text using the
inventory.pyscript:-
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_sizein 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,levelis always included (even if 0) - Spacing:
space_before,space_after, andline_spacingin points (only included when set) - Colors:
colorfor RGB (e.g., "FF0000"),theme_colorfor theme colors (e.g., "DARK_1") - Properties: Only non-default values are included in the output
-
-
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
alignmentproperty 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
- Headers/titles should typically have
- 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
-
Apply replacements using the
replace.pyscriptpython scripts/replace.py working.pptx replacement-text.json output.pptxThe 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 inventoryERROR: 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(orthumbnails-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)
- Note: The output prefix should include the path if you want output in a specific directory (e.g.,
- 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:
-
Convert PPTX to PDF:
soffice --headless --convert-to pdf template.pptx -
Convert PDF pages to JPEG images:
pdftoppm -jpeg -r 150 template.pdf slideThis 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-pngfor PNG if preferred)-f N: First page to convert (e.g.,-f 2starts from page 2)-l N: Last page to convert (e.g.,-l 5stops 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:
- Generate approved images in parallel using image-gen skill
- Build slides using selected adapter (PPTX/Google Slides/Canva)
- Apply design rules automatically:
- 30pt+ fonts minimum
- <6 words per slide (Godin standard)
- High contrast (4.5:1 minimum)
- No bullet points
- No paragraphs
- Run validation scoring (0-100 scale)
- 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
- Title Slide - Minimal text, strong visual, sets tone
- One Big Idea - Single word/number/image, max 6 words
- Visual + Caption - Large high-quality image, short caption
- Data Visualization - Charts following Tufte principles (maximize data-ink ratio)
- Timeline/Process - Linear flow, minimal text per step
- 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:
- Extract narrative from slide content
- Choose visual concept/metaphor
- Apply aesthetic (brand colors, presentation style)
- Construct detailed prompt
- Execute generation
- 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 generationpptx- PowerPoint creation (Phase 1)google-workspace- Google Slides (Phase 2)psd-brand-guidelines- Brand colors/logosresearch- Content developmentobsidian-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 practicesprinciples/validation-rules.md- Quality scoring systemprinciples/slide-patterns.md- Template libraryprinciples/story-frameworks.md- Narrative structures
Scripts and adapters:
scripts/analyze-context.js- Type detectionadapters/pptx-adapter.js- PowerPoint outputadapters/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.
| School | Mascot | Abbreviation | Official Site |
|---|---|---|---|
| Gig Harbor High School | Tides | GHHS | tidesathletics.com |
| Peninsula High School | Seahawks | PHS | peninsulaathletics.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:
| Parameter | Default | Examples |
|---|---|---|
| Date range | Next 7 days | "today", "this week", "next two weeks", "March schedule" |
| School filter | Both | "GHHS only", "Peninsula games", "Tides baseball" |
| Sport filter | All in-season | "baseball", "soccer", "track" |
2. Determine Active Season
Only fetch sports currently in season. Overlap periods check both seasons.
| Season | Months | Sports |
|---|---|---|
| Fall | Sep–Nov | Football, Volleyball, Cross Country, Girls Swimming, Water Polo, Girls Soccer (Fall) |
| Winter | Dec–Feb | Basketball, Boys Swimming, Wrestling, Bowling, Flag Football |
| Spring | Mar–Jun | Baseball, 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:
- Use web search to visit the MaxPreps schedule page
- Extract events within the requested date range
- For each event, capture: date, time, sport/level, opponent, home/away, link
- 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:
- Use logo files from
assets/directory - Use colors from
brand-config.json - Use
brand.pyutilities 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.
- Font: Josefin Sans Bold
- Source: https://fonts.google.com/specimen/Josefin+Sans
- Fallback: Arial, sans-serif
Body Text: Josefin Slab
Perfect pairing to Josefin Sans, highly legible at smaller sizes due to slab serif and typewriter-style attributes.
- Font: Josefin Slab
- Source: https://fonts.google.com/specimen/Josefin+Slab
- Fallback: Georgia, serif
Color Palette
Logo Colors (Primary)
| Name | Hex | RGB | Usage |
|---|---|---|---|
| Sea Glass | #6CA18A | rgb(108, 161, 138) | Primary green, landscape elements |
| Pacific | #25424C | rgb(37, 66, 76) | Primary dark blue, text, headers |
| Driftwood | #D7CDBE | rgb(215, 205, 190) | Neutral tan, backgrounds |
Supporting Brand Colors
| Name | Hex | RGB | Usage |
|---|---|---|---|
| Cedar | #466857 | rgb(70, 104, 87) | Dark green accent |
| Whulge | #346780 | rgb(52, 103, 128) | Medium blue (Coast Salish word for sound of waves) |
| Sea Foam | #EEEBE4 | rgb(238, 235, 228) | Light background |
| Meadow | #5D9068 | rgb(93, 144, 104) | Green accent |
| Ocean | #7396A9 | rgb(115, 150, 169) | Light blue accent |
| Skylight | #FFFAEC | rgb(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
- Full Landscape - Bridge connecting peninsula landscape, district name contained within
- Horizontal - For when name/tagline would be too small
- Emblem - Round versions, perfect for square spaces or tight fits
- 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
| Format | Use 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}.pngpsd_logo-1color-blue-{emblem,fulllandscape,stacked,horizontal,square}.pngpsd_logo-1color-green-{emblem,fulllandscape,stacked,horizontal,square}.pngpsd_logo-white-{emblem,stacked,horizontal,square}.png
EPS files (19) - for professional printing, Adobe programs:
- Same variants as PNG, with
.epsextension
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:
- Danielle Chastaine, Digital Media Coordinator
- chastained@psd401.net
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
| Essential | Core Belief |
|---|---|
| Rigor & Inclusion | All students access grade-level content through responsive, high-expectation instruction |
| Data-Driven Decisions | Multiple sources of evidence inform real-time instructional adjustments |
| Continuous Growth | Ongoing reflection, collaboration, and professional learning deepen outcomes |
| Innovation | Forward-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 planning | Building academic background, scaffolding, formative assessment |
| Assessment | Formative feedback, student self-assessment, data patterns |
| Coaching/PD | Collaborative learning, observation cycles, reflective practice |
| Student engagement | Real-world connections, technology, student voice |
| Differentiation | Flexible 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:
Authorization: Basic [base64(username:password)]headerapiKey: [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 week2= 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 absentabsenceDetail.reasons[0].name- Reason category (SICK, PERSONAL, etc.)location.name- School nameposition.title- Position titleposition.positionType.name- Position category (Teacher, Paraprofessional, etc.)substitute- If present, position is filledstart/end- Absence time rangeneedsReplacement- 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
- Detect domain from query (travel, shopping, work, etc.)
- Load
research_domains.[domain]from preferences - Load referenced context keys
- Fetch any dynamic data (point balances, etc.)
- 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
- User Reviews - TripAdvisor, FlyerTalk, Reddit feedback
- "What I Wish I Knew" - Common mistakes and gotchas
- Real Experiences - Actual trip reports from similar travelers
- Restaurant/Hotel Reviews - With prices and quality feedback
- 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:
- Brave must be running:
cd skills/browser-control && ./scripts/launch-chrome.sh - 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:
- User asks: "What do people say about Westin Rusutsu?"
- Start with
WebSearchfor blog reviews - Find promising Reddit/FlyerTalk threads
- Use
browser-controlto get full thread content - 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:
- Find a source
- Mark it as "unverified"
- 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:
| Agent | Best For | API Required |
|---|---|---|
perplexity-researcher.md | Current web info, citations | PERPLEXITY_API_KEY |
gemini-researcher.md | Multi-angle comparison | GEMINI_API_KEY |
openai-researcher.md | Structured analysis | OPENAI_API_KEY |
claude-researcher.md | Deep reasoning | Native (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
- Create Google Doc in Geoffrey/Research folder
- Use appropriate account (hrg for personal, psd for work)
- Apply markdown formatting (headers, bold, links)
- 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
| # | Advisor | Color | Focus | Core Question |
|---|---|---|---|---|
| 1 | Facilitator | Blue | Process & framing | "What exactly are we deciding?" |
| 2 | Analyst | White | Facts & data | "What do we actually know?" |
| 3 | Intuitive | Red | Emotions & gut feel | "How does this feel?" |
| 4 | Innovator | Green | Creative alternatives | "What else could we do?" |
| 5 | Advocate | Yellow | Benefits & optimism | "What's the best case?" |
| 6 | Critic | Black | Risks & pitfalls | "What could go wrong?" |
| 7 | Stakeholder | Orange | Affected 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:
- Facilitator (Blue) — Frames the decision, lists options, defines success criteria, assesses stakes
- 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
- 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.pyscript 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.
- What should this skill enable Claude to do?
- When should this skill trigger? (what user phrases/contexts)
- What's the expected output format?
- 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/, andassets/ - 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:
- Find the "Available Skills" table in the "Skill Locations" section
- Add a new row:
| {skill-name} | \skills/{skill-name}/SKILL.md` |` - 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:
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md body - In context whenever skill triggers (<500 lines ideal)
- 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:
-
Grade each run -- spawn a grader subagent that reads
agents/grader.mdand evaluates assertions against outputs. Save tograding.json. The grading.json expectations array must use fieldstext,passed, andevidence. For programmatically checkable assertions, write and run a script. -
Aggregate into benchmark:
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>Produces
benchmark.jsonandbenchmark.md. Put each with_skill version before its baseline. -
Do an analyst pass -- read
agents/analyzer.md("Analyzing Benchmark Results" section) for patterns the aggregate stats might hide. -
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. -
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
-
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.
-
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.
-
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.
-
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:
- Apply improvements to the skill
- Rerun all test cases into a new
iteration-<N+1>/directory, including baseline runs - Launch the reviewer with
--previous-workspacepointing at previous iteration - Wait for user review
- 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:
- Read
assets/eval_review.html - Replace placeholders:
__EVAL_DATA_PLACEHOLDER__,__SKILL_NAME_PLACEHOLDER__,__SKILL_DESCRIPTION_PLACEHOLDER__ - Write to a temp file and open it
- 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 outputsagents/comparator.md-- Blind A/B comparison between two outputsagents/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 patternsreferences/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:
- What specific process or procedure needs documenting?
- Which department owns this? (Athletics & Activities, Teaching & Learning, Employee Support Services, Safety & Security, Finance & Operations, Technology, Communications, Governance & Leadership)
- 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
| Department | Folder ID |
|---|---|
| Athletics & Activities | 1E-fmzIAfAXLMVL6brEHkCy1yeZXw-_PC |
| Appendices & Templates | 180TB_nkv87qU2lwRkCXiWCmzsYgzOyjM |
| Teaching and Learning | 1lAfAp7FMQJRFL9g-_IaP_fafEnt4d4pG |
| Employee Support Services | 1ENy54q8vJJ3oekBUXYKiigtLf_aKWBPK |
| Communications & Public Relations | 1FETCQTIijsSPRj3Kil62qrr0TvGuGDvN |
| Safety and Security | 1W2bhVKqdWzSVp0B3LD_EQai_M-ur5E92 |
| Finance and Operations | 1XonFKeTqSH_1qBDbLHMWRILr-hb2Pm1Q |
| Technology | 1j3235TyAzJ2pbNPaSn7dweIvizKmzN5Q |
| Governance and Leadership | 172c_1A2bXUE14bDNoOIJAeErOocx9auI |
| Drafts | 1PLeCQ6DaxWehEbzjzbXU2wLsaLTgv6Ku |
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.mdfor 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-planningskill 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
| Guide | Purpose | Duration |
|---|---|---|
leader-overview.md | Full process overview for superintendents | Reference |
stage1-engage-assess-guide.md | Data collection + SWOT workshop | 2-6 weeks + 2.5 hrs |
stage2-set-direction-guide.md | Vision, priorities, strategic directions | 3-4 hours |
stage3-build-plan-guide.md | Implementation planning workshop | 3-4 hours |
stage4-implement-improve-guide.md | Monitoring and continuous improvement | Ongoing |
appendix-a-vision-development.md | Deep participatory visioning exercise | 3-4 hours |
appendix-b-tension-analysis.md | Organizational tension analysis | 2-3 hours |
appendix-c-graduate-profile.md | Profile of a Graduate development process | Multi-session |
six-month-timeline.md | Month-by-month planning timeline | Reference |
retreat-agenda-2day.md | Full 2-day retreat (all 4 stages) | 2 days |
retreat-agenda-condensed.md | Condensed 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:
| Theme | Prevalence | Key Metrics |
|---|---|---|
| Student Achievement | 90%+ | Test scores, graduation rates, college readiness |
| Equity & Access | 90% | Gap reduction, program access, representation |
| Staff Quality & Retention | 80% | Hiring, development, turnover rates |
| Parent/Community Engagement | 80% | Participation, satisfaction, partnerships |
| Facilities & Technology | 75% | Infrastructure, device ratios, connectivity |
| Fiscal Sustainability | 70% | Budget balance, reserves, cost efficiency |
| Social-Emotional Learning | Growing | SEL metrics, climate surveys, wellness |
| Safety & Security | Variable | Incident 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:
| Profile | Source | Sample Target | Status |
|---|---|---|---|
email_work | PSD Gmail (sent emails, 6mo) | 50+ emails | Check writing-voice.json |
email_personal | Personal/HRG Gmail (sent, 6mo) | 50+ emails | Check writing-voice.json |
blog_technical | psd401.ai + blog.krishagel.com | 10+ posts | Check writing-voice.json |
social_linkedin | LinkedIn profile posts | 30+ posts | Check writing-voice.json |
social_twitter | X/Twitter posts | 30+ posts | Check writing-voice.json |
report_formal | User-provided samples | 5-10 reports | Check 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:
-
Detect content type from user request:
- "write email" →
email_workoremail_personal(ask which) - "blog post" →
blog_technical - "LinkedIn post" →
social_linkedin - "tweet" →
social_twitter - "report" →
report_formal
- "write email" →
-
Load voice profile:
cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/writing-voice.json -
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:
-
Load interview questions from
templates/interview-questions.json -
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)
-
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:
-
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)
-
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
-
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:
-
Load identity context:
cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/identity-core.jsonUse for personality alignment:
communication_preferences.style→ Direct, no-nonsense, concisedecision_framework→ Analytical, evidence-basedtelos_summary.top_3_values→ Equity, excellence, empathy
-
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
- Tone: From
-
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
-
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):
-
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
-
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%)
-
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"
-
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:
-
Determine file path:
~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Personal_Notes/Geoffrey/Writing/{ContentType}/{date}-{slug}.mdContent types:
- Blog →
Geoffrey/Writing/Blog/ - Email →
Geoffrey/Writing/Email/ - Social →
Geoffrey/Writing/Social/ - Reports →
Geoffrey/Writing/Reports/
- Blog →
-
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 --- -
Save file using Obsidian MCP tools:
mcp__obsidian-vault__create_vault_file -
Also return text directly (copy-paste ready)
-
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:
- Read all sample files
- Analyze each profile's:
- Tone and voice
- Sentence structure patterns
- Vocabulary (common/avoided terms)
- Formatting preferences
- Opening/closing patterns
- Argument structure
- Distinctive markers
- Select representative examples
- Calculate confidence scores
- 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, dislikesdecision_framework→ Analytical, evidence-based approachtelos_summary→ Values (equity, excellence, empathy), missionstrengths_essence→ Input (collector), Significance (impact), Analytical
google-workspace → Email Samples
When: Initial voice creation + quarterly refresh
Scripts: search_messages.js, read_message.js
Process:
- Search sent emails
- Filter automated, short, quoted
- Clean signatures, HTML
- Extract plain text + metadata
- 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:
- Navigate to blog/profile URL
- Extract article/post content
- Handle scrolling/lazy-loading (social)
- Parse and clean content
- 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
-
Sample Dependency: Voice quality directly tied to sample quantity and quality
- Low samples (<20) = low accuracy
- Poor quality samples = poor voice matching
-
Voice Drift: Styles evolve over time
- Recommend quarterly refresh (every 3 months)
- Auto-warn if profile >12 months old
-
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
-
Platform Nuances: Social media scraping limitations
- LinkedIn/X may change selectors
- Requires manual login
- May violate ToS (user accepted risk)
-
Multilingual: Currently English only
- No Spanish email profile (even though you write Spanish emails)
- Could add with Spanish samples
-
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)
- Real-time Learning: Auto-analyze new sent emails monthly
- A/B Testing: Generate 2 versions, learn from user choices
- Collaborative Voice: Blend user + co-author voices
- Multi-language: Spanish voice profiles
- Performance Tracking: Voice drift detection over time
- Audience-Aware: Sub-profiles (email_work_superintendent vs email_work_staff)
- 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:
- Check if file exists:
cat ~/Library/Mobile\ Documents/com~apple~CloudDocs/Geoffrey/knowledge/writing-voice.json - If missing: Run initial setup (extract samples + ask Geoffrey to analyze)
- If file exists but profile missing: Add samples for that content type
"Low confidence warning"
Cause: Fewer than 20 samples for profile
Solution:
- Gather more samples using extraction scripts
- Ask Geoffrey to re-analyze with new samples
- 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:
- Open Geoffrey Chrome manually
- Navigate to LinkedIn/X and log in
- Verify posts load
- Re-run extraction script
- 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
- Choose tool: pandas for data, openpyxl for formulas/formatting
- Create/Load: Create new workbook or load existing file
- Modify: Add/edit data, formulas, and formatting
- Save: Write to file
- Recalculate formulas (MANDATORY IF USING FORMULAS): Use the recalc.py script
skills/xlsx/recalc.py output.xlsx - Verify and fix any errors:
- The script returns JSON with error details
- If
statusiserrors_found, checkerror_summaryfor 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=Trueto read calculated values:load_workbook('file.xlsx', data_only=True) - Warning: If opened with
data_only=Trueand saved, formulas are replaced with values and permanently lost - For large files: Use
read_only=Truefor reading orwrite_only=Truefor 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:
-
Teach Geoffrey something new:
"I prefer window seats on flights, not aisle" -
Update existing preferences:
"Actually, I prefer Hilton over Marriott now" -
Delete preferences:
"Forget my airline preferences" -
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:
- Read the preferences.json file
- Parse and format for display
- Show confidence scores with visual indicators
- Group by category
- Provide summary statistics
- Offer next action suggestions
Sponsors
Details
- Marketplace
- krishagel/geoffrey
- Category
- Productivity
- Keywords
- personal-ai, learning, preferences, assistant, travel, productivity, strategic-planning, omnifocus