Agent Skills

An agent skill is a SKILL.md file with name and description frontmatter that a coding agent loads into context when the description matches what it's working on. Skills give an agent Signadot-specific guidance it wouldn't otherwise have: how to drive a particular surface, what to do in a particular situation, when to reach for which tool.

Skills are agent-agnostic. Any coding agent that supports the Skills format can load them, and they work with the Signadot MCP server: a skill will call MCP tools when they're available and fall back to the signadot CLI when they aren't.

Install

Install all Signadot skills with the skills CLI:

npx skills add signadot/agent-skills

Add -g to install globally and -a <agent> to target a specific supported agent. Skills are picked up on next start and trigger when the conversation matches their scope. To install individual skills, see the commands under each skill below.

Available skills

Skill	Purpose
signadot-validate	Validate code changes against real cluster dependencies before declaring a task done.
signadot-plan	Author and iterate on reusable Signadot plan specs.

Signadot validation is runtime, integration-level, and traffic-driven. The signadot-validate skill runs whatever test surface you pick (your integration suite, an existing e2e run, a Playwright script, or a tagged Signadot plan) against a real cluster with the change wired in via a routing key. It sits alongside your unit tests, type checks, static analysis, and security review, not on top of them.

signadot-validate

Some evidence only comes from running the change inside a real microservice, against real upstream and downstream services, with traffic flowing through the mesh and routing headers propagating end-to-end. Static analysis, type checks, and unit tests don't get you there. signadot-validate does: it runs the changed service against the real cluster, propagates a routing key across hops, and iterates until the agreed validation path passes.

Install just this skill:

npx skills add signadot/agent-skills --skill signadot-validate

What to expect

A few non-obvious things the skill does that are worth knowing up front:

• Validation runs through the cluster URL, not localhost. A successful curl to http://localhost:8080 doesn't count, because it bypasses the service mesh and the routing-key propagation path you actually want to exercise.
• The sandbox sticks around. The default is to leave it up so you can inspect it or re-run validation. The agent surfaces the signadot sandbox delete command but doesn't run it.
• The agent iterates on its own for mechanical failures like missing env vars, stale processes, or wrong ports. It stops to ask only when the fix is a judgment call, such as choosing between fixing forward or keeping things backward-compatible.
• Local image builds are a last resort, because running locally keeps the iteration loop tight and gives the agent stdout, logs, and a debugger. The skill only falls back to building and pushing an image when the service genuinely cannot run outside the cluster.
• Shared resources are gated. Creating an isolated sandbox is autonomous. Updating a shared sandbox or route group, adding public preview endpoints, or running sudo signadot local connect all require your confirmation.

signadot-plan

A Signadot plan is a reusable, multi-step automation: an immutable DAG of action invocations where params flow into steps, steps wire outputs into other steps, and the whole thing runs against a chosen cluster. signadot-plan helps an agent put one together end-to-end: discover the actions available in your org, draft the YAML spec, create the plan, run it, debug the failed step, and tag it for reuse when it's worth keeping.

Install just this skill:

npx skills add signadot/agent-skills --skill signadot-plan

What to expect

A few things worth knowing up front:

• The skill reads your action catalog before drafting. Actions are org-scoped, so the skill lists your enabled actions and reads each contract it's about to use, rather than guessing at action names or argument shapes.
• The agent iterates on its own through spec validation errors and failing steps. It pauses to ask when the call is about intent: which action to pick when two fit, what to do when a step's failure is ambiguous, whether a tag should overwrite an existing one.
• Plans are immutable, so iteration produces new plans. When the spec needs to change, the skill creates a fresh plan rather than rewriting in place. Old plans, executions, and outputs stay around for comparison.
• Tagging is opt-in. Plans stay untagged by default. A tag goes on only when the plan is reusable enough to be worth a stable name, and the skill checks before re-pointing an existing one.
• Secrets stay out of the spec. The skill passes secret values via --param-secret and keeps them out of YAML, params, and the final report.