What is dash-docset-install-generate?

A skill to install and generate Dash docsets or cheatsheets on macOS, with workflows for discovery, installation, generation, and verification.

How do I install a new docset?

The skill resolves a candidate from built-in, contributed, or cheatsheet catalogs and runs dash_url_install.py with repo and entry; it requires explicit approval for automated installs.

How is generation handled?

Generation can be automated when there is a stable toolchain (Sphinx, Javadoc, cheat sheets) or guided via Dash Docset Generator when paths are unclear.

dash-docset-install-generate

npx machina-cli add skill gaelic-ghost/apple-dev-skills/dash-docset-install-generate --openclaw

Files (1)

SKILL.md

5.0 KB

Dash Install and Generate

Overview

Use this skill for install and generation workflows after discovery from $dash-docset-search or direct user request.

Defaults:

confirmation-first installs
no silent installation
hybrid generation: automate known CLI paths, otherwise guide manual Dash generator steps

Use references/dash_url_and_service.md, references/dash_http_api.md, and references/dash_mcp_tools.md during execution.

Automation Prompting

Codex App automation fit: Guarded. Install and generation flows can require user approval or UI-level interaction.
Codex CLI automation fit: Guarded. Prefer dry-run or planning mode unless explicit install approval is provided.
Use references/automation-prompts.md for Codex App and Codex CLI templates with placeholders and stop conditions.
Default automation behavior should be non-destructive unless install mode is explicitly approved.

Install Workflow

1) Resolve candidate

Match request against catalog snapshots:
- uv run python scripts/dash_catalog_match.py --query "<text>"
Prefer in this order:
- built-in Dash Downloads
- user-contributed
- cheatsheet
- generation path

2) Perform install (confirmation-first)

Preferred automation path:

uv run python scripts/dash_url_install.py --repo-name "<repo>" --entry-name "<entry>"
add --version "<version>" when explicit version is required
use --yes only when explicit user approval exists

If URL install details are ambiguous:

switch to guide mode
provide exact Dash UI path in Settings > Downloads

3) Verify install

Use this order:

Dash MCP list_installed_docsets
local HTTP /docsets/list (after scripts/dash_api_probe.py)
if API unavailable, ask user to confirm from Dash UI

Generation Workflow (Hybrid)

1) Decide automation vs guide

Automate only when there is a documented and stable toolchain for the target source.

Typical examples:

Sphinx/PyDoctor via docset tooling
Javadoc pipelines
GoDoc/Rust/Scaladoc/HexDoc toolchains
cheat sheet authoring via cheatset

If the path is unclear or brittle:

guide through Dash Docset Generator and official docs

2) Generation sources to cover

Swift packages
Ruby gems
Python/Sphinx docs
PHP packages
Java packages
Go packages
Rust crates
Scala packages
Dart packages
Haskell packages
Hex packages
Clojure libraries
generic HTML docs

3) Last-resort generation

Suggest GitHub-based or Stack Overflow-based generation only when built-in, contributed, and known generator paths are exhausted.

API and Service Fallbacks

If MCP is unavailable:

run uv run python scripts/dash_api_probe.py
use local HTTP API if healthy
otherwise provide:
- AppleScript open location "dash://?query=..."
- terminal open "dash://?query=..."
- macOS Look Up in Dash service guidance

Scripts

scripts/dash_api_probe.py
scripts/dash_catalog_refresh.py
scripts/dash_catalog_match.py
scripts/dash_url_search.py
scripts/dash_url_install.py

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 interface behavior needs verification, use the $screenshot skill if it is available in the user's environment.

Interactive Customization Flow

Load current effective customization settings first:

uv run python scripts/customization_config.py effective

Ask targeted customization questions:

Use references/customization-flow.md to drive knob-by-knob questions.
Confirm desired behavior changes and safety constraints.

Map requested changes to implementation files:

Update SKILL.md, references/*, and any runtime script files listed in references/customization-flow.md.

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.

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-install-generate/SKILL.md

View on GitHub

Overview

This skill orchestrates install and generation workflows for Dash.app docsets and cheatsheets on macOS. It supports discovering docsets from built-in sources, user contributions, or cheatsheets, generating custom docsets, subscribing to feeds, and verifying installations, with default confirmation-first behavior and a hybrid generation path.

How This Skill Works

The skill first resolves the requested docset by matching it against catalog snapshots and selecting built-in, contributed, cheatsheet, or generation paths. It then performs a guided install using dash_url_install.py (with repo/entry and optional version), preferring automation only when approved. Finally, it verifies the installation via Dash MCP, a local /docsets/list probe, or UI confirmation if the API is unavailable.

When to Use It

To add a missing Dash docset requested by a user
When installing from built-in Dash downloads, user-contributed sources, or cheatsheets
To subscribe to a Dash feed or generate a custom docset from code/docs
To verify installation using MCP, local API, or Dash UI
To customize or extend this skill's install/generation policy for Dash docsets

Quick Start

Step 1: Resolve candidate by matching the request against the docset catalog using scripts/dash_catalog_match.py --query "<text>"
Step 2: Install using scripts/dash_url_install.py --repo-name "<repo>" --entry-name "<entry>"; add --version "<version>" if needed; use --yes only with explicit user approval
Step 3: Verify installation via MCP list_installed_docsets or local /docsets/list; if API is unavailable, confirm with the user or guide via Dash UI

Best Practices

Start with a confirmation-first install and keep automation non-destructive unless approved
Prioritize built-in Dash downloads before user-contributed sources or cheatsheets
If the path is unclear or brittle, switch to a guided flow with exact Dash UI steps
Verify installation via MCP list_installed_docsets or /docsets/list, and fall back to UI when needed
Document source, version, and steps to ensure reproducibility

Example Use Cases

Add a missing Swift docset from built-in downloads using the dash_url_install.py workflow
Install a contributed docset from the user-contributed catalog
Install a new cheatsheet from the catalog_cheatsheets.json
Subscribe to a Dash feed to keep docsets up to date automatically
Generate a custom docset from a local Sphinx or Markdown project

Frequently Asked Questions

Add this skill to your agents