OpenClicky Documentation

The Spotify skill provides 7 specialized tools to control a user's Spotify account, including playback, device management, queueing, searching, playlist management, album retrieval, and library operations.

Note on Subscription Levels:

• Playback-mutating actions (play, pause, skip, etc.) require a Spotify Premium account.
• Read-only operations (search, library, playlists) work on Spotify Free accounts.

Prerequisites tools:
- `spotify_playback` 
- `spotify_devices` 
- `spotify_queue` 
- `spotify_search` 
- `spotify_playlists` 
- `spotify_albums` 
- `spotify_library`

The save-wiki skill is designed to ingest links, screenshots, and notes into a persistent, compounding personal knowledge wiki. It acts as the counterpart to the read-wiki skill. It is triggered when a user expresses intent to "save", "remember", or "note" something.

Argument Hint: "[url | screenshot path | text]"

The gog CLI is the primary local route for interacting with Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Chat, Contacts, etc.) within OpenClicky. It is preferred over browser automation for standard requests.

Important Constraints:

• Scope: Use gog for Google Workspace. Do not use it for Google Cloud/GCP, Google Ads, generic Google Search, or public web research.
• Safety: By default, gog should be treated as read-only. Writes (sends, deletes, moves, etc.) require explicit user approval.
• Local Paths:
  • CLI: gog (Homebrew: /opt/homebrew/bin/gog)
  • Config: ~/Library/Application Support/gogcli/config.json
  • Credentials: ~/Library/Application Support/gogcli/credentials.json
  • Keyring: ~/Library/Application Support/gogcli/keyring/

# Example of checking gog version
```bash
gog --version

The Maps Skill provides location intelligence using OpenStreetMap, Nominatim, Overpass API, OSRM, and TimeAPI.io. It allows for geocoding, reverse geocoding, finding points of interest (POIs), calculating travel distances/times, and obtaining turn-by-turn directions. It requires Python 3.8+ or curl and has no external API key requirements.

Key Capabilities:

• Geocoding: Convert place names to coordinates (search).
• Reverse Geocoding: Convert coordinates to addresses (reverse).
• POI Discovery: Find nearby places by category (nearby).
• Routing: Calculate distance/time (distance) or get turn-by-turn steps (directions).
• Timezones: Get local time and UTC offsets (timezone).
• Area Analysis: Get bounding boxes for places (area) or search within a specific rectangle (bbox).

The OpenClicky architecture roadmap categorizes planned improvements and fixes by priority (P0 to P2) and estimated effort (Quick, Short, Medium, Large).

Priority Levels:

• P0: Critical fixes and core architectural requirements (e.g., honoring realtime tool-call classification, fixing background computer use selectors, and extracting the VoiceRouter).
• P1: Feature enhancements and technical debt reduction (e.g., bumping Anthropic defaults, implementing a SkillCorpus abstraction, and introducing AgentExecutor protocols).
• P2: Long-term stability and advanced features (e.g., resolving runtime ambiguity, fixing process lifecycles, and implementing model-authoritative routing for push-to-talk).

Effort Estimates:

• Quick: < ½ day
• Short: ≤ 1 day
• Medium: 2-4 days
• Large: 1-2 weeks

The Spotify skill provides control over playback, devices, queues, search, playlists, albums, and the user's library through 7 specialized tools.

Note on Spotify Tiers:

• Playback-mutating actions (play, pause, skip, etc.) require Spotify Premium.
• Search, library, and playlist operations work on the Free tier.

### The 7 tools

- `spotify_playback` — play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume, get_state, get_currently_playing, recently_played
- `spotify_devices` — list, transfer
- `spotify_queue` — get, add
- `spotify_search` — search the catalog
- `spotify_playlists` — list, get, create, add_items, remove_items, update_details
- `spotify_albums` — get, tracks
- `spotify_library` — list/save/remove with `kind: "tracks"|"albums"`

When developing or managing specialist agents, adhere to these safety and quality constraints:

• Archiving: Never overwrite a user-authored agent or skill without archiving the prior version first.
• Scope: Avoid creating broad or vague agents. Specialists must have a narrow job and named skills.
• Skill Verification: Do not claim a specialist can use a skill unless it is explicitly enabled in skills.json or exists in the agent's custom skills/ folder.
• Error Reporting: If a tool, auth, or macOS permission is missing, stop and report the exact missing setup step. Do not loop or silently switch to browser automation.
• Write Safety: Treat all external actions (sends, publishes, deploys, deletes, moves, merges, cloud writes, etc.) as external writes unless the specific skill narrows that scope.

Maintain high design fidelity by avoiding 'AI design sludge' and filler content.

Content Discipline:

• Do not add fake metrics, decorative stats, generic feature grids, or placeholder testimonials.
• Every element must earn its place. If a new section is needed to improve the artifact, ask the user first.
• Mark non-final copy as draft or placeholder.

Anti-Slop Rules (Avoid these):

• Aggressive gradient backgrounds and default glassmorphism.
• Generic SaaS cards with ubiquitous icons.
• Left-border accent callout cards.
• Fake dashboards with arbitrary numbers.
• Stock-photo hero sections.
• Oversized rounded rectangles used as a substitute for hierarchy.
• Vague labels like "Insights," "Growth," or "Scale" without supporting content.