AGENT SKILL

telemetry

Add and verify lightweight macOS runtime telemetry. Use when wiring Logger events or inspecting logs for windows, sidebars, menus, and actions.

License 许可
MIT
所属仓库
rossboyd/quickque
最近更新
2026-09-22
Stars
★ 0
Forks
0

01 前言 Front Matter

name
telemetry
description
Add and verify lightweight macOS runtime telemetry. Use when wiring Logger events or inspecting logs for windows, sidebars, menus, and actions.

02 资源文件 1

03 SKILL.md 正文

Telemetry

Quick Start

Use this skill to add lightweight app instrumentation that helps debug behavior without turning the codebase into a logging landfill. Prefer Apple's unified logging APIs and verify the events after a build/run loop.

Core Guidelines

  • Prefer Logger from the OSLog framework for structured app logs.
  • Give each feature a clear subsystem/category pair so runtime filtering stays easy.
  • Log meaningful user and app lifecycle events: window opening, sidebar selection changes, menu commands, menu bar extra actions, sync/load milestones, and unexpected fallback paths.
  • Keep info logs concise and stable. Use debug logs for noisy state details.
  • Do not log secrets, auth tokens, personal data, or raw document contents.
  • Add signposts only when measuring timing or performance spans; do not overinstrument by default.

Minimal Logger Pattern

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

Use feature-specific categories like Windowing, Commands, MenuBar, Sidebar, Sync, or Import so logs can be filtered quickly.

Workflow

  1. Identify the behavior that needs observability.

    • Window open/close
    • Sidebar or inspector selection changes
    • Menu or keyboard command actions
    • Menu bar extra actions
    • Background load/sync/import events
    • Error and recovery paths
  2. Add the smallest useful instrumentation.

    • Create one Logger per feature area or type.
    • Log action boundaries and key state transitions.
    • Prefer one high-signal line per user action over noisy value dumps.
  3. Build and run the app.

    • Use build-run-debug for the build/run loop.
    • If script/build_and_run.sh exists, prefer ./script/build_and_run.sh --telemetry for live telemetry checks or ./script/build_and_run.sh --logs for broader process logs.
    • Exercise the UI or command path that should emit telemetry.
  4. Read runtime logs and verify the event fired.

    • Use Console.app with a process/subsystem filter when that is the fastest manual check.
    • Use log stream --style compact --predicate 'process == "AppName"' for live terminal verification.
    • Prefer tighter predicates when you know the subsystem/category: log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'
  5. Tighten or remove instrumentation.

    • If the event fires, keep only the logs that remain useful for future debugging.
    • If it does not fire, move the log closer to the suspected control path and rerun.

Verification Checklist

  • The app builds after telemetry changes.
  • The relevant action emits exactly one clear log line or a small bounded sequence.
  • The log can be filtered by process, subsystem, or category.
  • No sensitive payloads are written to unified logs.
  • Noisy temporary debug logs are removed or demoted before finishing.

Guardrails

  • Do not use print as the primary app telemetry mechanism for macOS app code.
  • Do not leave a dense trail of permanent debug logs around every state mutation.
  • Do not claim an event is wired correctly until you have a concrete verification path through Console, log stream, or captured process output.
  • If the debugging task is mostly about crash/backtrace analysis rather than action telemetry, switch to build-run-debug.

04 同仓库更多 Skills

rossboyd
rossboyd/quickque

skill-installer

Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).

★ 0
rossboyd
rossboyd/quickque

skill-creator

Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.

★ 0
rossboyd
rossboyd/quickque

review-agent

Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.

★ 0
rossboyd
rossboyd/quickque

plugin-creator

Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.

★ 0
rossboyd
rossboyd/quickque

openai-docs

Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.

★ 0
rossboyd
rossboyd/quickque

imagegen

Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.

★ 0