feat: rewrite command skills to use --agent flag

All 6 scan command skills now use --agent instead of --json/--format json.
Each skill includes a Reading Results section documenting compressed output
format and available retrieve query filters.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

skills/commands/syncable-analyze.md

@@ -14,10 +14,10 @@ Analyze a project directory to detect its tech stack: programming languages, fra
 
 ## Commands
 
-### Basic analysis (JSON output for agent consumption)
+### Basic analysis (agent output)
 
 ```bash
-sync-ctl analyze <PATH> --json
+sync-ctl analyze <PATH> --agent
 ```
 
 ### Human-readable matrix view
@@ -29,31 +29,54 @@ sync-ctl analyze <PATH> --display matrix
 ### Filtered analysis (only specific aspects)
 
 ```bash
-sync-ctl analyze <PATH> --json --only languages,frameworks
-sync-ctl analyze <PATH> --json --only dependencies
+sync-ctl analyze <PATH> --agent --only languages,frameworks
+sync-ctl analyze <PATH> --agent --only dependencies
 ```
 
 ### Key Flags
 
 | Flag | Purpose |
 |------|---------|
-| `--json` | Machine-readable JSON output (always use when processing results) |
+| `--agent` | Compressed output for agent consumption (always use when processing results) |
 | `--detailed` | Show detailed analysis (legacy vertical format) |
 | `--display {matrix\|detailed\|summary}` | Display format for human-readable output |
 | `--only <filters>` | Comma-separated: `languages`, `frameworks`, `dependencies` |
 
 ## Output Interpretation
 
-The JSON output contains:
+When reporting to the user, prioritize: primary language, main framework, runtime version, and whether Docker/K8s infrastructure exists.
 
-- **languages** — detected programming languages with file counts and percentages
-- **frameworks** — detected frameworks with versions where available
-- **dependencies** — package managers found and dependency counts
-- **runtimes** — detected runtime versions (Node.js, Python, Go, Rust, Java)
-- **docker** — whether Dockerfiles or Docker Compose files exist
-- **monorepo** — whether the project is a monorepo and its structure
+## Reading Results
 
-When reporting to the user, prioritize: primary language, main framework, runtime version, and whether Docker/K8s infrastructure exists.
+When you use `--agent`, the output is a compressed summary — not the full analysis. Act on it directly for most decisions.
+
+The output JSON includes:
+- `summary` — project count, languages, frameworks detected
+- `full_data_ref` — reference ID for retrieving full data
+- `retrieval_hint` — exact command to get more details
+
+To drill into specifics:
+```bash
+# Get framework details
+sync-ctl retrieve <ref_id> --query "section:frameworks"
+
+# Get language breakdown
+sync-ctl retrieve <ref_id> --query "section:languages"
+
+# Get specific project details (monorepos)
+sync-ctl retrieve <ref_id> --query "project:<project-name>"
+
+# Get specific language details
+sync-ctl retrieve <ref_id> --query "language:Go"
+
+# Get specific framework details
+sync-ctl retrieve <ref_id> --query "framework:React"
+
+# List all stored outputs
+sync-ctl retrieve --list
+```
+
+**Available query filters:** `section:summary`, `section:frameworks`, `section:languages`, `language:<name>`, `framework:<name>`, `project:<name>`, `compact:true`
 
 ## Error Handling
 
@@ -67,15 +90,15 @@ When reporting to the user, prioritize: primary language, main framework, runtim
 
 **Analyze current directory:**
 ```bash
-sync-ctl analyze . --json
+sync-ctl analyze . --agent
 ```
 
 **Analyze a specific project:**
 ```bash
-sync-ctl analyze /path/to/project --json
+sync-ctl analyze /path/to/project --agent
 ```
 
 **Quick language-only check:**
 ```bash
-sync-ctl analyze . --json --only languages
+sync-ctl analyze . --agent --only languages
 ```

skills/commands/syncable-dependencies.md

