Get the FREE Ultimate OpenClaw Setup Guide →

dash-docset-search

Scanned
npx machina-cli add skill gaelic-ghost/apple-dev-skills/dash-docset-search --openclaw
Files (1)
SKILL.md
5.2 KB

Dash Docset Search

Overview

Use this skill to search Dash content with a strict fallback order:

  1. dash-mcp-server tools first
  2. local Dash HTTP API second
  3. Dash URL scheme and macOS Service guidance last

Use references/dash_mcp_tools.md, references/dash_http_api.md, and references/dash_url_and_service.md for exact details.

Automation Prompting

  • Codex App automation fit: Strong. Suitable for recurring search and reporting workflows.
  • Codex CLI automation fit: Strong. Suitable for non-interactive probe/search tasks with fallback handling.
  • Use references/automation-prompts.md for Codex App and Codex CLI templates, placeholders, and output shapes.
  • Keep install and generation actions out of this skill's automation prompts; hand off to $dash-docset-install-generate when needed.

Workflow

1) Establish access path

  1. If Dash MCP tools are available, use them first.
  2. If Dash MCP tools are unavailable, run:
    • uv run python scripts/dash_api_probe.py
  3. If probe indicates local API healthy, use /docsets/list, /search, and /docsets/enable_fts.
  4. If local API is unavailable, provide dash:// and Service fallback guidance.

2) List installed docsets

  • Preferred:
    • list_installed_docsets
  • HTTP fallback:
    • GET {base_url}/docsets/list

Normalize and present:

  • display name
  • identifier
  • platform
  • full-text status

3) Search one or many docsets

  • Preferred:
    • search_documentation(query, docset_identifiers, search_snippets, max_results)
  • HTTP fallback:
    • GET /search?query=...&docset_identifiers=...

Rules:

  • Use explicit identifiers from installed docsets.
  • Disable snippet search if user asks for docset-only results.
  • For multi-docset searches, pass comma-separated identifiers in one query.

4) Enable FTS when requested

  • Preferred:
    • enable_docset_fts(identifier)
  • HTTP fallback:
    • GET /docsets/enable_fts?identifier=...

Handle full_text_search status:

  • enabled: continue searching
  • disabled: enable then retry search
  • indexing: explain indexing in progress
  • not supported: skip FTS path

5) Missing docset recommendation

Use catalog snapshots and matcher:

  1. uv run python scripts/dash_catalog_match.py --query "<text>"
  2. classify top results into:
    • built-in
    • user-contributed
    • cheatsheet
  3. if no strong hit, suggest generator flow
  4. suggest GitHub or Stack Overflow generation only as last resort

When installation or generation is needed, hand off to $dash-docset-install-generate.

Fallback Search Guidance

When no API path is usable, provide direct commands:

  • AppleScript:
    • open location "dash://?query={query}"
    • open location "dash://?query=python:{query}"
  • Terminal:
    • open "dash://?query={query}"
  • macOS Service:
    • select text, then Services > Look Up in Dash

Scripts

  • scripts/dash_api_probe.py
    • Probe local Dash API state and schema path availability.
  • scripts/dash_catalog_refresh.py
    • Refresh built-in, contributed, and cheatsheet snapshots.
  • scripts/dash_catalog_match.py
    • Rank candidate docsets and cheatsheets for a query.
  • scripts/dash_url_search.py
    • Launch dash:// query URLs.
  • scripts/dash_url_install.py
    • Confirm-first launcher for dash-install://.

References

  • references/dash_mcp_tools.md
  • references/dash_http_api.md
  • references/dash_url_and_service.md
  • references/automation-prompts.md
  • references/catalog_built_in_docsets.json
  • references/catalog_user_contrib_docsets.json
  • references/catalog_cheatsheets.json

Optional Visual Troubleshooting

If Dash UI behavior needs visual confirmation, use the $screenshot skill if it is available in the user's environment.

Interactive Customization Flow

  1. Load current effective customization settings first:
  • uv run python scripts/customization_config.py effective
  1. Ask targeted customization questions:
  • Use references/customization-flow.md to drive knob-by-knob questions.
  • Confirm desired behavior changes and safety constraints.
  1. Map requested changes to implementation files:
  • Update SKILL.md, references/*, and any runtime script files listed in references/customization-flow.md.
  1. Persist durable customization state:
  • Start from customization.template.yaml defaults.
  • Apply approved overrides with uv run python scripts/customization_config.py apply --input <yaml-file>.
  • Durable path: ~/.config/gaelic-ghost/apple-dev-skills/<skill-name>/customization.yaml.
  • Optional override root: APPLE_DEV_SKILLS_CONFIG_HOME.
  1. Report resulting effective configuration:
  • Re-run uv run python scripts/customization_config.py effective and summarize final active settings.
  • If the user asks to remove customization state, run uv run python scripts/customization_config.py reset.

Use references/customization-flow.md for skill-specific knobs, file mapping, guardrails, validation checks, and example requests.

Source

git clone https://github.com/gaelic-ghost/apple-dev-skills/blob/main/dash-apple-swift-documentation/dash-docset-search/SKILL.mdView on GitHub

Overview

This skill searches Dash content with a strict fallback order: first using dash-mcp-server tools, then the local Dash HTTP API, and finally the Dash URL scheme and macOS Service guidance. It can explain Dash capabilities, list installed docsets, search docsets, enable full-text search, identify missing docsets before handing off to -docset-install-generate, and customize the search policy.

How This Skill Works

The workflow starts by establishing an access path: prefer Dash MCP tools, then fall back to a local API probe, and use the HTTP endpoints /docsets/list, /search, and /docsets/enable_fts if available. If the local API is unavailable, it guides via dash:// URLs and macOS Services. When needed, it uses catalog matching to suggest missing docsets and hands off installation or generation tasks to $dash-docset-install-generate.

When to Use It

  • Explain Dash capabilities and how the search process works.
  • List installed Dash docsets and their FTS status.
  • Search one or more docsets and retrieve relevant snippets.
  • Enable full-text search for a docset or handle its current FTS state.
  • Identify missing or unavailable docsets and trigger the install/generate flow

Quick Start

  1. Step 1: Establish access path (prefer MCP tools; else run dash_api_probe).
  2. Step 2: List installed docsets with list_installed_docsets or GET /docsets/list; perform search with search_documentation if needed.
  3. Step 3: If required, hand off installation or generation to $dash-docset-install-generate.

Best Practices

  • Use explicit docset identifiers from installed docsets for multi-docset searches.
  • Prefer dash-mcp-tools first, then the local HTTP API, then dash URL/service fallbacks.
  • Normalize results to show display name, identifier, platform, and FTS status.
  • Disable snippet search when user requests docset-only results.
  • When a docset is missing, run catalog matching and escalate to the install/generate handoff.

Example Use Cases

  • List all installed docsets and their full-text search status.
  • Search the Python docset across multiple docsets using explicit identifiers.
  • Enable full-text search for a specific docset and retry a search.
  • Run catalog_match to find a missing docset and propose an install/generate flow.
  • Provide dash:// URLs as a fallback when the local API is unavailable.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