agent-sops

Agent SOPs

Manage Standard Operating Procedure (SOP) files. SOPs are Agent behavior rules loaded on demand: when a task matches an SOP's when_to_use or name, read the complete SOP before following its process or rules.

Storage and precedence

Scope	Path	Purpose
Built-in	skills/meta/agent-sops/sops/*.md	SOPs distributed with the package.
User	~/.csl-agent-kit/sops/*.md	User-created SOPs that apply across projects.
Project	<workspace>/.agents/sops/*.md	Version-controlled SOPs specific to the current workspace.

For the same frontmatter name, precedence is project, then user, then built-in. Only the highest-precedence SOP is listed or routed.

SOP file format

Every SOP must begin with YAML frontmatter containing at least:

---
name: deploy-production
description: Deploy the production service safely.
when_to_use: Use when deploying the production service or investigating production deploy failures.
---

Use kebab-case for name. All frontmatter values must be English. Keep description brief. when_to_use must state when the SOP applies; it is the primary routing and summary field.

Optional fields:

version: 1.0
update_date: 2026-07-08
do_not_use_when:
  - Use another SOP when uploading releases or publishing remote artifacts.
globs:
  - "**/*.swift"
alwaysApply: false

Use do_not_use_when to prevent false positives. When a task matches both when_to_use and do_not_use_when, do not apply the SOP unless the user explicitly selects it.

Routing keywords

Prompt-time candidate matching scores keywords derived automatically from name, when_to_use, and globs (penalized by do_not_use_when); there is no separate keyword field. When generating or updating any SOP, make its routing fields matchable:

• Put concrete, distinctive terms in name and when_to_use: product or component names (e.g. Kanshan), specific techniques or formats (e.g. green-screen, Glyph JSON, DMG, Sparkle appcast), and stable tool or platform names.
• Prefer terms a user would literally type when requesting the task; an exact name hit scores highest, hyphen-separated name words also match.
• Do not rely on generic words (use, when, project, file, build, 用于); they are stopwords or weak signals and are filtered or scored low.
• Use do_not_use_when phrases that literally echo the adjacent SOP's distinctive terms, so the penalty fires on overlapping requests.
• Keep when_to_use one sentence; list the distinctive terms naturally instead of stuffing a keyword list.