@@ -17,32 +17,27 @@ Analyze project dependencies in detail: list all packages, check license types,
 ### Full dependency analysis with licenses
 
 ```bash
-sync-ctl dependencies <PATH> --licenses --format json
+sync-ctl dependencies <PATH> --licenses --agent
 ```
 
 ### Production dependencies only
 
 ```bash
-sync-ctl dependencies <PATH> --licenses --prod-only --format json
+sync-ctl dependencies <PATH> --licenses --prod-only --agent
 ```
 
 ### Key Flags
 
 | Flag | Purpose |
 |------|---------|
-| `--format json` | Machine-readable output (always use) |
+| `--agent` | Compressed output for agent consumption (always use) |
 | `--licenses` | Include license information for each dependency |
 | `--vulnerabilities` | Quick inline vulnerability check (for thorough CVE scanning, use the standalone `sync-ctl vulnerabilities` command instead) |
 | `--prod-only` | Show only production dependencies |
 | `--dev-only` | Show only development dependencies |
 
 ## Output Interpretation
 
-The JSON output contains:
-
-- **dependencies** — array of packages with name, version, license, and prod/dev classification
-- **summary** — total counts, license distribution
-
 **Priority for reporting to user:**
 1. License concerns (copyleft in commercial projects, unknown licenses)
 2. Dependency counts (prod vs dev)
@@ -52,6 +47,27 @@ The JSON output contains:
 - Use `--vulnerabilities` here for a quick inline check alongside license info
 - Use `sync-ctl vulnerabilities` for a dedicated, thorough CVE scan
 
+## Reading Results
+
+When you use `--agent`, the output is a compressed summary. License distribution and dependency counts are always included. Individual package details are available via retrieve for large dependency trees.
+
+The output JSON includes:
+- `summary` — total counts, license distribution, prod/dev split
+- `license_concerns` — packages with copyleft or unknown licenses
+- `full_data_ref` — reference ID for retrieving full data
+- `retrieval_hint` — exact command for drill-down
+
+To drill into specifics:
+```bash
+# Get high-severity license findings
+sync-ctl retrieve <ref_id> --query "severity:high"
+
+# Get findings for a specific file
+sync-ctl retrieve <ref_id> --query "file:package.json"
+```
+
+**Available query filters:** `severity:<level>`, `file:<path>`
+
 ## Error Handling
 
 | Error | Cause | Action |
@@ -63,15 +79,15 @@ The JSON output contains:
 
 **Full audit with licenses:**
 ```bash
-sync-ctl dependencies . --licenses --format json
+sync-ctl dependencies . --licenses --agent
 ```
 
 **Production-only for license compliance:**
 ```bash
-sync-ctl dependencies . --licenses --prod-only --format json
+sync-ctl dependencies . --licenses --prod-only --agent
 ```
 
 **Quick vulnerability check alongside deps:**
 ```bash
-sync-ctl dependencies . --licenses --vulnerabilities --format json
+sync-ctl dependencies . --licenses --vulnerabilities --agent
 ```

skills/commands/syncable-optimize.md

@@ -19,39 +19,39 @@ Analyze Kubernetes manifests and optionally live cluster metrics to recommend re
 ### Static manifest analysis
 
 ```bash
-sync-ctl optimize <PATH> --format json
+sync-ctl optimize <PATH> --agent
 ```
 
 ### Live cluster analysis
 
 ```bash
-sync-ctl optimize <PATH> --cluster --format json
-sync-ctl optimize <PATH> --cluster my-context --namespace default --format json
+sync-ctl optimize <PATH> --cluster --agent
+sync-ctl optimize <PATH> --cluster my-context --namespace default --agent
 ```
 
 ### With Prometheus metrics
 
 ```bash
-sync-ctl optimize <PATH> --cluster --prometheus http://localhost:9090 --period 30d --format json
+sync-ctl optimize <PATH> --cluster --prometheus http://localhost:9090 --period 30d --agent
 ```
 
 ### Full analysis (includes kubelint + helmlint)
 
 ```bash
-sync-ctl optimize <PATH> --full --format json
+sync-ctl optimize <PATH> --full --agent
 ```
 
 ### Cost estimation
 
 ```bash
-sync-ctl optimize <PATH> --cluster --cloud-provider aws --region us-east-1 --format json
+sync-ctl optimize <PATH> --cluster --cloud-provider aws --region us-east-1 --agent
 ```
 
 ### Key Flags
 
 | Flag | Purpose |
 |------|---------|
