plano/skills/README.md

Plano Agent Skills

A structured repository of best practices for building agents and agentic applications with Plano — 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

# Install via npx skills
npx skills add katanemo/plano-agent-skills

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

# 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:

   ---
   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

---
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):

# 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