feat: add detailed skills documentation and examples for Plano

skills/README.md

@@ -15,6 +15,18 @@ npx skills add katanemo/plano
 
 This skills collection is published from the `skills/` directory in the `katanemo/plano` monorepo.
 
+Install a specific skill:
+
+```bash
+npx skills add katanemo/plano --skill plano-routing-model-selection
+```
+
+List available skills before install:
+
+```bash
+npx skills add katanemo/plano --list
+```
+
 ## Using Skills in Agents
 
 After installation, these skills are available to your coding agent and can be invoked with normal language. You do not need special syntax unless your tooling requires it.
@@ -43,6 +55,27 @@ After installation, these skills are available to your coding agent and can be i
 - **Observability:** "Use observability skills to add traceability and debug routing."
 - **CLI/deployment:** "Use CLI and deployment skills to produce a startup checklist."
 
+## Available Skills
+
+- `plano-agent-skills` - Umbrella skill covering all Plano areas
+- `plano-config-fundamentals` - Config versioning, listeners, providers, secrets
+- `plano-routing-model-selection` - Defaults, aliases, passthrough auth, preferences
+- `plano-agent-orchestration` - Agent registration and routing descriptions
+- `plano-filter-guardrails` - MCP filters, guardrail messaging, filter ordering
+- `plano-observability-debugging` - Tracing setup, span attributes, trace analysis
+- `plano-cli-operations` - `planoai up`, `cli_agent`, init, prompt target generation
+- `plano-deployment-security` - Docker networking, health checks, state storage
+- `plano-advanced-patterns` - Multi-listener architecture and prompt target schema design
+
+## Local Testing
+
+```bash
+# From repo root
+npx skills add ./skills --list
+npx skills add ./skills --skill plano-agent-skills -y
+npx skills list
+```
+
 ## Structure
 
 ```

skills/plano-advanced-patterns/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: plano-advanced-patterns
+description: Design advanced Plano architectures. Use for multi-listener systems, prompt target schema quality, and layered orchestration patterns.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Advanced Patterns
+
+Use this skill for higher-order architecture decisions once fundamentals are stable.
+
+## When To Use
+
+- "Design a multi-listener Plano architecture"
+- "Improve prompt target schema precision"
+- "Combine model, prompt, and agent listeners"
+- "Refine advanced routing/function-calling behavior"
+
+## Apply These Rules
+
+- `advanced-multi-listener`
+- `advanced-prompt-targets`
+
+## Execution Checklist
+
+1. Use multiple listeners only when interfaces are truly distinct.
+2. Keep provider/routing definitions shared and consistent.
+3. Define prompt target parameters with strict, explicit schemas.
+4. Minimize ambiguity that causes malformed tool calls.
+5. Provide migration-safe recommendations and test scenarios.

skills/plano-agent-orchestration/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: plano-agent-orchestration
+description: Improve multi-agent orchestration in Plano. Use for agent registration, agent listener wiring, and capability-focused agent descriptions for accurate routing.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Agent Orchestration
+
+Use this skill for agent listener quality, sub-agent registration, and route accuracy.
+
+## When To Use
+
+- "Fix multi-agent routing"
+- "Validate agents vs listeners.agents config"
+- "Improve agent descriptions"
+- "Set up a reliable orchestrator"
+
+## Apply These Rules
+
+- `agent-orchestration`
+- `agent-descriptions`
+
+## Execution Checklist
+
+1. Verify each agent exists in both `agents` and `listeners[].agents`.
+2. Ensure one fallback/default agent where appropriate.
+3. Rewrite descriptions to be capability-focused and non-overlapping.
+4. Keep descriptions specific, concise, and example-driven.
+5. Provide test prompts to validate routing outcomes.

skills/plano-agent-skills/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: plano-agent-skills
+description: Best practices for building agents and agentic applications with Plano, including configuration, routing, orchestration, guardrails, observability, and deployment.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Agent Skills
+
+Comprehensive Plano guidance for coding agents. Use this umbrella skill when a task spans multiple areas (config, routing, orchestration, filters, observability, CLI, deployment).
+
+## When To Use
+
+- Validating or fixing Plano `config.yaml`
+- Designing listener architecture (`model`, `prompt`, `agent`)
+- Improving model/provider routing quality and fallback behavior
+- Hardening filter chains and prompt guardrails
+- Debugging routing with traces and CLI workflows
+- Preparing deployment and production readiness checks
+
+## How To Use
+
+1. Classify the request by scope (single section vs. cross-cutting).
+2. For focused work, prefer a section-specific skill (for example `plano-routing-model-selection`).
+3. For broad work, apply this umbrella skill and reference section rules from `skills/AGENTS.md`.
+4. Produce concrete edits first, then concise reasoning and validation steps.
+
+## Operating Workflow
+
+1. Identify the task area first: config, routing, orchestration, filters, observability, CLI, or deployment.
+2. Apply the smallest correct change that satisfies the requested behavior.
+3. Preserve security and reliability defaults:
+   - `version: v0.3.0`
+   - exactly one `default: true` model provider
+   - secrets via `$ENV_VAR` substitution only
+   - `host.docker.internal` for host services from inside Docker
+   - guardrails before enrichment in filter chains
+4. For debugging, prioritize traces over guesswork (`planoai up --with-tracing`, `planoai trace`).
+5. Return concrete diffs and a short validation checklist.
+
+## Response Style
+
+- Prefer actionable edits over generic advice.
+- Be explicit about why a config choice is correct.
+- Call out risky patterns (hardcoded secrets, missing default provider, bad filter ordering).
+- Keep examples minimal and production-viable.
+
+## References
+
+- Repo: https://github.com/katanemo/plano
+- Full rulebook: `skills/AGENTS.md`

skills/plano-cli-operations/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: plano-cli-operations
+description: Apply Plano CLI best practices. Use for startup troubleshooting, cli_agent workflows, prompt target generation, and template-based project bootstrapping.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano CLI Operations
+
+Use this skill when the task is primarily operational and CLI-driven.
+
+## When To Use
+
+- "Fix `planoai up` failures"
+- "Use `planoai cli_agent` with coding agents"
+- "Generate prompt targets from Python functions"
+- "Bootstrap a project with `planoai init` templates"
+
+## Apply These Rules
+
+- `cli-startup`
+- `cli-agent`
+- `cli-generate`
+- `cli-init`
+
+## Execution Checklist
+
+1. Follow startup validation order before deep debugging.
+2. Use `cli_agent` to route coding-agent traffic through Plano.
+3. Generate prompt target schema, then wire endpoint details explicitly.
+4. Start from templates for reliable first-time setup.
+5. Provide a compact runbook with exact CLI commands.

skills/plano-config-fundamentals/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: plano-config-fundamentals
+description: Validate and fix Plano config fundamentals. Use for config versioning, listener types, provider registration, secrets handling, and startup validation failures.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Configuration Fundamentals
+
+Use this skill for foundational `config.yaml` correctness.
+
+## When To Use
+
+- "Validate this Plano config"
+- "Fix startup config errors"
+- "Check listeners/providers/secrets"
+- "Why does `planoai up` fail schema validation?"
+
+## Apply These Rules
+
+- `config-version`
+- `config-listeners`
+- `config-providers`
+- `config-secrets`
+
+## Execution Checklist
+
+1. Ensure `version: v0.3.0` is present.
+2. Confirm listener type matches intended architecture.
+3. Verify provider names/interfaces and exactly one default provider.
+4. Replace hardcoded secrets with `$ENV_VAR` substitution.
+5. Return minimal patch and a `planoai up` verification plan.

skills/plano-deployment-security/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: plano-deployment-security
+description: Apply Plano deployment and production security practices. Use for Docker networking, state storage choices, readiness checks, and environment-based secret handling.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Deployment and Security
+
+Use this skill to harden production deployments and reduce runtime surprises.
+
+## When To Use
+
+- "Fix unreachable agents in Docker"
+- "Configure persistent conversation state"
+- "Add readiness and health checks"
+- "Prepare production deployment checklist"
+
+## Apply These Rules
+
+- `deploy-docker`
+- `deploy-state`
+- `deploy-health`
+
+## Execution Checklist
+
+1. Use `host.docker.internal` for host-side services from inside Plano container.
+2. Prefer PostgreSQL state storage for production multi-turn workloads.
+3. Verify `/healthz` before traffic or CI assertions.
+4. Ensure secrets remain environment-based, never hardcoded.
+5. Return deployment checks with failure-mode diagnostics.

skills/plano-filter-guardrails/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: plano-filter-guardrails
+description: Harden Plano filter chains and guardrails. Use for MCP filter setup, prompt guard responses, and safe filter ordering.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Filter Chains and Guardrails
+
+Use this skill when safety controls or filter pipelines need correction.
+
+## When To Use
+
+- "Fix filter chain ordering"
+- "Set up MCP filters correctly"
+- "Improve guardrail rejection behavior"
+- "Harden request processing for safety"
+
+## Apply These Rules
+
+- `filter-mcp`
+- `filter-guardrails`
+- `filter-ordering`
+
+## Execution Checklist
+
+1. Configure filter `type`, `transport`, and `tool` explicitly for MCP.
+2. Ensure rejection messages are clear and actionable.
+3. Order chain as guards -> rewriters -> enrichment -> output checks.
+4. Prevent expensive enrichment on unsafe requests.
+5. Verify with representative blocked and allowed test prompts.

skills/plano-observability-debugging/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: plano-observability-debugging
+description: Improve Plano tracing and debugging workflows. Use for sampling strategy, span attributes, and trace query-based root-cause analysis.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Observability and Debugging
+
+Use this skill to make routing and latency behavior inspectable and debuggable.
+
+## When To Use
+
+- "Enable tracing correctly"
+- "Add useful span attributes"
+- "Debug why a request routed incorrectly"
+- "Inspect filter/model latency from traces"
+
+## Apply These Rules
+
+- `observe-tracing`
+- `observe-span-attributes`
+- `observe-trace-query`
+
+## Execution Checklist
+
+1. Enable tracing with environment-appropriate sampling.
+2. Add useful static and header-derived span attributes.
+3. Use `planoai trace` filters to isolate route and latency issues.
+4. Prefer trace evidence over assumptions in recommendations.
+5. Return exact commands to reproduce and validate findings.

skills/plano-routing-model-selection/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: plano-routing-model-selection
+description: Optimize Plano model routing and selection. Use for provider defaults, model aliases, passthrough auth, and routing preference quality.
+license: Apache-2.0
+metadata:
+  author: katanemo
+  version: "1.0.0"
+---
+
+# Plano Routing and Model Selection
+
+Use this skill when requests are routed to the wrong model, costs are high, or fallback behavior is unclear.
+
+## When To Use
+
+- "Improve model routing"
+- "Add aliases and defaults"
+- "Fix passthrough auth with proxy providers"
+- "Tune routing preferences for better classification"
+
+## Apply These Rules
+
+- `routing-default`
+- `routing-aliases`
+- `routing-passthrough`
+- `routing-preferences`
+
+## Execution Checklist
+
+1. Ensure exactly one `default: true` provider.
+2. Add semantic aliases for stable client contracts.
+3. Configure passthrough auth only where required.
+4. Rewrite vague preference descriptions with concrete task scopes.
+5. Validate routing behavior using trace-based checks.