-| `--format json` | Machine-readable output (always use) |
+| `--agent` | Compressed output for agent consumption (always use) |
 | `--cluster [CONTEXT]` | Connect to live K8s cluster (uses current context if no name given) |
 | `--prometheus <URL>` | Prometheus URL for historical metrics |
 | `--namespace <NS>` | Target namespace (or `*` for all) |
@@ -67,23 +67,35 @@ sync-ctl optimize <PATH> --cluster --cloud-provider aws --region us-east-1 --for
 
 ## Output Interpretation
 
-The JSON output contains:
-
-- **recommendations** — array of optimization suggestions with:
-  - Resource right-sizing (CPU/memory requests/limits)
-  - Confidence score
-  - Current vs recommended values
-  - Estimated savings
-- **costs** — cost attribution per workload (if `--cloud-provider` set)
-- **drift** — configuration drift between manifests and running state (if `--cluster` set)
-- **security** — kubelint findings (if `--full` set)
-
 **Priority for reporting to user:**
 1. High-confidence right-sizing recommendations with cost savings
 2. Critical security findings (from `--full`)
 3. Drift detection issues
 4. Cost breakdown summary
 
+## Reading Results
+
+When you use `--agent`, the output is a compressed summary. High-confidence right-sizing recommendations are included in full. Cost summary and drift findings are always present when applicable.
+
+The output JSON includes:
+- `summary` — total recommendations, estimated savings, containers analyzed
+- `top_recommendations` — highest-impact right-sizing suggestions
+- `costs` — cost attribution summary (if `--cloud-provider` set)
+- `drift` — configuration drift issues (if `--cluster` set)
+- `full_data_ref` — reference ID for retrieving full data
+- `retrieval_hint` — exact command for drill-down
+
+To drill into specifics:
+```bash
+# Get high-severity findings
+sync-ctl retrieve <ref_id> --query "severity:high"
+
+# Get recommendations for a specific container
+sync-ctl retrieve <ref_id> --query "container:my-app"
+```
+
+**Available query filters:** `severity:<level>`, `container:<name>`
+
 ## Safety
 
 - `--fix` only generates suggestions — it does NOT modify files
@@ -95,23 +107,23 @@ The JSON output contains:
 
 | Error | Cause | Action |
 |-------|-------|--------|
-| `No Kubernetes manifests found` | No YAML with K8s resources | Run `sync-ctl analyze <PATH> --json` to check for K8s presence |
+| `No Kubernetes manifests found` | No YAML with K8s resources | Run `sync-ctl analyze <PATH> --agent` to check for K8s presence |
 | `Cannot connect to cluster` | Invalid kubeconfig or cluster unreachable | Check `kubectl cluster-info` works, verify context name |
 | `Prometheus unreachable` | Wrong URL or Prometheus not running | Verify URL, fall back to static analysis without `--prometheus` |
 
 ## Examples
 
 **Quick static analysis:**
 ```bash
-sync-ctl optimize . --format json
+sync-ctl optimize . --agent
 ```
 
 **Full analysis with live cluster and cost estimation:**
 ```bash
-sync-ctl optimize . --cluster --cloud-provider aws --full --format json
+sync-ctl optimize . --cluster --cloud-provider aws --full --agent
 ```
 
 **Preview fixes before applying:**
 ```bash
-sync-ctl optimize . --fix --dry-run --format json
+sync-ctl optimize . --fix --dry-run --agent
 ```

