Skip to main content

​
Usage

A path-triggered rule is an ordinary skill with a paths: glob in its frontmatter. Whenever the agent touches a file (reads, edits, or creates it) whose workspace-relative path matches one of those globs, the rule’s content is folded into the tool result the agent reads next — so the guidance is guaranteed to be present exactly when the agent is working on the matching file. Unlike keyword-triggered skills, rules are not advertised in <available_skills> and cannot be invoked by the model. They add zero baseline cost to the context window: nothing is loaded until a matching file is actually touched, and each rule is injected only once per conversation.
Use path-triggered rules for scoped conventions that should apply automatically when specific files are edited — e.g. “validate all request inputs with zod” for src/api/**/*.ts, or “keep migrations reversible” for db/migrations/**.

​
Frontmatter Syntax

Frontmatter is required for path-triggered rules. Enclose it in triple dashes (---) at the top of the file, above the guidelines.
FieldDescriptionRequiredDefault
pathsGlob patterns (YAML list or comma-separated string) that scope the rule.YesNone
A file that declares both paths: and triggers: becomes a path-triggered rule — paths: wins. This keeps rules deterministic and out of the model-invocable catalog.

​
Glob Semantics

Patterns use gitignore-style matching against the workspace-relative POSIX path (matching is case-sensitive):
PatternMatches
**Any number of path segments, including zero (crosses /).
*Any run of characters within a single path segment.
?A single non-separator character.
*.ts (no slash)The basename at any depth — equivalent to **/*.ts.
* also matches leading-dot files (e.g. src/* matches src/.env).

​
Example

Here’s a rule located at .agents/skills/api-validation.md: 
---
paths:
  - "src/api/**/*.ts"
  - "**/*.route.ts"
---

API RULE: validate all request inputs with zod before using them.
Reject unknown fields and return a 400 with the validation error.
When the agent creates or edits src/api/users.ts, the rule content is appended to that tool result inside an <EXTRA_INFO> block: 
<EXTRA_INFO>
The following rule applies because a file you touched matches "src/api/**/*.ts". Follow it when working with matching files.
Rule location: /repo/.agents/skills/api-validation.md

API RULE: validate all request inputs with zod before using them.
Reject unknown fields and return a 400 with the validation error.
</EXTRA_INFO>
Path-triggered rules load from the same skills directories as other skills (.agents/skills/, .openhands/skills/, …). They are repo-scoped: touching a file outside the workspace never fires a rule. Injection is available for local conversations; ACP-backed conversations do not inject path rules because the ACP server owns tool execution.
See the SDK guide for the programmatic PathTrigger API.