From ac0da8c1cd7593e816e50fd01273f701f5f3f005 Mon Sep 17 00:00:00 2001 From: m3tm3re Date: Tue, 6 Jan 2026 05:52:07 +0100 Subject: [PATCH] docs: expand scope and add comprehensive documentation Create README.md and enhance AGENTS.md to position this as an extensible framework for any Opencode skills and agents, not just PARA/task management. Includes installation, development workflow, code style guidelines, and Nix flake integration patterns. --- .beads/.gitignore | 39 ++ .beads/README.md | 81 ++++ .beads/config.yaml | 62 +++ .beads/interactions.jsonl | 0 .beads/issues.jsonl | 0 .beads/metadata.json | 4 + .gitattributes | 3 + AGENTS.md | 365 +++++++++++++++++ README.md | 315 ++++++++++++++ agent/chiron.md | 92 +++++ command/reflection.md | 20 + context/profile.md | 106 +++++ skill/calendar-scheduling/SKILL.md | 69 ++++ skill/communications/SKILL.md | 78 ++++ skill/knowledge-management/SKILL.md | 60 +++ skill/mem0-memory/SKILL.md | 166 ++++++++ skill/mem0-memory/references/api_reference.md | 202 +++++++++ skill/reflection/SKILL.md | 262 ++++++++++++ skill/reflection/references/command-usage.md | 85 ++++ .../references/rating-guidelines.md | 126 ++++++ .../reflection/references/signal-patterns.md | 79 ++++ skill/research/SKILL.md | 54 +++ skill/skill-creator/SKILL.md | 387 ++++++++++++++++++ .../references/output-patterns.md | 82 ++++ skill/skill-creator/references/workflows.md | 28 ++ skill/skill-creator/scripts/init_skill.py | 304 ++++++++++++++ skill/skill-creator/scripts/quick_validate.py | 81 ++++ skill/task-management/SKILL.md | 246 +++++++++++ .../references/anytype-setup.md | 176 ++++++++ .../references/anytype-workflows.md | 346 ++++++++++++++++ .../references/para-methodology.md | 190 +++++++++ .../references/review-templates.md | 307 ++++++++++++++ 32 files changed, 4415 insertions(+) create mode 100644 .beads/.gitignore create mode 100644 .beads/README.md create mode 100644 .beads/config.yaml create mode 100644 .beads/interactions.jsonl create mode 100644 .beads/issues.jsonl create mode 100644 .beads/metadata.json create mode 100644 .gitattributes create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 agent/chiron.md create mode 100644 command/reflection.md create mode 100644 context/profile.md create mode 100644 skill/calendar-scheduling/SKILL.md create mode 100644 skill/communications/SKILL.md create mode 100644 skill/knowledge-management/SKILL.md create mode 100644 skill/mem0-memory/SKILL.md create mode 100644 skill/mem0-memory/references/api_reference.md create mode 100644 skill/reflection/SKILL.md create mode 100644 skill/reflection/references/command-usage.md create mode 100644 skill/reflection/references/rating-guidelines.md create mode 100644 skill/reflection/references/signal-patterns.md create mode 100644 skill/research/SKILL.md create mode 100644 skill/skill-creator/SKILL.md create mode 100644 skill/skill-creator/references/output-patterns.md create mode 100644 skill/skill-creator/references/workflows.md create mode 100755 skill/skill-creator/scripts/init_skill.py create mode 100755 skill/skill-creator/scripts/quick_validate.py create mode 100644 skill/task-management/SKILL.md create mode 100644 skill/task-management/references/anytype-setup.md create mode 100644 skill/task-management/references/anytype-workflows.md create mode 100644 skill/task-management/references/para-methodology.md create mode 100644 skill/task-management/references/review-templates.md diff --git a/.beads/.gitignore b/.beads/.gitignore new file mode 100644 index 0000000..4a7a77d --- /dev/null +++ b/.beads/.gitignore @@ -0,0 +1,39 @@ +# SQLite databases +*.db +*.db?* +*.db-journal +*.db-wal +*.db-shm + +# Daemon runtime files +daemon.lock +daemon.log +daemon.pid +bd.sock +sync-state.json +last-touched + +# Local version tracking (prevents upgrade notification spam after git ops) +.local_version + +# Legacy database files +db.sqlite +bd.db + +# Worktree redirect file (contains relative path to main repo's .beads/) +# Must not be committed as paths would be wrong in other clones +redirect + +# Merge artifacts (temporary files from 3-way merge) +beads.base.jsonl +beads.base.meta.json +beads.left.jsonl +beads.left.meta.json +beads.right.jsonl +beads.right.meta.json + +# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here. +# They would override fork protection in .git/info/exclude, allowing +# contributors to accidentally commit upstream issue databases. +# The JSONL files (issues.jsonl, interactions.jsonl) and config files +# are tracked by git by default since no pattern above ignores them. diff --git a/.beads/README.md b/.beads/README.md new file mode 100644 index 0000000..50f281f --- /dev/null +++ b/.beads/README.md @@ -0,0 +1,81 @@ +# Beads - AI-Native Issue Tracking + +Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code. + +## What is Beads? + +Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git. + +**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads) + +## Quick Start + +### Essential Commands + +```bash +# Create new issues +bd create "Add user authentication" + +# View all issues +bd list + +# View issue details +bd show + +# Update issue status +bd update --status in_progress +bd update --status done + +# Sync with git remote +bd sync +``` + +### Working with Issues + +Issues in Beads are: +- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code +- **AI-friendly**: CLI-first design works perfectly with AI coding agents +- **Branch-aware**: Issues can follow your branch workflow +- **Always in sync**: Auto-syncs with your commits + +## Why Beads? + +✨ **AI-Native Design** +- Built specifically for AI-assisted development workflows +- CLI-first interface works seamlessly with AI coding agents +- No context switching to web UIs + +πŸš€ **Developer Focused** +- Issues live in your repo, right next to your code +- Works offline, syncs when you push +- Fast, lightweight, and stays out of your way + +πŸ”§ **Git Integration** +- Automatic sync with git commits +- Branch-aware issue tracking +- Intelligent JSONL merge resolution + +## Get Started with Beads + +Try Beads in your own projects: + +```bash +# Install Beads +curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash + +# Initialize in your repo +bd init + +# Create your first issue +bd create "Try out Beads" +``` + +## Learn More + +- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs) +- **Quick Start Guide**: Run `bd quickstart` +- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples) + +--- + +*Beads: Issue tracking that moves at the speed of thought* ⚑ diff --git a/.beads/config.yaml b/.beads/config.yaml new file mode 100644 index 0000000..f242785 --- /dev/null +++ b/.beads/config.yaml @@ -0,0 +1,62 @@ +# Beads Configuration File +# This file configures default behavior for all bd commands in this repository +# All settings can also be set via environment variables (BD_* prefix) +# or overridden with command-line flags + +# Issue prefix for this repository (used by bd init) +# If not set, bd init will auto-detect from directory name +# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc. +# issue-prefix: "" + +# Use no-db mode: load from JSONL, no SQLite, write back after each command +# When true, bd will use .beads/issues.jsonl as the source of truth +# instead of SQLite database +# no-db: false + +# Disable daemon for RPC communication (forces direct database access) +# no-daemon: false + +# Disable auto-flush of database to JSONL after mutations +# no-auto-flush: false + +# Disable auto-import from JSONL when it's newer than database +# no-auto-import: false + +# Enable JSON output by default +# json: false + +# Default actor for audit trails (overridden by BD_ACTOR or --actor) +# actor: "" + +# Path to database (overridden by BEADS_DB or --db) +# db: "" + +# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON) +# auto-start-daemon: true + +# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE) +# flush-debounce: "5s" + +# Git branch for beads commits (bd sync will commit to this branch) +# IMPORTANT: Set this for team projects so all clones use the same sync branch. +# This setting persists across clones (unlike database config which is gitignored). +# Can also use BEADS_SYNC_BRANCH env var for local override. +# If not set, bd sync will require you to run 'bd config set sync.branch '. +# sync-branch: "beads-sync" + +# Multi-repo configuration (experimental - bd-307) +# Allows hydrating from multiple repositories and routing writes to the correct JSONL +# repos: +# primary: "." # Primary repo (where this database lives) +# additional: # Additional repos to hydrate from (read-only) +# - ~/beads-planning # Personal planning repo +# - ~/work-planning # Work planning repo + +# Integration settings (access with 'bd config get/set') +# These are stored in the database, not in this file: +# - jira.url +# - jira.project +# - linear.url +# - linear.api-key +# - github.org +# - github.repo diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl new file mode 100644 index 0000000..e69de29 diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl new file mode 100644 index 0000000..e69de29 diff --git a/.beads/metadata.json b/.beads/metadata.json new file mode 100644 index 0000000..c787975 --- /dev/null +++ b/.beads/metadata.json @@ -0,0 +1,4 @@ +{ + "database": "beads.db", + "jsonl_export": "issues.jsonl" +} \ No newline at end of file diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..807d598 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ + +# Use bd merge for beads JSONL files +.beads/issues.jsonl merge=beads diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..912d731 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,365 @@ +# Agent Instructions - Opencode Skills Repository + +This repository contains Opencode Agent Skills, context files, and agent configurations for personal productivity and AI-assisted workflows. Files are deployed to `~/.config/opencode/` via Nix flake + home-manager. + +## Project Overview + +**Type**: Configuration-only repository (no build/compile step) +**Purpose**: Central repository for Opencode Agent Skills, AI agent configurations, custom commands, and workflows. Extensible framework for productivity, automation, knowledge management, and AI-assisted development. +**Primary User**: Sascha Koenig (@m3tam3re) +**Deployment**: Nix flake β†’ home-manager β†’ `~/.config/opencode/` + +### Current Focus Areas + +- **Productivity & Task Management** - PARA methodology, Anytype integration, reviews +- **Knowledge Management** - Note capture, organization, research workflows +- **Communications** - Email drafts, follow-ups, calendar scheduling +- **AI Development** - Skill creation, agent configurations, custom commands +- **Memory & Context** - Persistent memory with Mem0, conversation analysis + +### Extensibility + +This repository serves as a foundation for any Opencode-compatible skill or agent configuration. Add new skills for: +- Domain-specific workflows (finance, legal, engineering, etc.) +- Tool integrations (APIs, databases, cloud platforms) +- Custom automation and productivity systems +- Specialized AI agents for different contexts + +### Directory Structure + +``` +. +β”œβ”€β”€ agent/ # AI agent configurations (chiron.md) +β”œβ”€β”€ context/ # User profiles and preferences +β”œβ”€β”€ command/ # Custom command definitions +β”œβ”€β”€ skill/ # Opencode Agent Skills (8 skills) +β”‚ β”œβ”€β”€ task-management/ +β”‚ β”œβ”€β”€ skill-creator/ +β”‚ β”œβ”€β”€ reflection/ +β”‚ β”œβ”€β”€ communications/ +β”‚ β”œβ”€β”€ calendar-scheduling/ +β”‚ β”œβ”€β”€ mem0-memory/ +β”‚ β”œβ”€β”€ research/ +β”‚ └── knowledge-management/ +β”œβ”€β”€ .beads/ # Issue tracking database +└── AGENTS.md # This file +``` + +## Issue Tracking with Beads + +This project uses **bd** (beads) for AI-native issue tracking. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --status in_progress # Claim work +bd close # Complete work +bd sync # Sync with git +bd list # View all issues +bd create "title" # Create new issue +``` + +### Beads Workflow Integration + +- Issues live in `.beads/` directory (git-tracked) +- Auto-syncs with commits +- CLI-first design for AI agents +- No web UI needed + +## Skill Development + +### Creating a New Skill + +Use the skill initialization script: + +```bash +python3 skill/skill-creator/scripts/init_skill.py --path skill/ +``` + +This creates: +- `skill//SKILL.md` with proper frontmatter template +- `skill//scripts/` - For executable code +- `skill//references/` - For documentation +- `skill//assets/` - For templates/files + +### Validating Skills + +Run validation before committing: + +```bash +python3 skill/skill-creator/scripts/quick_validate.py skill/ +``` + +**Validation checks:** +- YAML frontmatter structure +- Required fields: `name`, `description` +- Name format: hyphen-case, max 64 chars +- Description: max 1024 chars, no angle brackets +- Allowed frontmatter properties: `name`, `description`, `compatibility`, `license`, `allowed-tools`, `metadata` + +### Skill Structure Requirements + +**SKILL.md Frontmatter** (required): +```yaml +--- +name: skill-name +description: What it does and when to use it. Include trigger words. +compatibility: opencode +--- +``` + +**Resource Directories** (optional): +- `scripts/` - Executable Python/Bash code for deterministic operations +- `references/` - Documentation loaded into context as needed +- `assets/` - Files used in output (templates, images, fonts) + +### Skill Design Principles + +1. **Concise is key** - Context window is shared resource +2. **Progressive disclosure** - Metadata β†’ SKILL.md body β†’ bundled resources +3. **Appropriate freedom** - Match specificity to task fragility +4. **No extraneous files** - No README.md, CHANGELOG.md, etc. in skills +5. **Reference patterns** - See `skill/skill-creator/references/workflows.md` and `output-patterns.md` + +## Code Style Guidelines + +### File Naming + +**Skills**: Hyphen-case (e.g., `task-management`, `skill-creator`) +**Python scripts**: Snake_case (e.g., `init_skill.py`, `quick_validate.py`) +**Markdown files**: UPPERCASE or sentence-case (e.g., `SKILL.md`, `profile.md`) +**Configuration**: Standard conventions (e.g., `config.yaml`, `metadata.json`) + +### Markdown Style + +**Frontmatter**: +- Always use YAML format between `---` delimiters +- Required fields for skills: `name`, `description` +- Optional: `compatibility: opencode`, `mode: primary` + +**Headers**: +- Use ATX-style (`#`, `##`, `###`) +- One H1 per file (skill title) +- Clear hierarchy + +**Lists**: +- Use `-` for unordered lists (not `*`) +- Use numbered lists for sequential steps +- Indent nested lists with 2 spaces + +**Code blocks**: +- Always specify language for syntax highlighting +- Use `bash` for shell commands +- Use `yaml`, `nix`, `python` as appropriate + +**Tables**: +- Use for structured comparisons and reference data +- Keep aligned for readability in source +- Example: + ```markdown + | Header 1 | Header 2 | + |----------|----------| + | Value | Value | + ``` + +### Python Style + +**Shebang**: Always use `#!/usr/bin/env python3` + +**Docstrings**: +```python +""" +Brief description of module/script + +Usage: + script_name.py --flag + +Examples: + script_name.py my-skill --path ~/.config/opencode/skill +""" +``` + +**Imports**: +```python +# Standard library +import sys +import os +from pathlib import Path + +# Third-party (if any) +import yaml + +# Local (if any) +from . import utilities +``` + +**Naming**: +- Functions: `snake_case` +- Classes: `PascalCase` +- Constants: `UPPER_SNAKE_CASE` +- Private: `_leading_underscore` + +**Error handling**: +```python +try: + # operation +except SpecificException as e: + print(f"❌ Error: {e}") + return None +``` + +**User feedback**: +- Use βœ… for success messages +- Use ❌ for error messages +- Print progress for multi-step operations + +### YAML Style + +```yaml +# Use lowercase keys with hyphens +skill-name: value + +# Quotes for strings with special chars +description: "PARA-based task management. Use when: (1) item, (2) item." + +# No quotes for simple strings +compatibility: opencode + +# Lists with hyphens +items: + - first + - second +``` + +## Nix Flake Integration + +This repository is designed to be consumed by a Nix flake via home-manager. + +### Expected Deployment Pattern + +```nix +# In your flake.nix or home.nix +xdg.configFile."opencode" = { + source = /path/to/AGENTS; + recursive = true; +}; +``` + +This deploys: +- `agent/` β†’ `~/.config/opencode/agent/` +- `skill/` β†’ `~/.config/opencode/skill/` +- `context/` β†’ `~/.config/opencode/context/` +- `command/` β†’ `~/.config/opencode/command/` + +### Best Practices for Nix + +1. **Keep original structure** - Don't rename directories; Opencode expects this layout +2. **Use recursive = true** - Required for directory deployment +3. **Exclude .git and .beads** - These are development artifacts: + ```nix + xdg.configFile."opencode" = { + source = /path/to/AGENTS; + recursive = true; + # Or filter with lib.cleanSource + }; + ``` +4. **No absolute paths in configs** - All references should be relative + +## Quality Gates + +Before committing changes, verify: + +1. **Skill validation** - Run `quick_validate.py` on modified skills +2. **File structure** - Ensure no extraneous files (README in skills, etc.) +3. **Frontmatter** - Check YAML syntax and required fields +4. **Scripts executable** - Python scripts should have proper shebang +5. **Markdown formatting** - Check headers, lists, code blocks +6. **Git status** - No uncommitted or untracked files that should be tracked + +## Landing the Plane (Session Completion) + +**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. + +### MANDATORY WORKFLOW + +1. **File issues for remaining work** - Create beads issues for anything that needs follow-up +2. **Run quality gates** - Validate modified skills, check file structure +3. **Update issue status** - Close finished work, update in-progress items +4. **PUSH TO REMOTE** - This is MANDATORY: + ```bash + git pull --rebase + bd sync + git push + git status # MUST show "up to date with origin" + ``` +5. **Clean up** - Clear stashes, prune remote branches +6. **Verify** - All changes committed AND pushed +7. **Hand off** - Provide context for next session + +### CRITICAL RULES + +- Work is NOT complete until `git push` succeeds +- NEVER stop before pushing - that leaves work stranded locally +- NEVER say "ready to push when you are" - YOU must push +- If push fails, resolve and retry until it succeeds + +## Common Operations + +### Test a Skill Locally + +```bash +# Validate structure +python3 skill/skill-creator/scripts/quick_validate.py skill/ + +# Check skill triggers by reading SKILL.md frontmatter +grep -A5 "^description:" skill//SKILL.md +``` + +### Create New Skill + +```bash +# Initialize +python3 skill/skill-creator/scripts/init_skill.py my-new-skill --path skill/ + +# Edit SKILL.md and implement resources +# Delete unneeded example files from scripts/, references/, assets/ + +# Validate +python3 skill/skill-creator/scripts/quick_validate.py skill/my-new-skill +``` + +### Update User Context + +Edit `context/profile.md` to update: +- Work style preferences +- PARA areas +- Communication preferences +- Integration status + +### Modify Agent Behavior + +Edit `agent/chiron.md` to adjust: +- Skill routing logic +- Communication protocols +- Daily rhythm support +- Operating principles + +## Reference Documentation + +**Skill creation guide**: `skill/skill-creator/SKILL.md` +**Workflow patterns**: `skill/skill-creator/references/workflows.md` +**Output patterns**: `skill/skill-creator/references/output-patterns.md` +**User profile**: `context/profile.md` +**Agent config**: `agent/chiron.md` +**Beads docs**: `.beads/README.md` + +## Notes for AI Agents + +1. **This is a config repo** - No compilation, no tests, no runtime +2. **Validation is manual** - Run scripts explicitly before committing +3. **Skills are documentation** - Write for AI consumption, not humans +4. **Context window matters** - Keep skills concise, use progressive disclosure +5. **Nix deployment** - Maintain structure expected by home-manager +6. **Always push** - Follow session completion workflow religiously diff --git a/README.md b/README.md new file mode 100644 index 0000000..59eb703 --- /dev/null +++ b/README.md @@ -0,0 +1,315 @@ +# Opencode Agent Skills & Configurations + +Central repository for [Opencode](https://opencode.dev) Agent Skills, AI agent configurations, custom commands, and AI-assisted workflows. This is an extensible framework for building productivity systems, automations, knowledge management, and specialized AI capabilities. + +## 🎯 What This Repository Provides + +This repository serves as a **personal AI operating system** - a collection of skills, agents, and configurations that extend Opencode's capabilities for: + +- **Productivity & Task Management** - PARA methodology, GTD workflows, project tracking +- **Knowledge Management** - Note-taking, research workflows, information organization +- **Communications** - Email management, meeting scheduling, follow-up tracking +- **AI Development** - Tools for creating new skills and agent configurations +- **Memory & Context** - Persistent memory systems, conversation analysis +- **Custom Workflows** - Domain-specific automation and specialized agents + +## πŸ“‚ Repository Structure + +``` +. +β”œβ”€β”€ agent/ # AI agent configurations +β”‚ └── chiron.md # Personal assistant agent +β”œβ”€β”€ context/ # User profiles and preferences +β”‚ └── profile.md # Work style, PARA areas, preferences +β”œβ”€β”€ command/ # Custom command definitions +β”‚ └── reflection.md +β”œβ”€β”€ skill/ # Opencode Agent Skills (8+ skills) +β”‚ β”œβ”€β”€ task-management/ # PARA-based productivity +β”‚ β”œβ”€β”€ skill-creator/ # Meta-skill for creating skills +β”‚ β”œβ”€β”€ reflection/ # Conversation analysis +β”‚ β”œβ”€β”€ communications/ # Email & messaging +β”‚ β”œβ”€β”€ calendar-scheduling/ # Time management +β”‚ β”œβ”€β”€ mem0-memory/ # Persistent memory +β”‚ β”œβ”€β”€ research/ # Investigation workflows +β”‚ └── knowledge-management/ # Note capture & organization +β”œβ”€β”€ .beads/ # Issue tracking database +β”œβ”€β”€ AGENTS.md # Developer documentation +└── README.md # This file +``` + +## πŸš€ Getting Started + +### Prerequisites + +- **Opencode** - AI coding assistant ([opencode.dev](https://opencode.dev)) +- **Nix** (optional) - For declarative deployment via home-manager +- **Python 3** - For skill validation and creation scripts +- **bd (beads)** (optional) - For issue tracking + +### Installation + +#### Option 1: Nix Flake (Recommended) + +Add to your Nix flake configuration: + +```nix +# In your flake.nix or home.nix +{ + inputs.agents = { + url = "github:yourusername/AGENTS"; # Update with your repo + flake = false; + }; + + # In your home-manager configuration + xdg.configFile."opencode" = { + source = inputs.agents; + recursive = true; + }; +} +``` + +Rebuild your system: +```bash +home-manager switch +``` + +#### Option 2: Manual Installation + +Clone and symlink: + +```bash +# Clone repository +git clone https://github.com/yourusername/AGENTS.git ~/AGENTS + +# Create symlink to Opencode config directory +ln -s ~/AGENTS ~/.config/opencode +``` + +### Verify Installation + +Check that Opencode can see your skills: + +```bash +# Skills should be available at ~/.config/opencode/skill/ +ls ~/.config/opencode/skill/ +``` + +## 🎨 Creating Your First Skill + +Skills are modular packages that extend Opencode with specialized knowledge and workflows. + +### 1. Initialize a New Skill + +```bash +python3 skill/skill-creator/scripts/init_skill.py my-skill-name --path skill/ +``` + +This creates: +- `skill/my-skill-name/SKILL.md` - Main skill documentation +- `skill/my-skill-name/scripts/` - Executable code (optional) +- `skill/my-skill-name/references/` - Reference documentation (optional) +- `skill/my-skill-name/assets/` - Templates and files (optional) + +### 2. Edit the Skill + +Open `skill/my-skill-name/SKILL.md` and customize: + +```yaml +--- +name: my-skill-name +description: What it does and when to use it. Include trigger keywords. +compatibility: opencode +--- + +# My Skill Name + +## Overview + +[Your skill instructions for Opencode] +``` + +### 3. Validate the Skill + +```bash +python3 skill/skill-creator/scripts/quick_validate.py skill/my-skill-name +``` + +### 4. Test in Opencode + +Open Opencode and trigger your skill naturally in conversation. The skill will load based on the `description` field in the frontmatter. + +## πŸ“š Available Skills + +| Skill | Purpose | Status | +|-------|---------|--------| +| **task-management** | PARA-based productivity with Anytype integration | βœ… Active | +| **skill-creator** | Guide for creating new Opencode skills | βœ… Active | +| **reflection** | Conversation analysis and skill improvement | βœ… Active | +| **communications** | Email drafts, follow-ups, message management | βœ… Active | +| **calendar-scheduling** | Time blocking, meeting management | βœ… Active | +| **mem0-memory** | Persistent memory storage and retrieval | βœ… Active | +| **research** | Investigation workflows, source management | 🚧 Stub | +| **knowledge-management** | Note capture, knowledge organization | 🚧 Stub | + +## πŸ€– AI Agents + +### Chiron - Personal Assistant + +**Location**: `agent/chiron.md` + +Chiron is a personal AI assistant focused on productivity and task management. Named after the wise centaur from Greek mythology, Chiron provides: + +- Task and project management guidance +- Daily and weekly review workflows +- Skill routing based on user intent +- Integration with productivity tools (Anytype, ntfy, n8n) + +**Triggers**: Personal productivity requests, task management, reviews, planning + +## πŸ› οΈ Development Workflow + +### Issue Tracking with Beads + +This project uses [beads](https://github.com/steveyegge/beads) for AI-native issue tracking: + +```bash +bd ready # Find available work +bd create "title" # Create new issue +bd update --status in_progress +bd close # Complete work +bd sync # Sync with git +``` + +### Quality Gates + +Before committing: + +1. **Validate skills**: `python3 skill/skill-creator/scripts/quick_validate.py skill/` +2. **Check formatting**: Ensure YAML frontmatter is valid +3. **Test locally**: Use the skill in Opencode to verify behavior +4. **Update docs**: Keep README and AGENTS.md in sync + +### Session Completion + +When ending a work session: + +1. File beads issues for remaining work +2. Run quality gates +3. Update issue status +4. **Push to remote** (mandatory): + ```bash + git pull --rebase + bd sync + git push + ``` +5. Verify changes are pushed + +See `AGENTS.md` for complete developer documentation. + +## πŸŽ“ Learning Resources + +### Essential Documentation + +- **AGENTS.md** - Complete developer guide for AI agents +- **skill/skill-creator/SKILL.md** - Comprehensive skill creation guide +- **skill/skill-creator/references/workflows.md** - Workflow pattern library +- **skill/skill-creator/references/output-patterns.md** - Output formatting patterns + +### Skill Design Principles + +1. **Concise is key** - Context window is a shared resource +2. **Progressive disclosure** - Load information as needed +3. **Appropriate freedom** - Match specificity to task fragility +4. **No extraneous files** - Keep skills focused and minimal + +### Example Skills to Study + +- **task-management/** - Full implementation with Anytype integration +- **skill-creator/** - Meta-skill with bundled resources +- **reflection/** - Conversation analysis with rating system + +## πŸ”§ Customization + +### Modify Agent Behavior + +Edit `agent/chiron.md` to customize: +- Skill routing logic +- Communication style +- Operating principles +- Integration awareness + +### Update User Context + +Edit `context/profile.md` to configure: +- Work style preferences +- PARA areas and projects +- Communication preferences +- Integration status + +### Add Custom Commands + +Create new command definitions in `command/` directory following the pattern in `command/reflection.md`. + +## 🌟 Use Cases + +### Personal Productivity + +Use the PARA methodology with Anytype integration: +- Capture tasks and notes quickly +- Run daily/weekly reviews +- Prioritize work based on impact +- Batch similar tasks for efficiency + +### Knowledge Management + +Build a personal knowledge base: +- Capture research findings +- Organize notes and references +- Link related concepts +- Retrieve information on demand + +### AI-Assisted Development + +Extend Opencode for specialized domains: +- Create company-specific skills (finance, legal, engineering) +- Integrate with APIs and databases +- Build custom automation workflows +- Deploy via Nix for reproducibility + +### Team Collaboration + +Share skills and agents across teams: +- Document company processes as skills +- Create shared knowledge bases +- Standardize communication templates +- Build domain expertise libraries + +## 🀝 Contributing + +This is a personal repository, but the patterns and structure are designed to be reusable: + +1. **Fork** this repository +2. **Customize** for your own use case +3. **Share** interesting skills and patterns +4. **Learn** from the skill-creator documentation + +## πŸ“ License + +This repository contains personal configurations and skills. Feel free to use the patterns and structure as inspiration for your own setup. + +## πŸ”— Links + +- [Opencode](https://opencode.dev) - AI coding assistant +- [Beads](https://github.com/steveyegge/beads) - AI-native issue tracking +- [PARA Method](https://fortelabs.com/blog/para/) - Productivity methodology +- [Anytype](https://anytype.io) - Knowledge management platform + +## πŸ™‹ Questions? + +- Check `AGENTS.md` for detailed developer documentation +- Review existing skills in `skill/` for examples +- See `skill/skill-creator/SKILL.md` for skill creation guide + +--- + +**Built with** ❀️ **for AI-augmented productivity** diff --git a/agent/chiron.md b/agent/chiron.md new file mode 100644 index 0000000..3dd2297 --- /dev/null +++ b/agent/chiron.md @@ -0,0 +1,92 @@ +--- +description: Personal AI assistant for Sascha Koenig. Wise mentor for productivity, task management, knowledge organization, and technical leadership. Uses PARA methodology with Anytype integration. Triggers on personal productivity requests, task management, daily/weekly reviews, project planning, and knowledge capture. +mode: primary +--- + +# Chiron - Personal Assistant + +You are Chiron, Sascha's personal AI assistant. Named after the wise centaur who mentored heroes like Achilles and Heracles, you guide Sascha toward peak productivity and clarity. + +## Core Identity + +- **Role**: Trusted mentor and productivity partner +- **Style**: Direct, efficient, anticipatory +- **Philosophy**: Work smarter through systems, not harder through willpower + +## Owner Context + +Load and internalize `context/profile.md` for Sascha's preferences, work style, and PARA areas. Key points: + +- **CTO** at 150-person company +- **Creator**: m3ta.dev, YouTube @m3tam3re +- **Focus**: Early mornings for deep work +- **Reviews**: Evening daily reviews +- **Method**: PARA (Projects, Areas, Resources, Archives) +- **Style**: Impact-first prioritization, context batching + +## Skill Routing + +Route requests to appropriate skills based on intent: + +| Intent Pattern | Skill | Examples | +|----------------|-------|----------| +| Tasks, projects, todos, priorities, reviews | `task-management` | "What should I focus on?", "Create a project for X", "Daily review" | +| Research, investigate, learn about, explore | `research` | "Research Y technology", "What are best practices for Z?" | +| Notes, knowledge, reference, documentation | `knowledge-management` | "Save this for later", "Where did I put notes on X?" | +| Calendar, schedule, meetings, time blocks | `calendar-scheduling` | "What's my day look like?", "Block time for deep work" | +| Email, messages, follow-ups, communication | `communications` | "Draft response to X", "What needs follow-up?" | + +## Communication Protocol + +### Response Style +- Lead with the answer or action +- Bullet points over prose +- No preamble ("I'll help you with...", "Great question!") +- Code/commands when applicable + +### Proactive Behaviors +- Surface urgent items without being asked +- Suggest next actions after completing tasks +- Flag potential conflicts or blockers +- Prepare relevant context before likely requests + +### Daily Rhythm Support +- **Morning**: Ready with priorities if asked +- **During day**: Quick captures, minimal friction +- **Evening**: Daily review summary, tomorrow prep + +## Integration Awareness + +### Active Integrations +- **Anytype**: Primary knowledge/task store (Space: Chiron) +- **ntfy**: Push notifications for important items +- **n8n**: Workflow automation triggers + +### Future Integrations (Stubs) +- Proton Calendar: Scheduling sync +- Proton Mail: Communication management + +## Operating Principles + +1. **Minimize friction** - Quick capture over perfect organization +2. **Trust the system** - PARA handles organization, you handle execution +3. **Impact over activity** - Focus on outcomes, not busywork +4. **Context is king** - Batch similar work, protect focus blocks +5. **Evening reflection** - Review drives improvement + +## When Uncertain + +- For ambiguous requests: Ask one clarifying question max +- For complex decisions: Present 2-3 options with recommendation +- For personal matters: Respect boundaries, don't over-assist +- For technical work: Defer to specialized agents (build, explore, etc.) + +## Skills Available + +Reference these skills for detailed workflows: + +- `task-management` - PARA methodology, Anytype integration, reviews +- `research` - Investigation workflows, source management +- `knowledge-management` - Note capture, knowledge base organization +- `calendar-scheduling` - Time blocking, meeting management +- `communications` - Email drafts, follow-up tracking diff --git a/command/reflection.md b/command/reflection.md new file mode 100644 index 0000000..c0f282b --- /dev/null +++ b/command/reflection.md @@ -0,0 +1,20 @@ +--- +description: Toggle reflection mode on/off for automatic skill improvement detection +--- + +Reflection mode is now set to: $1 + +When reflection mode is **ON**, I will: +- Actively monitor for user correction signals during conversation +- Detect patterns where you correct my behavior +- Automatically suggest skill improvements when clear signals detected +- Proactively ask "Should I reflect on this?" when corrections occur + +When reflection mode is **OFF** (default), I will: +- Only perform reflection when explicitly requested +- Respond to explicit commands like "reflect on [skill]" +- No automatic signal detection or suggestions + +Current mode: **$1** + +Note: This setting is session-scoped and will reset to OFF in new sessions. diff --git a/context/profile.md b/context/profile.md new file mode 100644 index 0000000..f021a49 --- /dev/null +++ b/context/profile.md @@ -0,0 +1,106 @@ +# Sascha Koenig - Personal Context + +## Identity + +- **Name**: Sascha Koenig (m3tam3re) +- **Role**: CTO at company with 150 employees +- **Location**: Germany +- **Creator**: m3ta.dev, YouTube @m3tam3re +- **Background**: E-commerce automation expert, former 7-figure business owner +- **Tech Focus**: NixOS, self-hosting, AI automation, n8n, Docker + +## Work Style + +| Aspect | Preference | +|--------|------------| +| Focus hours | Early mornings | +| Review time | Evenings | +| Prioritization | Impact-first | +| Batching | Context-based (similar tasks together) | +| Methodology | PARA | + +## PARA Areas + +1. **CTO Leadership** - Team management, technical strategy, architecture decisions, hiring +2. **m3ta.dev** - Content creation, courses (NixOS Flakes), coaching, tutoring programs +3. **YouTube @m3tam3re** - Technical exploration videos, tutorials, self-hosting guides +4. **Technical Exploration** - NixOS, self-hosting, AI agents, automation experiments +5. **Personal Development** - Learning, skills growth, reading +6. **Health & Wellness** - Exercise, rest, sustainability +7. **Family** - Quality time, responsibilities + +## Communication Preferences + +### Response Style +- Concise and direct +- Bullet points over paragraphs +- No fluff or pleasantries +- Code examples over explanations + +### Proactivity Level +- Anticipate needs and prepare ahead +- Suggest next actions when obvious +- Flag potential issues early + +### Notifications +- **Daily**: Evening summaries of completed/pending items +- **Real-time**: Only for urgent/important items +- **Channel**: ntfy for push notifications + +### Information Depth +- Quick summaries first +- Drill down on explicit request +- Data-driven with gut-check validation + +## Learning Style + +- Reading and text-based content +- Examples and walkthroughs +- Step-by-step with rationale +- Real-world use cases + +## Decision Making + +1. Data-driven analysis first +2. Gut-check validation +3. Options presented with recommendation +4. Final call is mine + +## Current Integrations + +| System | Purpose | Status | +|--------|---------|--------| +| Anytype | Knowledge management, PARA system | Setting up | +| ntfy | Push notifications | Active | +| n8n | Workflow automation | Active | +| Proton Mail | Email | Active | +| Proton Calendar | Scheduling | Active | +| Android | Mobile | Active | + +## Anytype Configuration + +- **Space**: Chiron (to be created) +- **Structure**: PARA methodology +- **Types**: Project, Area, Resource, Archive, Task, Note + +## Context for AI Interactions + +### What I Value +- Efficiency over ceremony +- Working solutions over perfect solutions +- Automation over manual processes +- Self-hosted over SaaS when practical +- Open source when available + +### Pet Peeves +- Unnecessary verbosity +- Obvious statements +- Asking for confirmation on trivial decisions +- Over-explaining basic concepts + +### How to Help Me Best +- Get to the point quickly +- Propose solutions, not just problems +- Batch related information together +- Remember my preferences across sessions +- Proactively surface relevant information diff --git a/skill/calendar-scheduling/SKILL.md b/skill/calendar-scheduling/SKILL.md new file mode 100644 index 0000000..6add405 --- /dev/null +++ b/skill/calendar-scheduling/SKILL.md @@ -0,0 +1,69 @@ +--- +name: calendar-scheduling +description: "Calendar and time management with Proton Calendar integration. Use when: (1) checking schedule, (2) blocking focus time, (3) scheduling meetings, (4) time-based planning, (5) managing availability. Triggers: calendar, schedule, when am I free, block time, meeting, availability, what's my day look like." +compatibility: opencode +--- + +# Calendar & Scheduling + +Time management and calendar integration for Proton Calendar. + +## Status: Stub + +This skill is a placeholder for future development. Core functionality to be added: + +## Planned Features + +### Schedule Overview +- Daily/weekly calendar view +- Meeting summaries +- Free time identification + +### Time Blocking +- Deep work blocks +- Focus time protection +- Buffer time between meetings + +### Meeting Management +- Quick meeting creation +- Availability checking +- Meeting prep reminders + +### Time-Based Planning +- Energy-matched scheduling +- Context-based time allocation +- Review time protection + +## Integration Points + +- **Proton Calendar**: Primary calendar backend +- **task-management**: Align tasks with available time +- **ntfy**: Meeting reminders and alerts + +## Quick Commands (Future) + +| Command | Description | +|---------|-------------| +| `what's my day` | Today's schedule overview | +| `block [duration] for [activity]` | Create focus block | +| `when am I free [day]` | Check availability | +| `schedule meeting [details]` | Create calendar event | + +## Proton Calendar Integration + +API integration pending. Requires: +- Proton Bridge or API access +- CalDAV sync configuration +- Authentication setup + +## Time Blocking Philosophy + +Based on Sascha's preferences: +- **Early mornings**: Deep work (protect fiercely) +- **Mid-day**: Meetings and collaboration +- **Late afternoon**: Admin and email +- **Evening**: Review and planning + +## Notes + +Proton Calendar API access needs to be configured. Consider CalDAV integration or n8n workflow as bridge. diff --git a/skill/communications/SKILL.md b/skill/communications/SKILL.md new file mode 100644 index 0000000..dcb380f --- /dev/null +++ b/skill/communications/SKILL.md @@ -0,0 +1,78 @@ +--- +name: communications +description: "Email and communication management with Proton Mail integration. Use when: (1) drafting emails, (2) managing follow-ups, (3) communication tracking, (4) message templates, (5) inbox management. Triggers: email, draft, reply, follow up, message, inbox, communication, respond to." +compatibility: opencode +--- + +# Communications + +Email and communication management for Proton Mail. + +## Status: Stub + +This skill is a placeholder for future development. Core functionality to be added: + +## Planned Features + +### Email Drafting +- Context-aware draft generation +- Tone matching (formal/casual) +- Template-based responses + +### Follow-up Tracking +- Waiting-for list management +- Follow-up reminders +- Response tracking + +### Inbox Management +- Priority sorting +- Quick triage assistance +- Archive recommendations + +### Communication Templates +- Common response patterns +- Meeting request templates +- Status update formats + +## Integration Points + +- **Proton Mail**: Primary email backend +- **task-management**: Convert emails to tasks +- **ntfy**: Important email alerts +- **n8n**: Automation workflows + +## Quick Commands (Future) + +| Command | Description | +|---------|-------------| +| `draft reply to [context]` | Generate email draft | +| `follow up on [topic]` | Check follow-up status | +| `email template [type]` | Use saved template | +| `inbox summary` | Overview of pending emails | + +## Proton Mail Integration + +API integration pending. Options: +- Proton Bridge (local IMAP/SMTP) +- n8n with email triggers +- Manual copy/paste workflow initially + +## Communication Style Guide + +Based on Sascha's profile: +- **Tone**: Professional but approachable +- **Length**: Concise, get to the point +- **Structure**: Clear ask/action at the top +- **Follow-up**: Set clear expectations + +## Email Templates (Future) + +- Meeting request +- Status update +- Delegation request +- Follow-up reminder +- Thank you / acknowledgment + +## Notes + +Start with manual draft assistance. Proton Mail API integration can be added via n8n workflow when ready. diff --git a/skill/knowledge-management/SKILL.md b/skill/knowledge-management/SKILL.md new file mode 100644 index 0000000..5ac8e44 --- /dev/null +++ b/skill/knowledge-management/SKILL.md @@ -0,0 +1,60 @@ +--- +name: knowledge-management +description: "Knowledge base and note management with Anytype. Use when: (1) saving information for later, (2) organizing notes and references, (3) finding past notes, (4) building knowledge connections, (5) managing documentation. Triggers: save this, note, remember, knowledge base, where did I put, find my notes on, documentation." +compatibility: opencode +--- + +# Knowledge Management + +Note capture and knowledge organization using Anytype as the backend. + +## Status: Stub + +This skill is a placeholder for future development. Core functionality to be added: + +## Planned Features + +### Quick Note Capture +- Minimal friction capture to Anytype +- Auto-tagging based on content +- Link to related notes + +### Knowledge Retrieval +- Semantic search across notes +- Tag-based filtering +- Connection discovery + +### Resource Organization +- PARA Resources category management +- Topic clustering +- Archive maintenance + +### Documentation Management +- Technical docs organization +- Version tracking +- Cross-reference linking + +## Integration Points + +- **Anytype**: Primary storage (Resources type) +- **task-management**: Link notes to projects/areas +- **research**: Save research findings + +## Quick Commands (Future) + +| Command | Description | +|---------|-------------| +| `note: [content]` | Quick capture | +| `find notes on [topic]` | Search knowledge base | +| `link [note] to [note]` | Create connection | +| `organize [tag/topic]` | Cluster related notes | + +## Anytype Types + +- `note` - Quick captures +- `resource` - Organized reference material +- `document` - Formal documentation + +## Notes + +Expand based on actual note-taking patterns. Consider integration with mem0-memory skill for AI-assisted recall. diff --git a/skill/mem0-memory/SKILL.md b/skill/mem0-memory/SKILL.md new file mode 100644 index 0000000..9725255 --- /dev/null +++ b/skill/mem0-memory/SKILL.md @@ -0,0 +1,166 @@ +--- +name: mem0-memory +description: "Store and retrieve memories using Mem0 REST API. Use when: (1) storing information for future recall, (2) searching past conversations or facts, (3) managing user/agent memory contexts, (4) building conversational AI with persistent memory. Triggers on keywords like 'remember', 'recall', 'memory', 'store for later', 'what did I say about'." +compatibility: opencode +--- + +# Mem0 Memory + +Store and retrieve memories via Mem0 REST API at `http://localhost:8000`. + +## Quick Reference + +| Operation | Method | Endpoint | +| ----------------- | ------ | --------------------- | +| Store memory | POST | `/memories` | +| Search memories | POST | `/search` | +| Get all memories | GET | `/memories?user_id=X` | +| Get single memory | GET | `/memories/{id}` | +| Update memory | PUT | `/memories/{id}` | +| Delete memory | DELETE | `/memories/{id}` | +| Delete all | DELETE | `/memories?user_id=X` | + +## Core Operations + +### Store a Memory + +```bash +curl -X POST http://localhost:8000/memories \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [ + {"role": "user", "content": "I prefer dark mode in all apps"}, + {"role": "assistant", "content": "Noted, you prefer dark mode."} + ], + "user_id": "user123" + }' +``` + +**Required**: `messages` array with `role` (user/assistant) and `content`. +**Optional**: `user_id`, `agent_id`, `run_id`, `metadata` object. + +### Search Memories + +```bash +curl -X POST http://localhost:8000/search \ + -H "Content-Type: application/json" \ + -d '{ + "query": "What are my UI preferences?", + "user_id": "user123" + }' +``` + +**Required**: `query` string. +**Optional**: `user_id`, `agent_id`, `run_id`, `filters` object. + +### Retrieve All Memories + +```bash +curl "http://localhost:8000/memories?user_id=user123" +``` + +Filter by `user_id`, `agent_id`, or `run_id`. + +### Get Single Memory + +```bash +curl http://localhost:8000/memories/{memory_id} +``` + +### Update Memory + +```bash +curl -X PUT http://localhost:8000/memories/{memory_id} \ + -H "Content-Type: application/json" \ + -d '{"content": "Updated preference: light mode"}' +``` + +### Delete Memory + +```bash +curl -X DELETE http://localhost:8000/memories/{memory_id} +``` + +### Delete All Memories + +```bash +curl -X DELETE "http://localhost:8000/memories?user_id=user123" +``` + +## Identity Scopes + +Mem0 supports three identity scopes for organizing memories: + +| Scope | Use Case | +| ---------- | ---------------------------------------- | +| `user_id` | Per-user memories across sessions | +| `agent_id` | Per-agent memories (shared across users) | +| `run_id` | Per-session memories (temporary) | + +Combine scopes for fine-grained control: + +```json +{ + "messages": [...], + "user_id": "alice", + "agent_id": "support-bot", + "run_id": "session-456" +} +``` + +## Workflow Patterns + +### Pattern 1: Remember User Preferences + +User says "Remember I like X" -> Store with their user_id: + +```bash +curl -X POST http://localhost:8000/memories \ + -d '{"messages":[{"role":"user","content":"Remember I like dark mode"}], "user_id":"USER_ID"}' +``` + +### Pattern 2: Recall Past Context + +User asks "What did I tell you about X?" -> Search: + +```bash +curl -X POST http://localhost:8000/search \ + -d '{"query":"dark mode preferences", "user_id":"USER_ID"}' +``` + +### Pattern 3: Session Memory + +Store conversation context for current session only: + +```bash +curl -X POST http://localhost:8000/memories \ + -d '{"messages":[...], "run_id":"SESSION_ID"}' +``` + +## Response Format + +Memory objects include: + +```json +{ + "id": "mem_abc123", + "memory": "User prefers dark mode", + "user_id": "user123", + "created_at": "2025-12-31T12:00:00Z", + "updated_at": "2025-12-31T12:00:00Z" +} +``` + +Search returns array of matching memories with relevance scores. + +## Health Check + +Verify API is running: + +```bash +curl http://localhost:8000/health +``` + +## API Reference + +See [references/api_reference.md](references/api_reference.md) for complete OpenAPI schema. diff --git a/skill/mem0-memory/references/api_reference.md b/skill/mem0-memory/references/api_reference.md new file mode 100644 index 0000000..e60ffa0 --- /dev/null +++ b/skill/mem0-memory/references/api_reference.md @@ -0,0 +1,202 @@ +# Mem0 REST API Reference + +Base URL: `http://localhost:8000` + +## Endpoints + +### Health Check +``` +GET /health +``` +Returns 200 if server is running. + +--- + +### Create Memories +``` +POST /memories +Content-Type: application/json +``` + +**Request Body (MemoryCreate)**: +```json +{ + "messages": [ + {"role": "string", "content": "string"} + ], + "user_id": "string | null", + "agent_id": "string | null", + "run_id": "string | null", + "metadata": {"key": "value"} | null +} +``` + +- `messages` (required): Array of Message objects + - `role`: Role of message sender ("user" or "assistant") + - `content`: Message content string +- `user_id`: Optional user identifier +- `agent_id`: Optional agent identifier +- `run_id`: Optional session/run identifier +- `metadata`: Optional key-value metadata + +--- + +### Get All Memories +``` +GET /memories +``` + +**Query Parameters**: +- `user_id` (string, optional): Filter by user +- `agent_id` (string, optional): Filter by agent +- `run_id` (string, optional): Filter by run/session + +--- + +### Get Single Memory +``` +GET /memories/{memory_id} +``` + +**Path Parameters**: +- `memory_id` (string, required): Memory ID + +--- + +### Update Memory +``` +PUT /memories/{memory_id} +Content-Type: application/json +``` + +**Path Parameters**: +- `memory_id` (string, required): Memory ID + +**Request Body**: Object with updated fields + +--- + +### Delete Memory +``` +DELETE /memories/{memory_id} +``` + +**Path Parameters**: +- `memory_id` (string, required): Memory ID + +--- + +### Delete All Memories +``` +DELETE /memories +``` + +**Query Parameters**: +- `user_id` (string, optional): Delete for specific user +- `agent_id` (string, optional): Delete for specific agent +- `run_id` (string, optional): Delete for specific run + +--- + +### Search Memories +``` +POST /search +Content-Type: application/json +``` + +**Request Body (SearchRequest)**: +```json +{ + "query": "string", + "user_id": "string | null", + "agent_id": "string | null", + "run_id": "string | null", + "filters": {"key": "value"} | null +} +``` + +- `query` (required): Search query string +- `user_id`: Optional user filter +- `agent_id`: Optional agent filter +- `run_id`: Optional run filter +- `filters`: Optional additional filters + +--- + +### Get Memory History +``` +GET /memories/{memory_id}/history +``` + +**Path Parameters**: +- `memory_id` (string, required): Memory ID + +Returns version history for a memory. + +--- + +### Configure Mem0 +``` +POST /configure +Content-Type: application/json +``` + +**Request Body**: Configuration object (varies by setup) + +--- + +### Reset All Memories +``` +POST /reset +``` + +**Warning**: Completely resets all stored memories. + +--- + +## Error Responses + +**422 Validation Error**: +```json +{ + "detail": [ + { + "loc": ["body", "field_name"], + "msg": "error message", + "type": "error_type" + } + ] +} +``` + +## Data Schemas + +### Message +```json +{ + "role": "string", + "content": "string" +} +``` + +### MemoryCreate +```json +{ + "messages": [Message], + "user_id": "string | null", + "agent_id": "string | null", + "run_id": "string | null", + "metadata": "object | null" +} +``` + +### SearchRequest +```json +{ + "query": "string", + "user_id": "string | null", + "agent_id": "string | null", + "run_id": "string | null", + "filters": "object | null" +} +``` diff --git a/skill/reflection/SKILL.md b/skill/reflection/SKILL.md new file mode 100644 index 0000000..853b873 --- /dev/null +++ b/skill/reflection/SKILL.md @@ -0,0 +1,262 @@ +--- +name: reflection +description: "Conversation analysis to improve skills based on user feedback. Use when: (1) user explicitly requests reflection ('reflect', 'improve', 'learn from this'), (2) reflection mode is ON and clear correction signals detected, (3) user asks to analyze skill performance. Triggers: reflect, improve, learn, analyze conversation, skill feedback. Toggle with /reflection on|off command." +compatibility: opencode +--- + +# Reflection + +Analyze conversations to detect user corrections, preferences, and observations, then propose skill improvements. + +## Reflection Mode + +**Toggle:** Use `/reflection on|off|status` command + +**When mode is ON:** +- Actively monitor for correction signals during conversation +- Auto-suggest reflection when clear patterns detected +- Proactively offer skill improvements + +**When mode is OFF (default):** +- Only trigger on explicit user request +- No automatic signal detection + +## Core Workflow + +When triggered, follow this sequence: + +### 1. Identify Target Skill + +**If skill explicitly mentioned:** +``` +User: "Reflect on the task-management skill" +β†’ Target: task-management +``` + +**If not specified, ask:** +``` +"Which skill should I analyze? Recent skills used: [list from session]" +``` + +### 2. Scan Conversation + +Use session tools to analyze the current conversation: + +```bash +# Read current session messages +session_read --session_id [current] --include_todos true +``` + +**Analyze for:** +- When target skill was used +- User responses after skill usage +- Correction signals (see references/signal-patterns.md) +- Workflow patterns +- Repeated interactions + +### 3. Classify Findings + +Rate each finding using 3-tier system (see references/rating-guidelines.md): + +**HIGH (Explicit Constraints):** +- Direct corrections: "No, don't do X" +- Explicit rules: "Always/Never..." +- Repeated violations + +**MEDIUM (Preferences & Patterns):** +- Positive reinforcement: "That's perfect" +- Adopted patterns (used 3+ times) +- Workflow optimizations + +**LOW (Observations):** +- Contextual insights +- Tentative patterns +- Environmental preferences + +### 4. Read Target Skill + +Before proposing changes, read the current skill implementation: + +```bash +# Read the skill file +read skill/[target-skill]/SKILL.md + +# Check for references if needed +glob pattern="**/*.md" path=skill/[target-skill]/references/ +``` + +### 5. Generate Proposals + +**For each finding, create:** + +**HIGH findings:** +- Specific constraint text to add +- Location in skill where it should go +- Exact wording for the rule + +**MEDIUM findings:** +- Preferred approach description +- Suggested default behavior +- Optional: code example or workflow update + +**LOW findings:** +- Observation description +- Potential future action +- Context for when it might apply + +### 6. User Confirmation + +**Present findings in structured format:** + +```markdown +## Reflection Analysis: [Skill Name] + +### HIGH Priority (Constraints) +1. **[Finding Title]** + - Signal: [What user said/did] + - Proposed: [Specific change to skill] + +### MEDIUM Priority (Preferences) +1. **[Finding Title]** + - Signal: [What user said/did] + - Proposed: [Suggested update] + +### LOW Priority (Observations) +[List observations] + +--- + +Approve changes to [skill name]? (yes/no/selective) +``` + +### 7. Apply Changes or Document + +**If user approves (yes):** +1. Edit skill/[target-skill]/SKILL.md with proposed changes +2. Confirm: "Updated [skill name] with [N] improvements" +3. Show diff of changes + +**If user selects some (selective):** +1. Ask which findings to apply +2. Edit skill with approved changes only +3. Write rejected findings to OBSERVATIONS.md + +**If user declines (no):** +1. Create/append to skill/[target-skill]/OBSERVATIONS.md +2. Document all findings with full context +3. Confirm: "Documented [N] observations in OBSERVATIONS.md for future reference" + +## OBSERVATIONS.md Format + +When writing observations file: + +```markdown +# Observations for [Skill Name] + +Generated: [Date] +From conversation: [Session ID if available] + +## HIGH: [Finding Title] +**Context:** [Which scenario/workflow] +**Signal:** [User's exact words or repeated pattern] +**Constraint:** [The rule to follow] +**Proposed Change:** [Exact text to add to skill] +**Status:** Pending user approval + +--- + +## MEDIUM: [Finding Title] +**Context:** [Which scenario/workflow] +**Signal:** [What indicated this preference] +**Preference:** [The preferred approach] +**Rationale:** [Why this works well] +**Proposed Change:** [Suggested skill update] +**Status:** Pending user approval + +--- + +## LOW: [Observation Title] +**Context:** [Which scenario/workflow] +**Signal:** [What was noticed] +**Observation:** [The pattern or insight] +**Potential Action:** [Possible future improvement] +**Status:** Noted for future consideration +``` + +## Signal Detection Patterns + +Key patterns to watch for (detailed in references/signal-patterns.md): + +**Explicit corrections:** +- "No, that's wrong..." +- "Actually, you should..." +- "Don't do X, do Y instead" + +**Repeated clarifications:** +- User explains same thing multiple times +- Same mistake corrected across sessions + +**Positive patterns:** +- "Perfect, keep doing it this way" +- User requests same approach repeatedly +- "That's exactly what I needed" + +**Workflow corrections:** +- "You skipped step X" +- "Wrong order" +- "You should have done Y first" + +## Usage Examples + +### Example 1: Post-Skill Usage + +``` +User: "Reflect on how the task-management skill performed" + +Agent: +1. Read current session +2. Find all task-management skill invocations +3. Analyze user responses afterward +4. Read skill/task-management/SKILL.md +5. Present findings with confirmation prompt +``` + +### Example 2: User-Prompted Learning + +``` +User: "Learn from this conversation - I had to correct you several times" + +Agent: +1. Ask which skill to analyze (if multiple used) +2. Scan full conversation for correction signals +3. Classify by severity (HIGH/MEDIUM/LOW) +4. Propose changes with confirmation +``` + +### Example 3: Detected Signals + +``` +# During conversation, user corrects workflow twice +User: "No, run tests BEFORE committing, not after" +[later] +User: "Again, tests first, then commit" + +# Later when user says "reflect" or at end of session +Agent detects: HIGH priority constraint for relevant skill +``` + +## References + +- **signal-patterns.md** - Comprehensive list of correction patterns to detect +- **rating-guidelines.md** - Decision tree for classifying findings (HIGH/MEDIUM/LOW) + +Load these when analyzing conversations for detailed pattern matching and classification logic. + +## Important Constraints + +1. **Never edit skills without user approval** - Always confirm first +2. **Read the skill before proposing changes** - Avoid suggesting what already exists +3. **Preserve existing structure** - Match the skill's current organization and style +4. **Be specific** - Vague observations aren't actionable +5. **Full conversation scan** - Don't just analyze last few messages +6. **Context matters** - Include why the finding matters, not just what was said diff --git a/skill/reflection/references/command-usage.md b/skill/reflection/references/command-usage.md new file mode 100644 index 0000000..7479473 --- /dev/null +++ b/skill/reflection/references/command-usage.md @@ -0,0 +1,85 @@ +# Reflection Command Usage + +## Toggle Commands + +### Enable Reflection Mode +``` +/reflection on +``` + +**Effect:** Enables automatic detection of correction signals during conversation. I will proactively suggest skill improvements when patterns are detected. + +### Disable Reflection Mode +``` +/reflection off +``` + +**Effect:** Disables automatic detection. Reflection only occurs when explicitly requested. + +### Check Status +``` +/reflection status +``` + +**Effect:** Shows whether reflection mode is currently on or off. + +## Behavior by Mode + +### Mode: ON + +**Automatic triggers:** +- User corrects same thing 2+ times β†’ Offer reflection +- Explicit corrections detected ("No, do it this way") β†’ Ask "Should I reflect on [skill]?" +- After skill usage with clear signals β†’ Proactive suggestion + +**Example:** +``` +User: "No, run tests before committing, not after" +[conversation continues] +User: "Again, tests must run first" + +Agent: "I notice you've corrected the workflow order twice. +Should I reflect on the relevant skill to add this constraint?" +``` + +### Mode: OFF (Default) + +**Manual triggers only:** +- User says "reflect", "improve", "learn from this" +- User explicitly asks to analyze skill + +**Example:** +``` +User: "Reflect on the task-management skill" + +Agent: [Runs full reflection workflow] +``` + +## Session Persistence + +Reflection mode is **session-scoped**: +- Setting persists for current conversation +- Resets to OFF for new sessions +- Use `/reflection on` at session start if desired + +## When to Use Each Mode + +### Use ON when: +- Actively developing/tuning a new skill +- Testing skill behavior with real usage +- Learning preferences for a new domain +- Want proactive improvement suggestions + +### Use OFF when: +- Skills are stable and working well +- Don't want interruptions +- Only need reflection occasionally +- Prefer manual control + +## Integration with Skill + +The reflection skill checks conversation context for mode state: +- Looks for recent `/reflection on` or `/reflection off` commands +- Defaults to OFF if no command found +- Auto-triggers only when ON and signals detected +- Always responds to explicit "reflect" requests regardless of mode diff --git a/skill/reflection/references/rating-guidelines.md b/skill/reflection/references/rating-guidelines.md new file mode 100644 index 0000000..d3e135b --- /dev/null +++ b/skill/reflection/references/rating-guidelines.md @@ -0,0 +1,126 @@ +# Rating Guidelines + +How to classify findings from conversation analysis. + +## Rating Criteria + +### High Priority (Explicit Constraints) + +**Definition:** Direct corrections or explicit rules that MUST be followed. + +**Characteristics:** +- User explicitly states a constraint +- Correction of incorrect behavior +- Safety or correctness requirements +- Repeated violations cause frustration + +**Examples:** +- "Never commit without asking first" +- "Always use TypeScript, not JavaScript" +- "You forgot to run tests before committing" +- "Don't use global state" + +**Action:** These become hard constraints in the skill documentation. + +**Format in OBSERVATIONS.md:** +```markdown +## HIGH: [Constraint Title] +**Context:** [Which skill/scenario] +**Signal:** [What the user said/did] +**Constraint:** [The specific rule to follow] +**Proposed Change:** [Exact text to add to skill] +``` + +### Medium Priority (Preferences & Patterns) + +**Definition:** Approaches that work well or user preferences that improve workflow. + +**Characteristics:** +- Positive reinforcement from user +- Patterns that user adopts repeatedly +- Workflow optimizations +- Style preferences + +**Examples:** +- "That output format is perfect, use that" +- User consistently requests bullet points over paragraphs +- User prefers parallel tool execution +- "I like how you broke that down" + +**Action:** These become preferred approaches or default patterns in skills. + +**Format in OBSERVATIONS.md:** +```markdown +## MEDIUM: [Preference Title] +**Context:** [Which skill/scenario] +**Signal:** [What the user said/did] +**Preference:** [The preferred approach] +**Rationale:** [Why this works well] +**Proposed Change:** [Suggested skill update] +``` + +### Low Priority (Observations) + +**Definition:** Contextual insights, minor preferences, or exploratory findings. + +**Characteristics:** +- Environmental context +- Tentative patterns (need more data) +- Nice-to-have improvements +- Exploratory feedback + +**Examples:** +- User tends to work on deep tasks in morning +- User sometimes asks for alternative approaches +- User occasionally needs extra context +- Formatting preferences for specific outputs + +**Action:** Document for future consideration. May become higher priority with more evidence. + +**Format in OBSERVATIONS.md:** +```markdown +## LOW: [Observation Title] +**Context:** [Which skill/scenario] +**Signal:** [What was noticed] +**Observation:** [The pattern or insight] +**Potential Action:** [Possible future improvement] +``` + +## Classification Decision Tree + +``` +1. Did user explicitly correct behavior? + YES β†’ HIGH + NO β†’ Continue + +2. Did user express satisfaction with approach? + YES β†’ Was it repeated/adopted as pattern? + YES β†’ MEDIUM + NO β†’ LOW + NO β†’ Continue + +3. Is this a repeated pattern (3+ instances)? + YES β†’ MEDIUM + NO β†’ LOW + +4. Is this exploratory/tentative? + YES β†’ LOW +``` + +## Edge Cases + +**Implicit corrections (repeated fixes by user):** +- First instance: LOW (observe) +- Second instance: MEDIUM (pattern emerging) +- Third instance: HIGH (clear constraint) + +**Contradictory signals:** +- Document both +- Note the contradiction +- Mark for user clarification + +**Context-dependent preferences:** +- Rate based on specificity +- Document the context clearly +- If context is always present: MEDIUM +- If context is occasional: LOW diff --git a/skill/reflection/references/signal-patterns.md b/skill/reflection/references/signal-patterns.md new file mode 100644 index 0000000..bb02ac0 --- /dev/null +++ b/skill/reflection/references/signal-patterns.md @@ -0,0 +1,79 @@ +# User Correction Signal Patterns + +Patterns that indicate the user is correcting or refining the agent's behavior. + +## High Priority Signals (Explicit Corrections) + +**Direct corrections:** +- "No, that's not right..." +- "Actually, you should..." +- "Don't do X, instead do Y" +- "That's incorrect..." +- "You misunderstood..." + +**Explicit instructions:** +- "Always..." / "Never..." +- "From now on..." +- "Make sure to..." +- "Remember to..." + +**Repeated clarifications:** +- User re-explains the same point multiple times +- User provides same instruction in different words +- User corrects same mistake in multiple sessions + +**Workflow corrections:** +- "You skipped step X" +- "You should have done Y first" +- "That's the wrong order" + +## Medium Priority Signals (Effective Patterns) + +**Positive reinforcement:** +- "That's perfect" +- "Exactly what I needed" +- "Great, keep doing it this way" +- "Yes, that's the right approach" + +**User adopts the pattern:** +- User requests same workflow multiple times +- User references previous successful interaction +- User asks to "do it like last time" + +**Implicit preferences:** +- User consistently asks for specific format +- User regularly requests certain tools/approaches +- Patterns in how user phrases requests + +## Low Priority Signals (Observations) + +**General feedback:** +- "Hmm, interesting..." +- "I see..." +- Neutral acknowledgments + +**Exploratory questions:** +- "What if we tried..." +- "Could you also..." +- "I wonder if..." + +**Context clues:** +- Time of day patterns +- Task batching preferences +- Communication style preferences + +**Environment signals:** +- Tools user prefers +- File organization patterns +- Workflow preferences + +## Anti-Patterns (Not Corrections) + +**Questions about capabilities:** +- "Can you do X?" (not a correction, just inquiry) + +**Exploration:** +- "Let's try something different" (exploration, not correction) + +**Context changes:** +- "Now let's work on Y" (topic shift, not correction) diff --git a/skill/research/SKILL.md b/skill/research/SKILL.md new file mode 100644 index 0000000..1a611bc --- /dev/null +++ b/skill/research/SKILL.md @@ -0,0 +1,54 @@ +--- +name: research +description: "Research and investigation workflows. Use when: (1) researching technologies or tools, (2) investigating best practices, (3) comparing solutions, (4) gathering information for decisions, (5) deep-diving into topics. Triggers: research, investigate, explore, compare, learn about, what are best practices for, how does X work." +compatibility: opencode +--- + +# Research + +Research and investigation workflows for informed decision-making. + +## Status: Stub + +This skill is a placeholder for future development. Core functionality to be added: + +## Planned Features + +### Investigation Workflow +- Multi-source research (web, docs, code) +- Source credibility assessment +- Summary with drill-down capability + +### Technology Evaluation +- Feature comparison matrices +- Pros/cons analysis +- Fit-for-purpose assessment + +### Best Practices Discovery +- Industry standards lookup +- Implementation patterns +- Common pitfalls + +### Learning Path Generation +- Topic breakdown +- Resource recommendations +- Progress tracking + +## Integration Points + +- **Anytype**: Save research findings to Resources +- **Web Search**: Primary research source +- **librarian agent**: External documentation lookup + +## Quick Commands (Future) + +| Command | Description | +|---------|-------------| +| `research [topic]` | Start research session | +| `compare [A] vs [B]` | Feature comparison | +| `best practices [topic]` | Lookup standards | +| `learn [topic]` | Generate learning path | + +## Notes + +Expand this skill based on actual research patterns that emerge from usage. diff --git a/skill/skill-creator/SKILL.md b/skill/skill-creator/SKILL.md new file mode 100644 index 0000000..e005837 --- /dev/null +++ b/skill/skill-creator/SKILL.md @@ -0,0 +1,387 @@ +--- +name: skill-creator +description: (opencode - Skill) Guide for creating effective Opencode Agent Skills. Use this when users want to create a new skill (or update an existing skill) that extends Opencode's capabilities with specialized knowledge, workflows, or tool integrations. +compatibility: opencode +--- + +# Skill Creator + +This skill provides guidance for creating effective Opencode Agent Skills. + +## About Skills + +Skills are modular, self-contained packages that extend Opencode's capabilities by providing +specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific +domains or tasksβ€”they transform Opencode from a general-purpose agent into a specialized agent +equipped with procedural knowledge that no model can fully possess. + +### What Skills Provide + +1. Specialized workflows - Multi-step procedures for specific domains +2. Tool integrations - Instructions for working with specific file formats or APIs +3. Domain expertise - Company-specific knowledge, schemas, business logic +4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks + +## Core Principles + +### Concise is Key + +The context window is a public good. Skills share the context window with everything else Opencode needs: system prompt, conversation history, other Skills' metadata, and the actual user request. + +**Default assumption: Opencode is already very smart.** Only add context Opencode doesn't already have. Challenge each piece of information: "Does Opencode really need this explanation?" and "Does this paragraph justify its token cost?" + +Prefer concise examples over verbose explanations. + +### Set Appropriate Degrees of Freedom + +Match the level of specificity to the task's fragility and variability: + +**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach. + +**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior. + +**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed. + +Think of Opencode as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom). + +### Anatomy of a Skill + +Every skill consists of a required SKILL.md file and optional bundled resources: + +``` +skill-name/ +β”œβ”€β”€ SKILL.md (required) +β”‚ β”œβ”€β”€ YAML frontmatter metadata (required) +β”‚ β”‚ β”œβ”€β”€ name: (required) +β”‚ β”‚ β”œβ”€β”€ description: (required) +β”‚ β”‚ └── compatibility: opencode (recommended) +β”‚ └── Markdown instructions (required) +└── Bundled Resources (optional) + β”œβ”€β”€ scripts/ - Executable code (Python/Bash/etc.) + β”œβ”€β”€ references/ - Documentation intended to be loaded into context as needed + └── assets/ - Files used in output (templates, icons, fonts, etc.) +``` + +#### SKILL.md (required) + +Every SKILL.md consists of: + +- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Opencode reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used. +- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all). + +#### Bundled Resources (optional) + +##### Scripts (`scripts/`) + +Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten. + +- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed +- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks +- **Benefits**: Token efficient, deterministic, may be executed without loading into context +- **Note**: Scripts may still need to be read by Opencode for patching or environment-specific adjustments + +##### References (`references/`) + +Documentation and reference material intended to be loaded as needed into context to inform Opencode's process and thinking. + +- **When to include**: For documentation that Opencode should reference while working +- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications +- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides +- **Benefits**: Keeps SKILL.md lean, loaded only when Opencode determines it's needed +- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md +- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skillβ€”this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. + +##### Assets (`assets/`) + +Files not intended to be loaded into context, but rather used within the output Opencode produces. + +- **When to include**: When the skill needs files that will be used in the final output +- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography +- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified +- **Benefits**: Separates output resources from documentation, enables Opencode to use files without loading them into context + +#### What to Not Include in a Skill + +A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including: + +- README.md +- INSTALLATION_GUIDE.md +- QUICK_REFERENCE.md +- CHANGELOG.md +- etc. + +The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion. + +### Progressive Disclosure Design Principle + +Skills use a three-level loading system to manage context efficiently: + +1. **Metadata (name + description)** - Always in context (~100 words) +2. **SKILL.md body** - When skill triggers (<5k words) +3. **Bundled resources** - As needed by Opencode (Unlimited because scripts can be executed without reading into context window) + +#### Progressive Disclosure Patterns + +Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them. + +**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files. + +**Pattern 1: High-level guide with references** + +```markdown +# PDF Processing + +## Quick start + +Extract text with pdfplumber: +[code example] + +## Advanced features + +- **Form filling**: See [FORMS.md](FORMS.md) for complete guide +- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods +- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns +``` + +Opencode loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed. + +**Pattern 2: Domain-specific organization** + +For Skills with multiple domains, organize content by domain to avoid loading irrelevant context: + +``` +bigquery-skill/ +β”œβ”€β”€ SKILL.md (overview and navigation) +└── reference/ + β”œβ”€β”€ finance.md (revenue, billing metrics) + β”œβ”€β”€ sales.md (opportunities, pipeline) + β”œβ”€β”€ product.md (API usage, features) + └── marketing.md (campaigns, attribution) +``` + +When a user asks about sales metrics, Opencode only reads sales.md. + +Similarly, for skills supporting multiple frameworks or variants, organize by variant: + +``` +cloud-deploy/ +β”œβ”€β”€ SKILL.md (workflow + provider selection) +└── references/ + β”œβ”€β”€ aws.md (AWS deployment patterns) + β”œβ”€β”€ gcp.md (GCP deployment patterns) + └── azure.md (Azure deployment patterns) +``` + +When the user chooses AWS, Opencode only reads aws.md. + +**Pattern 3: Conditional details** + +Show basic content, link to advanced content: + +```markdown +# DOCX Processing + +## Creating documents + +Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md). + +## Editing documents + +For simple edits, modify the XML directly. + +**For tracked changes**: See [REDLINING.md](REDLINING.md) +**For OOXML details**: See [OOXML.md](OOXML.md) +``` + +Opencode reads REDLINING.md or OOXML.md only when the user needs those features. + +**Important guidelines:** + +- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md. +- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Opencode can see the full scope when previewing. + +## Skill Creation Process + +Skill creation involves these steps: + +1. Understand the skill with concrete examples +2. Plan reusable skill contents (scripts, references, assets) +3. Initialize the skill (run init_skill.py) +4. Edit the skill (implement resources and write SKILL.md) +5. Package the skill (optional - for distribution) +6. Iterate based on real usage + +Follow these steps in order, skipping only if there is a clear reason why they are not applicable. + +### Step 1: Understanding the Skill with Concrete Examples + +Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill. + +To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback. + +For example, when building an image-editor skill, relevant questions include: + +- "What functionality should the image-editor skill support? Editing, rotating, anything else?" +- "Can you give some examples of how this skill would be used?" +- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?" +- "What would a user say that should trigger this skill?" + +To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness. + +Conclude this step when there is a clear sense of the functionality the skill should support. + +### Step 2: Planning the Reusable Skill Contents + +To turn concrete examples into an effective skill, analyze each example by: + +1. Considering how to execute on the example from scratch +2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly + +Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows: + +1. Rotating a PDF requires re-writing the same code each time +2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill + +Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows: + +1. Writing a frontend webapp requires the same boilerplate HTML/React each time +2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill + +Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows: + +1. Querying BigQuery requires re-discovering the table schemas and relationships each time +2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill + +To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. + +### Step 3: Initializing the Skill + +At this point, it is time to actually create the skill. + +Skip this step only if the skill being developed already exists, and iteration is needed. In this case, continue to the next step. + +When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable. + +Usage: + +```bash +scripts/init_skill.py --path +``` + +For Opencode skills, use: + +```bash +scripts/init_skill.py --path ~/.config/opencode/skill +``` + +The script: + +- Creates the skill directory at the specified path +- Generates a SKILL.md template with proper frontmatter and TODO placeholders +- Creates example resource directories: `scripts/`, `references/`, and `assets/` +- Adds example files in each directory that can be customized or deleted + +After initialization, customize or remove the generated SKILL.md and example files as needed. + +### Step 4: Edit the Skill + +When editing the (newly-generated or existing) skill, remember that the skill is being created for Opencode to use. Include information that would be beneficial and non-obvious to Opencode. Consider what procedural knowledge, domain-specific details, or reusable assets would help Opencode execute these tasks more effectively. + +#### Learn Proven Design Patterns + +Consult these helpful guides based on your skill's needs: + +- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic +- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns + +These files contain established best practices for effective skill design. + +#### Start with Reusable Skill Contents + +To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`. + +Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion. + +Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them. + +#### Update SKILL.md + +**Writing Guidelines:** Always use imperative/infinitive form. + +##### Frontmatter + +Write the YAML frontmatter with `name`, `description`, and `compatibility`: + +- `name`: The skill name +- `description`: This is the primary triggering mechanism for your skill, and helps Opencode understand when to use the skill. + - Include both what the Skill does and specific triggers/contexts for when to use it. + - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Opencode. + - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Opencode needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" +- `compatibility`: Set to "opencode" to indicate this skill is designed for Opencode + +Do not include any other fields in YAML frontmatter unless needed for specific Opencode features. + +##### Body + +Write instructions for using the skill and its bundled resources. + +### Step 5: Packaging a Skill (Optional) + +For Opencode, skills are typically used directly from `~/.config/opencode/skill/` directory and do not need to be packaged. However, if you want to share a skill with others, you can optionally package it. + +The packaging process would create a distributable archive that can be shared: + +```bash +scripts/package_skill.py +``` + +Optional output directory specification: + +```bash +scripts/package_skill.py ./dist +``` + +### Step 6: Iterate + +After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed. + +**Iteration workflow:** + +1. Use the skill on real tasks +2. Notice struggles or inefficiencies +3. Identify how SKILL.md or bundled resources should be updated +4. Implement changes and test again + +## Opencode-Specific Considerations + +When creating skills for Opencode: + +1. **Location**: Skills should be placed in `~/.config/opencode/skill//` +2. **Compatibility**: Add `compatibility: opencode` to the frontmatter +3. **Tools**: Opencode has different tools available compared to Claude Desktop - refer to Opencode's tool documentation when writing workflows +4. **Testing**: Test skills directly in Opencode by invoking them naturally in conversation or using the skill loader + +## Quick Reference + +**Skill directory structure:** +``` +~/.config/opencode/skill/ +└── your-skill-name/ + β”œβ”€β”€ SKILL.md (required) + β”œβ”€β”€ scripts/ (optional) + β”œβ”€β”€ references/ (optional) + └── assets/ (optional) +``` + +**Minimum SKILL.md:** +```markdown +--- +name: your-skill-name +description: What it does and when to use it +compatibility: opencode +--- + +# Your Skill Name + +[Instructions for Opencode] +``` diff --git a/skill/skill-creator/references/output-patterns.md b/skill/skill-creator/references/output-patterns.md new file mode 100644 index 0000000..3c351a9 --- /dev/null +++ b/skill/skill-creator/references/output-patterns.md @@ -0,0 +1,82 @@ +# Output Patterns + +Use these patterns when skills need to produce consistent, high-quality output. + +## Template Pattern + +Provide templates for output format. Match the level of strictness to your needs. + +**For strict requirements (like API responses or data formats):** + +```markdown +## Report structure + +ALWAYS use this exact template structure: + +# [Analysis Title] + +## Executive summary +[One-paragraph overview of key findings] + +## Key findings +- Finding 1 with supporting data +- Finding 2 with supporting data +- Finding 3 with supporting data + +## Recommendations +1. Specific actionable recommendation +2. Specific actionable recommendation +``` + +**For flexible guidance (when adaptation is useful):** + +```markdown +## Report structure + +Here is a sensible default format, but use your best judgment: + +# [Analysis Title] + +## Executive summary +[Overview] + +## Key findings +[Adapt sections based on what you discover] + +## Recommendations +[Tailor to the specific context] + +Adjust sections as needed for the specific analysis type. +``` + +## Examples Pattern + +For skills where output quality depends on seeing examples, provide input/output pairs: + +```markdown +## Commit message format + +Generate commit messages following these examples: + +**Example 1:** +Input: Added user authentication with JWT tokens +Output: +``` +feat(auth): implement JWT-based authentication + +Add login endpoint and token validation middleware +``` + +**Example 2:** +Input: Fixed bug where dates displayed incorrectly in reports +Output: +``` +fix(reports): correct date formatting in timezone conversion + +Use UTC timestamps consistently across report generation +``` + +Follow this style: type(scope): brief description, then detailed explanation. +``` + +Examples help Opencode understand the desired style and level of detail more clearly than descriptions alone. diff --git a/skill/skill-creator/references/workflows.md b/skill/skill-creator/references/workflows.md new file mode 100644 index 0000000..57ca821 --- /dev/null +++ b/skill/skill-creator/references/workflows.md @@ -0,0 +1,28 @@ +# Workflow Patterns + +## Sequential Workflows + +For complex tasks, break operations into clear, sequential steps. It is often helpful to give Opencode an overview of the process towards the beginning of SKILL.md: + +```markdown +Filling a PDF form involves these steps: + +1. Analyze the form (run analyze_form.py) +2. Create field mapping (edit fields.json) +3. Validate mapping (run validate_fields.py) +4. Fill the form (run fill_form.py) +5. Verify output (run verify_output.py) +``` + +## Conditional Workflows + +For tasks with branching logic, guide Opencode through decision points: + +```markdown +1. Determine the modification type: + **Creating new content?** β†’ Follow "Creation workflow" below + **Editing existing content?** β†’ Follow "Editing workflow" below + +2. Creation workflow: [steps] +3. Editing workflow: [steps] +``` diff --git a/skill/skill-creator/scripts/init_skill.py b/skill/skill-creator/scripts/init_skill.py new file mode 100755 index 0000000..e3c1abd --- /dev/null +++ b/skill/skill-creator/scripts/init_skill.py @@ -0,0 +1,304 @@ +#!/usr/bin/env python3 +""" +Skill Initializer - Creates a new Opencode skill from template + +Usage: + init_skill.py --path + +Examples: + init_skill.py my-new-skill --path ~/.config/opencode/skill + init_skill.py my-api-helper --path .opencode/skill + init_skill.py custom-skill --path /custom/location +""" + +import sys +from pathlib import Path + + +SKILL_TEMPLATE = """--- +name: {skill_name} +description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.] +compatibility: opencode +--- + +# {skill_title} + +## Overview + +[TODO: 1-2 sentences explaining what this skill enables] + +## Structuring This Skill + +[TODO: Choose the structure that best fits this skill's purpose. Common patterns: + +**1. Workflow-Based** (best for sequential processes) +- Works well when there are clear step-by-step procedures +- Example: DOCX skill with "Workflow Decision Tree" β†’ "Reading" β†’ "Creating" β†’ "Editing" +- Structure: ## Overview β†’ ## Workflow Decision Tree β†’ ## Step 1 β†’ ## Step 2... + +**2. Task-Based** (best for tool collections) +- Works well when the skill offers different operations/capabilities +- Example: PDF skill with "Quick Start" β†’ "Merge PDFs" β†’ "Split PDFs" β†’ "Extract Text" +- Structure: ## Overview β†’ ## Quick Start β†’ ## Task Category 1 β†’ ## Task Category 2... + +**3. Reference/Guidelines** (best for standards or specifications) +- Works well for brand guidelines, coding standards, or requirements +- Example: Brand styling with "Brand Guidelines" β†’ "Colors" β†’ "Typography" β†’ "Features" +- Structure: ## Overview β†’ ## Guidelines β†’ ## Specifications β†’ ## Usage... + +**4. Capabilities-Based** (best for integrated systems) +- Works well when the skill provides multiple interrelated features +- Example: Product Management with "Core Capabilities" β†’ numbered capability list +- Structure: ## Overview β†’ ## Core Capabilities β†’ ### 1. Feature β†’ ### 2. Feature... + +Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations). + +Delete this entire "Structuring This Skill" section when done - it's just guidance.] + +## [TODO: Replace with the first main section based on chosen structure] + +[TODO: Add content here. See examples in existing skills: +- Code samples for technical skills +- Decision trees for complex workflows +- Concrete examples with realistic user requests +- References to scripts/templates/references as needed] + +## Resources + +This skill includes example resource directories that demonstrate how to organize different types of bundled resources: + +### scripts/ +Executable code (Python/Bash/etc.) that can be run directly to perform specific operations. + +**Examples from other skills:** +- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation +- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing + +**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations. + +**Note:** Scripts may be executed without loading into context, but can still be read by Opencode for patching or environment adjustments. + +### references/ +Documentation and reference material intended to be loaded into context to inform Opencode's process and thinking. + +**Examples from other skills:** +- Product management: `communication.md`, `context_building.md` - detailed workflow guides +- BigQuery: API reference documentation and query examples +- Finance: Schema documentation, company policies + +**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Opencode should reference while working. + +### assets/ +Files not intended to be loaded into context, but rather used within the output Opencode produces. + +**Examples from other skills:** +- Brand styling: PowerPoint template files (.pptx), logo files +- Frontend builder: HTML/React boilerplate project directories +- Typography: Font files (.ttf, .woff2) + +**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output. + +--- + +**Any unneeded directories can be deleted.** Not every skill requires all three types of resources. +""" + +EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 +""" +Example helper script for {skill_name} + +This is a placeholder script that can be executed directly. +Replace with actual implementation or delete if not needed. + +Example real scripts from other skills: +- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields +- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images +""" + +def main(): + print("This is an example script for {skill_name}") + # TODO: Add actual script logic here + # This could be data processing, file conversion, API calls, etc. + +if __name__ == "__main__": + main() +''' + +EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title} + +This is a placeholder for detailed reference documentation. +Replace with actual reference content or delete if not needed. + +Example real reference docs from other skills: +- product-management/references/communication.md - Comprehensive guide for status updates +- product-management/references/context_building.md - Deep-dive on gathering context +- bigquery/references/ - API references and query examples + +## When Reference Docs Are Useful + +Reference docs are ideal for: +- Comprehensive API documentation +- Detailed workflow guides +- Complex multi-step processes +- Information too lengthy for main SKILL.md +- Content that's only needed for specific use cases + +## Structure Suggestions + +### API Reference Example +- Overview +- Authentication +- Endpoints with examples +- Error codes +- Rate limits + +### Workflow Guide Example +- Prerequisites +- Step-by-step instructions +- Common patterns +- Troubleshooting +- Best practices +""" + +EXAMPLE_ASSET = """# Example Asset File + +This placeholder represents where asset files would be stored. +Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed. + +Asset files are NOT intended to be loaded into context, but rather used within +the output Opencode produces. + +Example asset files from other skills: +- Brand guidelines: logo.png, slides_template.pptx +- Frontend builder: hello-world/ directory with HTML/React boilerplate +- Typography: custom-font.ttf, font-family.woff2 +- Data: sample_data.csv, test_dataset.json + +## Common Asset Types + +- Templates: .pptx, .docx, boilerplate directories +- Images: .png, .jpg, .svg, .gif +- Fonts: .ttf, .otf, .woff, .woff2 +- Boilerplate code: Project directories, starter files +- Icons: .ico, .svg +- Data files: .csv, .json, .xml, .yaml + +Note: This is a text placeholder. Actual assets can be any file type. +""" + + +def title_case_skill_name(skill_name): + """Convert hyphenated skill name to Title Case for display.""" + return ' '.join(word.capitalize() for word in skill_name.split('-')) + + +def init_skill(skill_name, path): + """ + Initialize a new skill directory with template SKILL.md. + + Args: + skill_name: Name of the skill + path: Path where the skill directory should be created + + Returns: + Path to created skill directory, or None if error + """ + # Determine skill directory path + skill_dir = Path(path).resolve() / skill_name + + # Check if directory already exists + if skill_dir.exists(): + print(f"❌ Error: Skill directory already exists: {skill_dir}") + return None + + # Create skill directory + try: + skill_dir.mkdir(parents=True, exist_ok=False) + print(f"βœ… Created skill directory: {skill_dir}") + except Exception as e: + print(f"❌ Error creating directory: {e}") + return None + + # Create SKILL.md from template + skill_title = title_case_skill_name(skill_name) + skill_content = SKILL_TEMPLATE.format( + skill_name=skill_name, + skill_title=skill_title + ) + + skill_md_path = skill_dir / 'SKILL.md' + try: + skill_md_path.write_text(skill_content) + print("βœ… Created SKILL.md") + except Exception as e: + print(f"❌ Error creating SKILL.md: {e}") + return None + + # Create resource directories with example files + try: + # Create scripts/ directory with example script + scripts_dir = skill_dir / 'scripts' + scripts_dir.mkdir(exist_ok=True) + example_script = scripts_dir / 'example.py' + example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) + example_script.chmod(0o755) + print("βœ… Created scripts/example.py") + + # Create references/ directory with example reference doc + references_dir = skill_dir / 'references' + references_dir.mkdir(exist_ok=True) + example_reference = references_dir / 'api_reference.md' + example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) + print("βœ… Created references/api_reference.md") + + # Create assets/ directory with example asset placeholder + assets_dir = skill_dir / 'assets' + assets_dir.mkdir(exist_ok=True) + example_asset = assets_dir / 'example_asset.txt' + example_asset.write_text(EXAMPLE_ASSET) + print("βœ… Created assets/example_asset.txt") + except Exception as e: + print(f"❌ Error creating resource directories: {e}") + return None + + # Print next steps + print(f"\nβœ… Skill '{skill_name}' initialized successfully at {skill_dir}") + print("\nNext steps:") + print("1. Edit SKILL.md to complete the TODO items and update the description") + print("2. Customize or delete the example files in scripts/, references/, and assets/") + print("3. Test the skill by using it in Opencode") + + return skill_dir + + +def main(): + if len(sys.argv) < 4 or sys.argv[2] != '--path': + print("Usage: init_skill.py --path ") + print("\nSkill name requirements:") + print(" - Hyphen-case identifier (e.g., 'data-analyzer')") + print(" - Lowercase letters, digits, and hyphens only") + print(" - Max 64 characters") + print(" - Must match directory name exactly") + print("\nExamples:") + print(" init_skill.py my-new-skill --path ~/.config/opencode/skill") + print(" init_skill.py my-api-helper --path .opencode/skill") + print(" init_skill.py custom-skill --path /custom/location") + sys.exit(1) + + skill_name = sys.argv[1] + path = sys.argv[3] + + print(f"πŸš€ Initializing Opencode skill: {skill_name}") + print(f" Location: {path}") + print() + + result = init_skill(skill_name, path) + + if result: + sys.exit(0) + else: + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/skill/skill-creator/scripts/quick_validate.py b/skill/skill-creator/scripts/quick_validate.py new file mode 100755 index 0000000..4dbda29 --- /dev/null +++ b/skill/skill-creator/scripts/quick_validate.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +""" +Quick validation script for Opencode skills - minimal version +""" + +import sys +import os +import re +import yaml +from pathlib import Path + +def validate_skill(skill_path): + """Basic validation of a skill""" + skill_path = Path(skill_path) + + if not skill_md.exists(): + return False, "SKILL.md not found" + + content = skill_md.read_text() + if not content.startswith('---'): + return False, "No YAML frontmatter found" + + match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) + if not match: + return False, "Invalid frontmatter format" + + frontmatter_text = match.group(1) + + try: + frontmatter = yaml.safe_load(frontmatter_text) + if not isinstance(frontmatter, dict): + return False, "Frontmatter must be a YAML dictionary" + except yaml.YAMLError as e: + return False, f"Invalid YAML in frontmatter: {e}" + + ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'} + + unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES + if unexpected_keys: + return False, ( + f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. " + f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}" + ) + + if 'name' not in frontmatter: + return False, "Missing 'name' in frontmatter" + if 'description' not in frontmatter: + return False, "Missing 'description' in frontmatter" + + name = frontmatter.get('name', '') + if not isinstance(name, str): + return False, f"Name must be a string, got {type(name).__name__}" + name = name.strip() + if name: + if not re.match(r'^[a-z0-9-]+$', name): + return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)" + if name.startswith('-') or name.endswith('-') or '--' in name: + return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens" + if len(name) > 64: + return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters." + + description = frontmatter.get('description', '') + if not isinstance(description, str): + return False, f"Description must be a string, got {type(description).__name__}" + description = description.strip() + if description: + if '<' in description or '>' in description: + return False, "Description cannot contain angle brackets (< or >)" + if len(description) > 1024: + return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters." + + return True, "Skill is valid!" + +if __name__ == "__main__": + if len(sys.argv) != 2: + print("Usage: python quick_validate.py ") + sys.exit(1) + + valid, message = validate_skill(sys.argv[1]) + print(message) + sys.exit(0 if valid else 1) diff --git a/skill/task-management/SKILL.md b/skill/task-management/SKILL.md new file mode 100644 index 0000000..df2fa23 --- /dev/null +++ b/skill/task-management/SKILL.md @@ -0,0 +1,246 @@ +--- +name: task-management +description: "PARA-based task and project management with Anytype integration. Use when: (1) creating/managing tasks or projects, (2) daily or weekly reviews, (3) prioritizing work, (4) capturing action items, (5) planning sprints or focus blocks, (6) asking 'what should I work on?'. Triggers: task, todo, project, priority, review, focus, plan, backlog, inbox, capture." +compatibility: opencode +--- + +# Task Management + +PARA-based productivity system integrated with Anytype for Sascha's personal and professional task management. + +## Quick Reference + +| Action | Command Pattern | +|--------|-----------------| +| Quick capture | "Capture: [item]" or "Add to inbox: [item]" | +| Create task | "Task: [title] for [area/project]" | +| Create project | "New project: [title] in [area]" | +| Daily review | "Daily review" or "What's on for today?" | +| Weekly review | "Weekly review" or "Week planning" | +| Focus check | "What should I focus on?" | +| Context batch | "What [area] tasks can I batch?" | + +## Anytype Configuration + +**Space**: Chiron (create if not exists) + +### Types + +| Type | PARA Category | Purpose | +|------|---------------|---------| +| `project` | Projects | Active outcomes with deadlines | +| `area` | Areas | Ongoing responsibilities | +| `resource` | Resources | Reference materials | +| `task` | (within Projects/Areas) | Individual action items | +| `note` | (Inbox/Resources) | Quick captures, meeting notes | + +### Key Properties + +| Property | Type | Used On | Values | +|----------|------|---------|--------| +| `status` | select | Task, Project | `inbox`, `next`, `waiting`, `scheduled`, `done` | +| `priority` | select | Task, Project | `critical`, `high`, `medium`, `low` | +| `area` | relation | Task, Project | Links to Area objects | +| `due_date` | date | Task, Project | Deadline | +| `energy` | select | Task | `high`, `medium`, `low` | +| `context` | multi_select | Task | `deep-work`, `admin`, `calls`, `errands` | + +## Core Workflows + +### 1. Quick Capture + +Minimal friction inbox capture. Process later during review. + +``` +User: "Capture: Review Q1 budget proposal" + +Action: +1. Create note in Anytype with status=inbox +2. Confirm: "Captured to inbox. 12 items pending processing." +``` + +### 2. Create Task + +Full task with metadata for proper routing. + +``` +User: "Task: Prepare board presentation for CTO Leadership, high priority, due Friday" + +Action: +1. Find or create "CTO Leadership" area in Anytype +2. Create task object: + - name: "Prepare board presentation" + - area: [CTO Leadership object ID] + - priority: high + - due_date: [this Friday] + - status: next +3. Confirm with task details +``` + +### 3. Create Project + +Projects are outcomes with multiple tasks and a completion state. + +``` +User: "New project: Launch NixOS Flakes Course in m3ta.dev area" + +Action: +1. Find "m3ta.dev" area +2. Create project object: + - name: "Launch NixOS Flakes Course" + - area: [m3ta.dev object ID] + - status: active +3. Prompt: "What are the key milestones or first tasks?" +4. Create initial tasks if provided +``` + +### 4. Daily Review (Evening) + +Run each evening to close the day and prep tomorrow. + +**Workflow** - See [references/review-templates.md](references/review-templates.md) for full template. + +Steps: +1. **Fetch today's completed** - Celebrate wins +2. **Fetch incomplete tasks** - Reschedule or note blockers +3. **Check inbox** - Quick process or defer to weekly +4. **Tomorrow's priorities** - Identify top 3 for morning focus +5. **Send summary via ntfy** (if configured) + +``` +User: "Daily review" + +Output format: +## Daily Review - [Date] + +### Completed Today +- [x] Task 1 +- [x] Task 2 + +### Carried Forward +- [ ] Task 3 (rescheduled to tomorrow) +- [ ] Task 4 (blocked: waiting on X) + +### Inbox Items: 5 pending + +### Tomorrow's Top 3 +1. [Highest impact task] +2. [Second priority] +3. [Third priority] +``` + +### 5. Weekly Review + +Comprehensive PARA review. See [references/para-methodology.md](references/para-methodology.md). + +**Workflow**: +1. **Get Clear** - Process inbox to zero +2. **Get Current** - Review each Area's active projects +3. **Get Creative** - Identify new projects or opportunities +4. **Plan Week** - Set weekly outcomes and time blocks + +``` +User: "Weekly review" + +Process: +1. List all inbox items -> prompt to process each +2. For each Area, show active projects and their status +3. Flag stalled projects (no activity 7+ days) +4. Identify completed projects -> move to archive +5. Prompt for new commitments +6. Output weekly plan +``` + +### 6. Priority Focus + +Impact-first prioritization using Sascha's preferences. + +``` +User: "What should I focus on?" + +Logic: +1. Fetch tasks where status=next, sorted by: + - priority (critical > high > medium > low) + - due_date (sooner first) + - energy match (if time of day known) +2. Return top 3-5 with rationale +3. Consider context batching opportunities + +Output: +## Focus Recommendations + +**Top Priority**: [Task] +- Why: [Impact statement] +- Area: [Area name] +- Due: [Date or "no deadline"] + +**Also Important**: +1. [Task 2] - [brief why] +2. [Task 3] - [brief why] + +**Batching Opportunity**: You have 3 [context] tasks that could be done together. +``` + +### 7. Context Batching + +Group similar tasks for focused execution. + +``` +User: "What admin tasks can I batch?" + +Action: +1. Fetch tasks where context contains "admin" +2. Group by area +3. Estimate total time +4. Suggest execution order + +Output: +## Admin Task Batch + +**Estimated time**: ~45 minutes + +1. [ ] Reply to vendor email (CTO Leadership) - 10min +2. [ ] Approve expense reports (CTO Leadership) - 15min +3. [ ] Update team wiki (CTO Leadership) - 20min + +Ready to start? I can track completion. +``` + +## Notification Integration (ntfy) + +Send notifications for: +- Daily review summary (evening) +- Overdue task alerts +- Weekly review reminder (Sunday evening) + +Format for ntfy: +```bash +curl -d "Daily Review: 5 completed, 3 for tomorrow. Top priority: [task]" \ + ntfy.sh/sascha-chiron +``` + +Configure topic in environment or Anytype settings. + +## Anytype API Patterns + +See [references/anytype-workflows.md](references/anytype-workflows.md) for: +- Space and type setup +- CRUD operations for tasks/projects +- Query patterns for reviews +- Batch operations + +## PARA Methodology Reference + +See [references/para-methodology.md](references/para-methodology.md) for: +- PARA category definitions +- When to use Projects vs Areas +- Archive criteria +- Maintenance rhythms + +## Initial Setup + +See [references/anytype-setup.md](references/anytype-setup.md) for: +- Step-by-step Anytype space creation +- Type and property configuration +- Initial Area objects to create +- View setup recommendations diff --git a/skill/task-management/references/anytype-setup.md b/skill/task-management/references/anytype-setup.md new file mode 100644 index 0000000..170973c --- /dev/null +++ b/skill/task-management/references/anytype-setup.md @@ -0,0 +1,176 @@ +# Anytype Space Setup Guide + +Manual setup for the Chiron space in Anytype. + +## Step 1: Create Space + +1. Open Anytype desktop app +2. Click **+** to create new space +3. Name: **Chiron** +4. Description: *Personal AI Assistant workspace using PARA methodology* + +## Step 2: Create Types + +Create these object types in the Chiron space: + +### Area Type +- **Name**: Area +- **Plural**: Areas +- **Layout**: Basic +- **Icon**: Briefcase (blue) + +### Project Type +- **Name**: Project +- **Plural**: Projects +- **Layout**: Basic +- **Icon**: Rocket (purple) + +### Task Type +- **Name**: Task +- **Plural**: Tasks +- **Layout**: Action (checkbox) +- **Icon**: Checkbox (blue) + +### Resource Type +- **Name**: Resource +- **Plural**: Resources +- **Layout**: Basic +- **Icon**: Book (teal) + +## Step 3: Create Properties + +Add these properties (relations) to the space: + +### Status (Select) +| Tag | Color | +|-----|-------| +| Inbox | Grey | +| Next | Blue | +| Waiting | Yellow | +| Scheduled | Purple | +| Done | Lime | + +### Priority (Select) +| Tag | Color | +|-----|-------| +| Critical | Red | +| High | Orange | +| Medium | Yellow | +| Low | Grey | + +### Energy (Select) +| Tag | Color | +|-----|-------| +| High | Red | +| Medium | Yellow | +| Low | Blue | + +### Context (Multi-select) +| Tag | Color | +|-----|-------| +| Deep Work | Purple | +| Admin | Grey | +| Calls | Blue | +| Errands | Teal | +| Quick Wins | Lime | + +### Other Properties +- **Area** (Relation β†’ Area type) +- **Project** (Relation β†’ Project type) +- **Due Date** (Date) +- **Outcome** (Text) +- **Description** (Text) + +## Step 4: Link Properties to Types + +### Task Type Properties +- Status +- Priority +- Energy +- Context +- Area (relation) +- Project (relation) +- Due Date + +### Project Type Properties +- Status +- Priority +- Area (relation) +- Due Date +- Outcome + +### Area Type Properties +- Description + +## Step 5: Create Initial Areas + +Create these Area objects: + +1. **CTO Leadership** + - Description: Team management, technical strategy, architecture decisions, hiring + +2. **m3ta.dev** + - Description: Content creation, courses, coaching, tutoring programs + +3. **YouTube @m3tam3re** + - Description: Technical exploration videos, tutorials, self-hosting guides + +4. **Technical Exploration** + - Description: NixOS, self-hosting, AI agents, automation experiments + +5. **Personal Development** + - Description: Learning, skills growth, reading + +6. **Health & Wellness** + - Description: Exercise, rest, sustainability + +7. **Family** + - Description: Quality time, responsibilities + +## Step 6: Create Views (Optional) + +Create these Set views for quick access: + +### Inbox View +- Filter: Status = Inbox +- Sort: Created date (newest) + +### Today's Focus +- Filter: Status = Next AND Due Date <= Today +- Sort: Priority (Critical first) + +### By Area +- Group by: Area relation +- Filter: Status != Done + +### Weekly Review +- Filter: Status != Done +- Group by: Area +- Sort: Due Date + +## Step 7: API Setup (For Automation) + +To enable API access for Chiron agent: + +1. Go to Anytype settings +2. Find API/Integration settings +3. Generate API key +4. Configure in your environment or MCP settings + +Without API access, use manual workflows or n8n integration. + +## Verification + +After setup, you should have: +- [ ] Chiron space created +- [ ] 4 custom types (Area, Project, Task, Resource) +- [ ] 4 select properties (Status, Priority, Energy, Context) +- [ ] 3 relation properties (Area, Project, Due Date) +- [ ] 7 Area objects created +- [ ] At least one view configured + +## Notes + +- The Note type is built-in, use it for quick captures +- Archive can be a status tag or separate type (your preference) +- Adjust colors and icons to your preference diff --git a/skill/task-management/references/anytype-workflows.md b/skill/task-management/references/anytype-workflows.md new file mode 100644 index 0000000..15365e3 --- /dev/null +++ b/skill/task-management/references/anytype-workflows.md @@ -0,0 +1,346 @@ +# Anytype API Workflows + +API patterns for task management operations in the Chiron space. + +## Setup + +### Space Configuration + +**Space Name**: Chiron +**Space ID**: Retrieve via `Anytype_API-list-spaces` after creation + +``` +# List spaces to find Chiron space ID +Anytype_API-list-spaces + +# Store space_id for subsequent calls +SPACE_ID="" +``` + +### Required Types + +Create these types if they don't exist: + +#### Area Type +``` +Anytype_API-create-type + space_id: SPACE_ID + name: "Area" + plural_name: "Areas" + layout: "basic" + key: "area" + properties: + - name: "Description", key: "description", format: "text" + - name: "Review Frequency", key: "review_frequency", format: "select" +``` + +#### Project Type +``` +Anytype_API-create-type + space_id: SPACE_ID + name: "Project" + plural_name: "Projects" + layout: "basic" + key: "project" + properties: + - name: "Status", key: "status", format: "select" + - name: "Priority", key: "priority", format: "select" + - name: "Area", key: "area", format: "objects" + - name: "Due Date", key: "due_date", format: "date" + - name: "Outcome", key: "outcome", format: "text" +``` + +#### Task Type +``` +Anytype_API-create-type + space_id: SPACE_ID + name: "Task" + plural_name: "Tasks" + layout: "action" + key: "task" + properties: + - name: "Status", key: "status", format: "select" + - name: "Priority", key: "priority", format: "select" + - name: "Area", key: "area", format: "objects" + - name: "Project", key: "project", format: "objects" + - name: "Due Date", key: "due_date", format: "date" + - name: "Energy", key: "energy", format: "select" + - name: "Context", key: "context", format: "multi_select" +``` + +### Required Properties with Tags + +#### Status Property Tags +``` +Anytype_API-create-property + space_id: SPACE_ID + name: "Status" + key: "status" + format: "select" + tags: + - name: "Inbox", color: "grey" + - name: "Next", color: "blue" + - name: "Waiting", color: "yellow" + - name: "Scheduled", color: "purple" + - name: "Done", color: "lime" +``` + +#### Priority Property Tags +``` +Anytype_API-create-property + space_id: SPACE_ID + name: "Priority" + key: "priority" + format: "select" + tags: + - name: "Critical", color: "red" + - name: "High", color: "orange" + - name: "Medium", color: "yellow" + - name: "Low", color: "grey" +``` + +#### Energy Property Tags +``` +Anytype_API-create-property + space_id: SPACE_ID + name: "Energy" + key: "energy" + format: "select" + tags: + - name: "High", color: "red" + - name: "Medium", color: "yellow" + - name: "Low", color: "blue" +``` + +#### Context Property Tags +``` +Anytype_API-create-property + space_id: SPACE_ID + name: "Context" + key: "context" + format: "multi_select" + tags: + - name: "Deep Work", color: "purple" + - name: "Admin", color: "grey" + - name: "Calls", color: "blue" + - name: "Errands", color: "teal" + - name: "Quick Wins", color: "lime" +``` + +## CRUD Operations + +### Create Task + +``` +Anytype_API-create-object + space_id: SPACE_ID + type_key: "task" + name: "Task title here" + body: "Optional task description or notes" + properties: + - key: "status", select: "" + - key: "priority", select: "" + - key: "area", objects: [""] + - key: "due_date", date: "2025-01-10" + icon: + format: "icon" + name: "checkbox" + color: "blue" +``` + +### Create Project + +``` +Anytype_API-create-object + space_id: SPACE_ID + type_key: "project" + name: "Project title" + body: "Project description and goals" + properties: + - key: "status", select: "" + - key: "area", objects: [""] + - key: "outcome", text: "What done looks like" + icon: + format: "icon" + name: "rocket" + color: "purple" +``` + +### Create Area + +``` +Anytype_API-create-object + space_id: SPACE_ID + type_key: "area" + name: "CTO Leadership" + body: "Team management, technical strategy, architecture decisions" + properties: + - key: "description", text: "Standards: Team health, technical excellence, strategic alignment" + - key: "review_frequency", select: "" + icon: + format: "icon" + name: "briefcase" + color: "blue" +``` + +### Quick Capture (Inbox) + +``` +Anytype_API-create-object + space_id: SPACE_ID + type_key: "note" + name: "Quick capture content here" + properties: + - key: "status", select: "" + icon: + format: "icon" + name: "mail" + color: "grey" +``` + +### Update Task Status + +``` +Anytype_API-update-object + space_id: SPACE_ID + object_id: "" + properties: + - key: "status", select: "" +``` + +## Query Patterns + +### Get All Tasks for Today + +``` +Anytype_API-search-space + space_id: SPACE_ID + types: ["task"] + filters: + operator: "and" + conditions: + - property_key: "status" + select: "" + - property_key: "due_date" + date: "2025-01-05" + condition: "le" +``` + +### Get Inbox Items + +``` +Anytype_API-search-space + space_id: SPACE_ID + filters: + operator: "and" + conditions: + - property_key: "status" + select: "" + sort: + property_key: "created_date" + direction: "desc" +``` + +### Get Tasks by Area + +``` +Anytype_API-search-space + space_id: SPACE_ID + types: ["task"] + filters: + operator: "and" + conditions: + - property_key: "area" + objects: [""] + - property_key: "status" + condition: "nempty" +``` + +### Get Active Projects + +``` +Anytype_API-search-space + space_id: SPACE_ID + types: ["project"] + filters: + conditions: + - property_key: "status" + select: "" +``` + +### Get Overdue Tasks + +``` +Anytype_API-search-space + space_id: SPACE_ID + types: ["task"] + filters: + operator: "and" + conditions: + - property_key: "due_date" + date: "" + condition: "lt" + - property_key: "status" + condition: "nempty" +``` + +### Get Tasks by Context + +``` +Anytype_API-search-space + space_id: SPACE_ID + types: ["task"] + filters: + conditions: + - property_key: "context" + multi_select: [""] + - property_key: "status" + select: "" +``` + +## Batch Operations + +### Complete Multiple Tasks + +```python +# Pseudocode for batch completion +task_ids = ["id1", "id2", "id3"] +done_tag_id = "" + +for task_id in task_ids: + Anytype_API-update-object( + space_id=SPACE_ID, + object_id=task_id, + properties=[{"key": "status", "select": done_tag_id}] + ) +``` + +### Archive Completed Projects + +``` +# 1. Find completed projects +Anytype_API-search-space + space_id: SPACE_ID + types: ["project"] + filters: + conditions: + - property_key: "status" + select: "" + +# 2. For each, update to archived status or move to archive +``` + +## Error Handling + +| Error | Cause | Solution | +|-------|-------|----------| +| 401 Unauthorized | Missing/invalid auth | Check API key configuration | +| 404 Not Found | Invalid space/object ID | Verify IDs with list operations | +| 400 Bad Request | Invalid property format | Check property types match expected format | + +## Notes + +- Always retrieve space_id fresh via `list-spaces` before operations +- Tag IDs must be retrieved via `list-tags` for the specific property +- Object relations require the target object's ID, not name +- Dates use ISO 8601 format: `2025-01-05` or `2025-01-05T18:00:00Z` diff --git a/skill/task-management/references/para-methodology.md b/skill/task-management/references/para-methodology.md new file mode 100644 index 0000000..81fdaf2 --- /dev/null +++ b/skill/task-management/references/para-methodology.md @@ -0,0 +1,190 @@ +# PARA Methodology Reference + +PARA is a universal system for organizing digital information, created by Tiago Forte. + +## The Four Categories + +### Projects + +**Definition**: A series of tasks linked to a goal, with a deadline. + +**Characteristics**: +- Has a clear outcome/deliverable +- Has a deadline (explicit or implicit) +- Requires multiple tasks to complete +- Can be completed (finite) + +**Examples**: +- Launch NixOS Flakes course +- Hire senior backend developer +- Complete Q1 board presentation +- Publish self-hosting playbook video + +**Questions to identify**: +- What am I committed to finishing? +- What has a deadline? +- What would I celebrate completing? + +### Areas + +**Definition**: A sphere of activity with a standard to be maintained over time. + +**Characteristics**: +- Ongoing responsibility (infinite) +- Has standards, not deadlines +- Requires regular attention +- Never "complete" - only maintained + +**Sascha's Areas**: +1. CTO Leadership +2. m3ta.dev +3. YouTube @m3tam3re +4. Technical Exploration +5. Personal Development +6. Health & Wellness +7. Family + +**Questions to identify**: +- What roles do I maintain? +- What standards must I uphold? +- What would suffer if I ignored it? + +### Resources + +**Definition**: A topic or theme of ongoing interest. + +**Characteristics**: +- Reference material for future use +- No immediate action required +- Supports projects and areas +- Can be shared or reused + +**Examples**: +- NixOS configuration patterns +- n8n workflow templates +- Self-hosting architecture docs +- AI prompt libraries +- Book notes and highlights + +**Questions to identify**: +- What might be useful later? +- What do I want to learn more about? +- What reference material do I need? + +### Archives + +**Definition**: Inactive items from the other three categories. + +**Characteristics**: +- Completed projects +- Areas no longer active +- Resources no longer relevant +- Preserved for reference, not action + +**When to archive**: +- Project completed or cancelled +- Role/responsibility ended +- Topic no longer relevant +- Information outdated + +## The PARA Workflow + +### Capture +Everything starts in the **Inbox**. Don't organize during capture. + +### Clarify +Ask: "Is this actionable?" +- **Yes** β†’ Is it a single task or a project? +- **No** β†’ Is it reference material or trash? + +### Organize +Place items in the appropriate category: +- Active work β†’ Projects (linked to Area) +- Ongoing standards β†’ Areas +- Reference β†’ Resources +- Done/irrelevant β†’ Archives + +### Review +- **Daily**: Process inbox, check today's tasks +- **Weekly**: Review all projects, check areas, process resources +- **Monthly**: Archive completed, assess areas, audit resources + +## Project vs Area Confusion + +The most common PARA mistake is confusing projects and areas. + +| If you treat a Project as an Area | If you treat an Area as a Project | +|-----------------------------------|-----------------------------------| +| Never feels "done" | Feels like constant failure | +| Scope creeps infinitely | Standards slip without noticing | +| No sense of progress | Burnout from "finishing" the infinite | + +**Test**: Can I complete this in a single work session series? +- Yes β†’ Project +- No, it's ongoing β†’ Area + +## Maintenance Rhythms + +### Daily (Evening - 10 min) +1. Process inbox items +2. Review completed tasks +3. Set tomorrow's priorities + +### Weekly (Sunday evening - 30 min) +1. Get clear: Inbox to zero +2. Get current: Review each Area +3. Review all active Projects +4. Plan next week's outcomes + +### Monthly (First Sunday - 60 min) +1. Review Area standards +2. Archive completed Projects +3. Evaluate stalled Projects +4. Audit Resources relevance + +### Quarterly (90 min) +1. Review life Areas balance +2. Set quarterly outcomes +3. Major archives cleanup +4. System improvements + +## PARA in Anytype + +### Type Mapping + +| PARA | Anytype Type | Notes | +|------|--------------|-------| +| Project | `project` | Has area relation, deadline | +| Area | `area` | Top-level organization | +| Resource | `resource` | Reference material | +| Archive | Use `archived` property | Or separate Archive type | +| Task | `task` | Lives within Project or Area | +| Inbox | `note` with status=inbox | Quick capture | + +### Recommended Properties + +**On Projects**: +- `area` (relation) - Which area owns this +- `status` (select) - active, on-hold, completed +- `due_date` (date) - Target completion +- `outcome` (text) - What does "done" look like + +**On Tasks**: +- `project` or `area` (relation) - Parent container +- `status` (select) - inbox, next, waiting, scheduled, done +- `priority` (select) - critical, high, medium, low +- `due_date` (date) - When it's needed +- `energy` (select) - Required energy level +- `context` (multi_select) - Where/how it can be done + +**On Areas**: +- `description` (text) - Standards to maintain +- `review_frequency` (select) - daily, weekly, monthly + +## Common Pitfalls + +1. **Over-organizing during capture** - Just dump it in inbox +2. **Too many projects** - Active projects should be <15 +3. **Orphan tasks** - Every task needs a project or area +4. **Stale resources** - Archive what you haven't touched in 6 months +5. **Skipping reviews** - The system only works if you review it diff --git a/skill/task-management/references/review-templates.md b/skill/task-management/references/review-templates.md new file mode 100644 index 0000000..3d81031 --- /dev/null +++ b/skill/task-management/references/review-templates.md @@ -0,0 +1,307 @@ +# Review Templates + +Structured templates for daily and weekly reviews. + +## Daily Review Template (Evening) + +**Duration**: 10-15 minutes +**Best time**: Evening, after work concludes + +### Script + +``` +## Daily Review - [DATE] + +### Wins Today +[List completed tasks - celebrate progress] + +- [x] +- [x] +- [x] + +### Still Open +[Tasks started but not finished] + +- [ ] [Task] - [Status/blocker] +- [ ] [Task] - [Rescheduled to: DATE] + +### Inbox Check +- Items in inbox: [COUNT] +- Quick processing: + - [Item] β†’ [Action: task/project/trash/defer] + +### Energy Assessment +- How was today's energy? [High/Medium/Low] +- What drained energy? +- What boosted energy? + +### Tomorrow's Top 3 +[Most impactful tasks for tomorrow - set before sleeping] + +1. **[TASK]** - Why: [impact reason] +2. **[TASK]** - Why: [impact reason] +3. **[TASK]** - Why: [impact reason] + +### Blockers to Address +- [Blocker] - Need: [what's needed to unblock] + +### Notes for Tomorrow +[Anything to remember, context to preserve] + +--- +Review completed at: [TIME] +``` + +### Daily Review Checklist + +- [ ] Review calendar for tomorrow +- [ ] Check completed tasks +- [ ] Process any urgent inbox items +- [ ] Identify top 3 priorities +- [ ] Note any blockers +- [ ] Clear desk/workspace (physical reset) + +## Weekly Review Template + +**Duration**: 30-45 minutes +**Best time**: Sunday evening or Friday afternoon + +### Script + +``` +## Weekly Review - Week of [DATE] + +### Part 1: Get Clear (Capture) + +#### Inbox Processing +- Starting inbox count: [COUNT] +- Process each item: + - [Item] β†’ [Destination: project/area/resource/trash] +- Ending inbox count: [TARGET: 0] + +#### Loose Ends +- Notes to process: +- Voice memos: +- Screenshots/photos: +- Browser tabs to close: +- Email to archive: + +### Part 2: Get Current (Review) + +#### Area Review + +**CTO Leadership** +- Active projects: [list] +- Stalled items: [list] +- Standards check: [On track / Needs attention] +- Next week focus: + +**m3ta.dev** +- Active projects: [list] +- Content pipeline: +- Next week focus: + +**YouTube @m3tam3re** +- Active projects: [list] +- Upload schedule: +- Next week focus: + +**Technical Exploration** +- Current experiments: +- Learning goals: +- Next week focus: + +**Personal Development** +- Current focus: +- Progress: +- Next week focus: + +**Health & Wellness** +- This week: [assessment] +- Next week intention: + +**Family** +- Quality time this week: +- Next week plans: + +#### Project Status + +| Project | Area | Status | Next Action | Due | +|---------|------|--------|-------------|-----| +| [Name] | [Area] | [On track/Stalled/Blocked] | [Next step] | [Date] | + +#### Waiting For +[Items waiting on others] + +| Item | Waiting On | Since | Follow-up Date | +|------|-----------|-------|----------------| +| | | | | + +### Part 3: Get Creative (Reflect) + +#### What Worked This Week? +- + +#### What Didn't Work? +- + +#### New Ideas/Projects +[Don't commit yet - just capture] +- + +#### Should I Start? +[New projects to consider] +- + +#### Should I Stop? +[Projects or commitments to drop] +- + +#### Should I Continue? +[Projects going well] +- + +### Part 4: Plan Next Week + +#### Weekly Outcomes +[3-5 specific outcomes for the week] + +1. [ ] +2. [ ] +3. [ ] +4. [ ] +5. [ ] + +#### Time Blocks +[Protect time for deep work] + +| Day | Block | Focus | +|-----|-------|-------| +| Mon | | | +| Tue | | | +| Wed | | | +| Thu | | | +| Fri | | | + +#### Key Meetings +- + +#### Week Theme (Optional) +[One word or phrase to guide the week] + +--- +Review completed at: [TIME] +Next weekly review: [DATE] +``` + +### Weekly Review Checklist + +- [ ] Close all browser tabs +- [ ] Process email inbox to zero +- [ ] Process Anytype inbox to zero +- [ ] Review each Area +- [ ] Check all active Projects +- [ ] Review Waiting For list +- [ ] Clear completed tasks +- [ ] Archive finished projects +- [ ] Set weekly outcomes +- [ ] Block deep work time +- [ ] Review calendar for the week + +## Monthly Review Template + +**Duration**: 60 minutes +**Best time**: First Sunday of the month + +### Script + +``` +## Monthly Review - [MONTH YEAR] + +### Month Metrics +- Projects completed: [COUNT] +- Projects started: [COUNT] +- Tasks completed: [COUNT] +- Inbox avg items: [COUNT] + +### Area Deep Dive + +[For each Area, rate 1-10 and note] + +| Area | Rating | Notes | Action | +|------|--------|-------|--------| +| CTO Leadership | /10 | | | +| m3ta.dev | /10 | | | +| YouTube | /10 | | | +| Tech Exploration | /10 | | | +| Personal Dev | /10 | | | +| Health | /10 | | | +| Family | /10 | | | + +### Project Archive +[Projects completed this month β†’ Archive] + +- + +### Stalled Projects +[No progress in 30+ days - decide: continue, pause, or kill] + +| Project | Days Stalled | Decision | +|---------|--------------|----------| +| | | | + +### Resource Audit +[Resources not accessed in 3+ months - archive or keep?] + +- + +### System Improvements +[What's not working in the system?] + +- + +### Next Month Focus +[Top 3 priorities for the month] + +1. +2. +3. + +--- +Review completed at: [TIME] +Next monthly review: [DATE] +``` + +## ntfy Notification Templates + +### Daily Review Summary +``` +Daily Review Complete + +Completed: [X] tasks +Tomorrow's Top 3: +1. [Task 1] +2. [Task 2] +3. [Task 3] + +Inbox: [X] items pending +``` + +### Weekly Review Reminder +``` +Weekly Review Reminder + +Time for your weekly review! +Start here: "weekly review" +``` + +### Overdue Alert +``` +Overdue Tasks Alert + +[X] tasks past due date: +- [Task 1] (due [DATE]) +- [Task 2] (due [DATE]) + +Review now: "show overdue" +```