skills/commands/syncable-security.md

@@ -17,7 +17,7 @@ Perform security analysis on a codebase: detect leaked secrets (API keys, tokens
 ### Standard security scan
 
 ```bash
-sync-ctl security <PATH> --mode balanced --format json
+sync-ctl security <PATH> --mode balanced --agent
 ```
 
 ### Mode Selection Guide
@@ -37,7 +37,7 @@ Always pass `--mode` explicitly. Choose based on context:
 | Flag | Purpose |
 |------|---------|
 | `--mode {lightning\|fast\|balanced\|thorough\|paranoid}` | Scan depth (always specify) |
-| `--format json` | Machine-readable output (always use when processing results) |
+| `--agent` | Compressed output for agent consumption (always use when processing results) |
 | `--include-low` | Include low-severity findings (off by default) |
 | `--no-secrets` | Skip secrets detection (only code patterns) |
 | `--no-code-patterns` | Skip code pattern analysis (only secrets) |
@@ -46,24 +46,39 @@ Always pass `--mode` explicitly. Choose based on context:
 
 ## Output Interpretation
 
-The JSON output contains:
-
-- **findings** — array of security issues, each with:
-  - `severity` — Critical, High, Medium, Low, Info
-  - `category` — secrets, code_pattern, configuration, infrastructure
-  - `file` — exact file path
-  - `line` — line number
-  - `description` — what was found
-  - `remediation` — how to fix it
-- **summary** — total counts by severity
-- **score** — overall security score (0-100)
-
 **Priority for reporting to user:**
 1. Critical findings first (leaked secrets, hardcoded credentials)
 2. High findings (insecure patterns)
 3. Summary with score
 4. Remediation steps for top findings
 
+## Reading Results
+
+When you use `--agent`, the output is a compressed summary (~15KB max). All **critical** issues are included in full detail. High-severity issues show the first 10. Medium/low issues are deduplicated into patterns.
+
+The output JSON includes:
+- `status` — e.g., "CRITICAL_ISSUES_FOUND", "HIGH_ISSUES_FOUND", "CLEAN"
+- `summary` — counts by severity (total, critical, high, medium, low, info)
+- `critical_issues` — full details for every critical finding
+- `high_issues` — first 10 high-severity findings
+- `patterns` — deduplicated medium/low findings with counts
+- `full_data_ref` — reference ID for retrieving full data
+- `retrieval_hint` — exact command for drill-down
+
+To drill into specifics:
+```bash
+# Get all critical findings
+sync-ctl retrieve <ref_id> --query "severity:critical"
+
+# Get findings for a specific file
+sync-ctl retrieve <ref_id> --query "file:src/auth.rs"
+
+# Get findings by rule code
+sync-ctl retrieve <ref_id> --query "code:hardcoded-secret"
+```
+
+**Available query filters:** `severity:critical|high|medium|low|info`, `file:<path>`, `code:<id>`
+
 ## Error Handling
 
 | Error | Cause | Action |
@@ -76,20 +91,20 @@ The JSON output contains:
 
 **Quick secrets check on current directory:**
 ```bash
-sync-ctl security . --mode balanced --format json
+sync-ctl security . --mode balanced --agent
 ```
 
 **Deep pre-deploy audit:**
 ```bash
-sync-ctl security . --mode paranoid --format json
+sync-ctl security . --mode paranoid --agent
 ```
 
 **Secrets-only scan (skip code patterns):**
 ```bash
-sync-ctl security . --mode thorough --no-code-patterns --format json
+sync-ctl security . --mode thorough --no-code-patterns --agent
 ```
 
 **Save report to file:**
 ```bash
-sync-ctl security . --mode thorough --format json --output security-report.json
+sync-ctl security . --mode thorough --agent --output security-report.json
 ```