docs(skills): improve using-ado-cli skill score

.cursor/skills/using-ado-cli/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: using-ado-cli
-description:
-  Guidelines for using ado CLI commands and documenting them correctly. Use when
-  writing documentation that includes ado commands, verifying CLI syntax, or
-  explaining ado CLI usage patterns to users.
+description: "Reference for ado CLI command syntax, flags, and usage patterns — covers get, create, edit, show, and describe subcommands, output formatting with -o and --output-file, convenience flags (--use-latest, --set, --with), debugging with -l, and run_experiment for local point testing. Use when writing or verifying ado CLI commands, looking up correct command syntax or flags, debugging unexpected CLI output, or explaining ado command patterns."
 ---
 
 # Using the ado CLI
@@ -29,15 +26,27 @@ uv run ado [COMMAND] [SUBCOMMAND1] [SUBCOMMAND2] --help
 - Required arguments are included
 - Optional flags match actual CLI behavior
 
-## Output format vs output file
+## Output Format and File Handling
 
 For `ado get` and `ado show` subcommands:
 
 - `-o` / `--output` selects the **output format** (for example `yaml`, `table`,
   `csv`, or `json`; allowed values depend on the command — use `--help`).
-- `--output-file PATH` writes that formatted output to **PATH** instead of
-  stdout. Prefer this over shell redirection for large output so encoding and
-  table rendering stay consistent.
+- `--output-file PATH` writes formatted output to **PATH** instead of stdout.
+
+Shell redirects (`>`) work for simple cases. Prefer `--output-file` when:
+
+- **Pre-flight checks**: ado validates the path is writable before fetching,
+  avoiding failure after a long data fetch.
+- **Stdout pollution**: `--output-file` writes only formatted output to the file;
+  logs stay on stderr. A redirect captures both.
+- **Table truncation**: terminal-width column truncation applies to redirected
+  output but not to `--output-file`.
+
+```bash
+uv run ado get space SPACE_ID -o yaml > space.yaml
+uv run ado show entities operation OPERATION_ID -o csv --output-file entities.csv
+```
 
 ## Commands That do not exist
 
@@ -167,33 +176,6 @@ uv run ado describe space SPACE_ID
 uv run ado describe experiment EXPERIMENT_ID
 ```
 
-## Using --output-file
-
-For `ado get` and `ado show` subcommands, output can be captured with a shell
-redirect (`>`) or with the `--output-file PATH` flag. In many cases a redirect
-(or pipe) is perfectly fine and fits naturally into terminal workflows:
-
-```bash
-uv run ado get space SPACE_ID -o yaml > space.yaml
-uv run ado show entities operation OPERATION_ID -o csv > entities.csv
-```
-
-Prefer `--output-file` in the following situations:
-
-- **Pre-flight checks**: ado validates that the path is writable before starting
-  a potentially long data fetch, avoiding a failure after fetch.
-- **Stdout pollution**: if any log lines or warnings are mixed into stdout (e.g.
-  when another tool in the pipeline writes to stdout), a redirect captures that
-  noise alongside the data. `--output-file` writes only the formatted output to
-  the file; logs continue to go to stderr.
-- **Table Truncation**: when output to terminal the table format (the default
-  for --output) may truncate columns to fit terminal width. This truncation is
-  not removed when the output is redirected, but is if --output-file specified
-
-```bash
-uv run ado show entities operation OPERATION_ID -o csv --output-file entities.csv
-```
-
 ## Debugging
 
 If commands are not given expected output use the -l flag to activate different
@@ -205,16 +187,10 @@ e.g. for debug level logs
 uv run ado -lDEBUG [COMMAND]
 ```
 
-## Terminology
-
-### Entities
-
-Entities represent points in the discovery space with:
+## show Commands Quick Reference
 
-- **Constitutive properties** (inputs/priors) - what defines the point
-- **Measured properties** (outputs/posteriors) - what was observed
-
-### Understanding show Commands
+Entities are points in the discovery space — constitutive properties (inputs)
+plus measured properties (outputs).
 
 <!-- markdownlint-disable line-length -->
 
@@ -226,13 +202,11 @@ Entities represent points in the discovery space with:
 
 <!-- markdownlint-enable line-length -->
 
-**Example distinction**:
-
 ```bash
-# Get the actual measurement data for entities
+# Measurement data for entities
 uv run ado show entities operation op-123
 
-# Get metadata about the operation's results
+# Metadata about the operation's results (not measurements)
 uv run ado show results operation op-123
 ```
 
@@ -313,31 +287,11 @@ When writing documentation with ado commands:
 1. **Always verify** the command syntax with `--help`
 2. **Use realistic IDs** in examples (e.g., `space-abc123` not `SPACE_ID` in
    code blocks where actual output is shown)
-3. **Show expected output** when helpful for clarity
-4. **Prefer shortcuts** (`--use-latest`, `--with`) in tutorials to reduce
+3. **Prefer shortcuts** (`--use-latest`, `--with`) in tutorials to reduce
    friction
-5. **Explain terminology** the first time: "entities (the inputs and their
+4. **Explain terminology** the first time: "entities (the inputs and their
    measurements)"
 
-### Example Documentation Pattern
-
-```markdown
-## Creating and Running an Operation
-
-First, create your discovery space:
-
-\`\`\`bash ado create space -f space.yaml \`\`\`
-
-Then create and start the operation, automatically using the space you just
-created:
-
-\`\`\`bash ado create operation -f operation.yaml --use-latest space \`\`\`
-
-View the entities (inputs) and their measurements (outputs):
-
-\`\`\`bash ado show entities operation --use-latest \`\`\`
-```
-
 ## Common Patterns
 
 ### Query workflow
@@ -371,7 +325,11 @@ uv run ado create space -f space.yaml
 # Validate with dry-run
 uv run ado create operation -f operation.yaml --dry-run --use-latest space
 
-# Actually create it
+# If dry-run fails: check error message, fix the YAML, re-run dry-run
+# Common issues: missing experiment references, invalid parameter types,
+# unresolvable --use-latest (no resource of that type exists yet)
+
+# Once dry-run passes, actually create it
 uv run ado create operation -f operation.yaml --use-latest space
 ```