add Plano agent skills framework and rule set

skills/README.md

@@ -0,0 +1,243 @@
+# Plano Agent Skills
+
+A structured repository of best practices for building agents and agentic applications with [Plano](https://github.com/katanemo/archgw) — the AI-native proxy and dataplane. Optimized for coding agents and LLMs.
+
+## What Are Skills?
+
+Skills are principle-based guides that help coding agents (Claude Code, Cursor, Copilot, etc.) make better decisions when working with Plano. They cover configuration patterns, routing strategies, agent orchestration, observability, and CLI workflows — acting as operating principles, not documentation replacements.
+
+## Installing
+
+```bash
+# Install via npx skills
+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.
+
+### Natural Language Invocation Examples
+
+- "Use the Plano skills to validate this `config.yaml` and fix issues."
+- "Apply Plano routing best practices to improve model/provider selection."
+- "Review this agent listener config with the orchestration rules."
+- "Refactor this filter chain to follow guardrail ordering best practices."
+- "Audit this setup against Plano deployment and security recommendations."
+
+### Prompting Tips for Better Results
+
+- Name your goal and file: "Harden `config.yaml` for production."
+- Ask for an action: "Generate a patch," "fix directly," or "explain the changes."
+- Include runtime context when relevant: trace output, logs, listener errors.
+- Ask for verification: "Run a final validation check after edits."
+
+### Invoke by Skill Area (Optional)
+
+- **Configuration:** "Use Plano configuration fundamentals on this config."
+- **Routing:** "Use routing/model-selection skills to tune defaults and aliases."
+- **Agent orchestration:** "Use agent orchestration skills to improve routing accuracy."
+- **Filters/guardrails:** "Use filter-chain skills to harden input/output safety."
+- **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/
+├── rules/                    # Individual rule files (one per rule)
+│   ├── _sections.md          # Section metadata and prefix definitions
+│   ├── _template.md          # Template for creating new rules
+│   ├── config-*.md           # Section 1: Configuration Fundamentals
+│   ├── routing-*.md          # Section 2: Routing & Model Selection
+│   ├── agent-*.md            # Section 3: Agent Orchestration
+│   ├── filter-*.md           # Section 4: Filter Chains & Guardrails
+│   ├── observe-*.md          # Section 5: Observability & Debugging
+│   ├── cli-*.md              # Section 6: CLI Operations
+│   ├── deploy-*.md           # Section 7: Deployment & Security
+│   └── advanced-*.md         # Section 8: Advanced Patterns
+├── src/
+│   ├── build.ts              # Compiles rules/ into AGENTS.md
+│   ├── validate.ts           # Validates rule files
+│   └── extract-tests.ts      # Extracts test cases for LLM evaluation
+├── metadata.json             # Document metadata
+├── AGENTS.md                 # Compiled output (generated — do not edit directly)
+├── test-cases.json           # Test cases for LLM evaluation (generated)
+└── package.json
+```
+
+## Sections
+
+| # | Prefix | Section | Rules |
+|---|--------|---------|-------|
+| 1 | `config-` | Configuration Fundamentals | Version, listeners, providers, secrets, timeouts |
+| 2 | `routing-` | Routing & Model Selection | Preferences, aliases, defaults, passthrough |
+| 3 | `agent-` | Agent Orchestration | Descriptions, agent registration |
+| 4 | `filter-` | Filter Chains & Guardrails | Ordering, MCP integration, guardrails |
+| 5 | `observe-` | Observability & Debugging | Tracing, trace inspection, span attributes |
+| 6 | `cli-` | CLI Operations | Startup, CLI agent, init, code generation |
+| 7 | `deploy-` | Deployment & Security | Docker networking, state storage, health checks |
+| 8 | `advanced-` | Advanced Patterns | Prompt targets, rate limits, multi-listener |
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Validate all rule files
+npm run validate
+
+# Build AGENTS.md from rules
+npm run build
+
+# Extract test cases for LLM evaluation
+npm run extract-tests
+
+# Run all of the above
+npm run dev
+```
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/<prefix>-<description>.md`
+
+2. Choose the correct prefix for your section:
+   - `config-` — Configuration Fundamentals
+   - `routing-` — Routing & Model Selection
+   - `agent-` — Agent Orchestration
+   - `filter-` — Filter Chains & Guardrails
+   - `observe-` — Observability & Debugging
+   - `cli-` — CLI Operations
+   - `deploy-` — Deployment & Security
+   - `advanced-` — Advanced Patterns
+
+3. Fill in the frontmatter:
+   ```yaml
+   ---
+   title: Clear, Actionable Rule Title
+   impact: HIGH
+   impactDescription: One-line description of why this matters
+   tags: config, routing, relevant-tags
+   ---
+   ```
+
+4. Write the rule body with:
+   - Brief explanation of the principle and why it matters
+   - **Incorrect** example (YAML config or CLI command showing the wrong pattern)
+   - **Correct** example (the right pattern with comments)
+   - Optional explanatory notes
+
+5. Run `npm run dev` to validate and regenerate
+
+## Rule File Structure
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL
+impactDescription: One sentence on the impact
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters for Plano developers.
+
+**Incorrect (describe what's wrong):**
+
+```yaml
+# Bad example
+```
+
+**Correct (describe what's right):**
+
+```yaml
+# Good example with comments explaining the decisions
+```
+
+Optional explanatory text, lists, or tables.
+
+Reference: https://github.com/katanemo/archgw
+
+
+
+## Impact Levels
+
+| Level | Description |
+|-------|-------------|
+| `CRITICAL` | Causes startup failures or silent misbehavior — always fix |
+| `HIGH` | Significantly degrades routing accuracy, security, or reliability |
+| `MEDIUM-HIGH` | Important for production deployments |
+| `MEDIUM` | Best practice for maintainability and developer experience |
+| `LOW-MEDIUM` | Incremental improvements |
+| `LOW` | Nice to have |
+
+## Key Rules at a Glance
+
+- **Always set `version: v0.3.0`** — config is rejected without it
+- **Use `host.docker.internal`** for agent/filter URLs — `localhost` doesn't work inside Docker
+- **Set exactly one `default: true` provider** — unmatched requests need a fallback
+- **Write specific routing preference descriptions** — vague descriptions cause misroutes
+- **Order filter chains: guards → rewriters → context builders** — never build context before blocking bad input
+- **Use `$VAR_NAME` for all secrets** — never hardcode API keys in config.yaml
+- **Enable tracing with `--with-tracing`** — traces are the primary debugging tool
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Compile `rules/` into `AGENTS.md` |
+| `npm run validate` | Validate all rule files for required fields and structure |
+| `npm run extract-tests` | Generate `test-cases.json` for LLM evaluation |
+| `npm run dev` | Validate + build + extract tests |
+
+## Contributing
+
+Rules are automatically sorted alphabetically by title within each section — no need to manage numbers. IDs (`1.1`, `1.2`, etc.) are assigned during build.
+
+When adding rules:
+1. Use the correct filename prefix for your section
+2. Follow `_template.md` structure
+3. Include clear bad/good YAML or CLI examples
+4. Add relevant tags
+5. Run `npm run dev` to validate and regenerate
+
+## License
+
+Apache-2.0 — see [LICENSE](../LICENSE)

skills/metadata.json

@@ -0,0 +1,8 @@
+{
+  "version": "1.0.0",
+  "organization": "Plano",
+  "name": "plano-agent-skills",
+  "abstract": "Best practices for building agents and agentic applications with Plano — the AI-native proxy and dataplane. Covers configuration, routing, agent orchestration, filter chains, observability, CLI operations, and deployment patterns.",
+  "homepage": "https://github.com/katanemo/archgw",
+  "license": "Apache-2.0"
+}