OpenHands · rajshah4 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/docs.json b/docs.json
@@ -64,6 +64,7 @@
                   "overview/skills",
                   "overview/skills/repo",
                   "overview/skills/keyword",
+                  "overview/skills/path",
                   "overview/skills/org",
                   "overview/skills/public",
                   "overview/skills/adding",

diff --git a/overview/skills.mdx b/overview/skills.mdx
@@ -17,12 +17,13 @@
 
 Skills inject additional context and rules into the agent's behavior.
 
-At a high level, OpenHands supports two loading models:
+At a high level, OpenHands supports three loading models:
 
 - **Always-on context** (e.g., `AGENTS.md`) that is injected into the system prompt at conversation start.
 - **On-demand skills** that are either:
   - **triggered by the user** (keyword matches), or
   - **invoked by the agent** (the agent decides to look up the full skill content).
+- **Path-triggered rules** that are injected deterministically when the agent reads, edits, or creates a file whose path matches a glob pattern.
 
 ## Permanent agent context (recommended)
 
@@ -82,17 +83,19 @@
 
 - **[Permanent Context](/overview/skills/repo)**: Repository-wide guidelines and best practices. We recommend `AGENTS.md` (and optionally `GEMINI.md` / `CLAUDE.md`).
 - **[Keyword-Triggered Skills](/overview/skills/keyword)**: Guidelines activated by specific keywords in user prompts.
+- **[Path-Triggered Rules](/overview/skills/path)**: Guidelines injected automatically when the agent touches files matching a glob pattern.
 - **[Organization Skills](/overview/skills/org)**: Team or organization-wide standards.
 - **[Global Skills](/overview/skills/public)**: Community-shared skills and templates.
 
 ### Skills Frontmatter Requirements

 Each skill file may include frontmatter that provides additional information. In some cases, this frontmatter is required:

 | Skill Type  | Required |
 |-------------|----------|
 | General Skills                           | No       |
 | Keyword-Triggered Skills                 | Yes      |
+| Path-Triggered Rules                     | Yes      |
 
 ## Skills Support Matrix
 
@@ -142,4 +145,4 @@
 - **For bundling multiple components**: See [Plugins](/overview/plugins)
 - **For SDK integration**: See [SDK Skills Guide](/sdk/guides/skill)
 - **For architecture details**: See [Skills Architecture](/sdk/arch/skill)
-- **For specific skill types**: See [Repository Skills](/overview/skills/repo), [Keyword Skills](/overview/skills/keyword), [Organization Skills](/overview/skills/org), and [Global Skills](/overview/skills/public)
+- **For specific skill types**: See [Repository Skills](/overview/skills/repo), [Keyword Skills](/overview/skills/keyword), [Path-Triggered Rules](/overview/skills/path), [Organization Skills](/overview/skills/org), and [Global Skills](/overview/skills/public)
diff --git a/overview/skills/creating.mdx b/overview/skills/creating.mdx
@@ -167,6 +167,27 @@
     - List concrete scenarios
     - Mention related tools or frameworks
   </Accordion>
+
+  <Accordion title="Path Triggers (Rules)">
+    Instead of keywords, scope a skill to files with a `paths:` glob. The skill
+    becomes a [path-triggered rule](/overview/skills/path) that OpenHands injects
+    automatically whenever the agent reads, edits, or creates a matching file — no
+    keyword or model decision needed:
+
+    ```yaml
+    ---
+    name: api-validation
+    paths:
+      - "src/api/**/*.ts"
+      - "**/*.route.ts"
+    ---
+    ```
+
+    **When to use:**
+    - Conventions tied to specific files (e.g. "validate request inputs with zod" for API routes)
+    - Guidance you want applied deterministically, without relying on trigger words
+    - `paths:` takes precedence over `triggers:` if a file declares both
+  </Accordion>
 </AccordionGroup>
 
 ### Examples of Good Triggers
@@ -479,7 +500,7 @@
   ls .agents/skills/your-skill/SKILL.md
   ```

 2. **Check frontmatter**: Ensure YAML is valid with `name`, `description`, and `triggers`

 3. **Test trigger keywords**: Use a trigger word in a prompt:
   ```
@@ -491,7 +512,7 @@
 5. **Iterate**: Improve based on actual usage

 <Info>
 For production deployments, see [Monitoring and Improving Skills](/overview/skills/monitoring) to track performance using logging, evaluation metrics, dashboarding, and automated feedback aggregation.
 </Info>

 ## Common Mistakes to Avoid

diff --git a/overview/skills/path.mdx b/overview/skills/path.mdx
@@ -0,0 +1,85 @@
+---
+title: Path-Triggered Rules
+description: Path-triggered rules are skills that OpenHands injects deterministically whenever the agent reads, edits, or creates a file whose path matches a glob pattern. They behave like Claude Code "rules" — guaranteed to load for the files they scope, with no reliance on the model choosing them.
+---
+
+## 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](/overview/skills/keyword), 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.
+
+<Info>
+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/**`.
+</Info>
+
+## Frontmatter Syntax
+
+Frontmatter is required for path-triggered rules. Enclose it in triple dashes (`---`) at the top of
+the file, above the guidelines.
+
+| Field   | Description                                                        | Required | Default |
+|---------|--------------------------------------------------------------------|----------|---------|
+| `paths` | Glob patterns (YAML list or comma-separated string) that scope the rule. | Yes      | None    |
+
+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):
+
+| Pattern            | Matches                                                                 |
+|--------------------|-------------------------------------------------------------------------|
+| `**`               | 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`:
+
+```markdown
+---
+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:
+
+```xml
+<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>
+```
+
+<Note>
+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.
+</Note>
+
+[See the SDK guide for the programmatic `PathTrigger` API](/sdk/guides/skill#path-triggered-rules).
@@ -12,7 +12,7 @@
 The Skill system has five primary responsibilities:
 
 1. **Context Injection** - Add specialized prompts to agent context based on triggers
-2. **Trigger Evaluation** - Determine when skills should activate (always, keyword, task)
+2. **Trigger Evaluation** - Determine when skills should activate (always, keyword, task, path)
 3. **Dynamic Content Rendering** - Execute inline shell commands for dynamic context injection
 4. **MCP Integration** - Load MCP tools associated with repository skills
 5. **Third-Party Support** - Parse `.cursorrules`, `agents.md`, and other skill formats
@@ -26,12 +26,14 @@
         Repo["Repository Skill<br><i>trigger: None</i>"]
         Knowledge["Knowledge Skill<br><i>trigger: KeywordTrigger</i>"]
         Task["Task Skill<br><i>trigger: TaskTrigger</i>"]
+        Rule["Path Rule<br><i>trigger: PathTrigger</i>"]
     end
 
     subgraph Triggers["Trigger Evaluation"]
         Always["Always Active<br><i>Repository guidelines</i>"]
         Keyword["Keyword Match<br><i>String matching on user messages</i>"]
         TaskMatch["Keyword Match + Inputs<br><i>Same as KeywordTrigger + user inputs</i>"]
+        PathMatch["File-Touch Match<br><i>Glob match on touched file path</i>"]
     end
 
     subgraph Content["Skill Content"]
@@ -44,15 +46,18 @@
     subgraph Integration["Agent Integration"]
         Context["Agent Context"]
         Prompt["System Prompt"]
+        ToolResult["Tool Result<br><i>Rules injected on file-touch</i>"]
     end
 
     Repo --> Always
     Knowledge --> Keyword
     Task --> TaskMatch
+    Rule --> PathMatch
 
     Always --> Markdown
     Keyword --> Markdown
     TaskMatch --> Markdown
+    PathMatch --> ToolResult
 
     Markdown -.->|Optional| Dynamic
     Repo -.->|Optional| MCPTools
@@ -68,9 +73,9 @@
     classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px
     classDef dynamic fill:#e9f9ef,stroke:#2f855a,stroke-width:2px
 
-    class Repo,Knowledge,Task primary
-    class Always,Keyword,TaskMatch secondary
-    class Context tertiary
+    class Repo,Knowledge,Task,Rule primary
+    class Always,Keyword,TaskMatch,PathMatch secondary
+    class Context,ToolResult tertiary
     class Dynamic dynamic
 ```
 
@@ -78,12 +83,13 @@

 | Component | Purpose | Design |
 |-----------|---------|--------|
 | **[`Skill`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/skill.py)** | Core skill model | Pydantic model with name, content, trigger |
 | **[`KeywordTrigger`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/trigger.py)** | Keyword-based activation | String matching on user messages |
 | **[`TaskTrigger`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/trigger.py)** | Task-based activation | Special type of KeywordTrigger for skills with user inputs |
+| **[`PathTrigger`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/skills/trigger.py)** | Path-based activation ("rules") | Glob match on a touched file path; injected into the tool result, not model-invocable |
 | **[`InputMetadata`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/types.py)** | Task input parameters | Defines user inputs for task skills |
 | **[`render_content_with_commands`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/skills/execute.py)** | Dynamic content | Executes inline `!`command`` patterns |
 | **Skill Loader** | File parsing | Reads markdown with frontmatter, validates schema |

 ## Skill Types

@@ -209,6 +215,47 @@
 
 **Note:** TaskTrigger uses the same keyword matching mechanism as KeywordTrigger. The distinction is semantic - TaskTrigger is used for skills that require structured user inputs, while KeywordTrigger is for knowledge-based skills.
 
+### Path Skills (Rules)
+
+Skills that are injected **deterministically** when the agent touches a matching file, modeled on Claude Code "rules":
+
+```mermaid
+%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%%
+flowchart TB
+    Touch["Agent Reads/Edits/Creates File"]
+    Match{"Path Matches<br>Glob?"}
+    Inject["Inject into Tool Result"]
+    Skip["Skip Rule"]
+    Dedup["Dedup: once per conversation"]
+
+    Touch --> Match
+    Match -->|Yes| Dedup
+    Match -->|No| Skip
+    Dedup --> Inject
+
+    style Match fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
+    style Inject fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
+```
+
+**Characteristics:**
+- **Trigger:** `PathTrigger` with gitignore-style `paths` globs (matched against the workspace-relative POSIX path)
+- **Activation:** The agent reads, edits, or creates a file whose path matches a glob (fires on `create` too)
+- **Injection point:** Folded into the `ObservationEvent` tool result (`extended_content`) as an `<EXTRA_INFO>` block — **not** the user message
+- **Baseline cost:** Zero — excluded from `<available_skills>` and `<REPO_CONTEXT>`; `disable_model_invocation` is forced, so rules are never model-invocable
+- **Dedup:** Each rule is injected only once per conversation (tracked via `ConversationState.activated_path_rules`)
+- **Location:** Any skills directory (e.g. `.agents/skills/*.md`) — a rule is just a skill with `paths:` frontmatter
+
+**Trigger Example:**
+```yaml
+---
+paths:
+  - "src/api/**/*.ts"
+  - "**/*.route.ts"
+---
+```
+
+**Note:** A skill is either path-triggered or model-invocable, not both — if a file declares both `paths:` and `triggers:`, `paths:` wins. Path-rule injection applies to local conversations; ACP-backed conversations do not inject rules because the ACP server owns tool execution.
+
 ## Trigger Evaluation
 
 Skills are evaluated at different points in the agent lifecycle:
@@ -258,6 +305,7 @@
 | **None** | Every step | Always active |
 | **KeywordTrigger** | On user message | Keyword/string match in message |
 | **TaskTrigger** | On user message | Keyword/string match in message (same as KeywordTrigger) |
+| **PathTrigger** | On tool observation | Glob match on the touched file's path (read/edit/create) |
 
 **Note:** Both KeywordTrigger and TaskTrigger use identical string matching logic. TaskTrigger is simply a semantic variant used for skills that include user input parameters.
 
@@ -298,7 +346,7 @@
 ```

 **Workflow:**
 1. **Load Skill:** Parse markdown file with frontmatter
 2. **Extract MCP Config:** Read `mcp_tools` field
 3. **Spawn MCP Servers:** Create MCP clients for each server
 4. **Register Tools:** Add MCP tools to agent's tool registry
@@ -309,7 +357,7 @@
 Skills support inline command execution for injecting dynamic context at render time:

 1. Parse content for `` !`cmd` `` patterns outside code blocks
 2. Execute each command via subprocess
 3. Replace pattern with stdout (or error marker)
 4. Return rendered content

@@ -327,7 +375,7 @@

 ## Skill File Format

 Skills are defined in markdown files with YAML frontmatter:

 ```markdown
 ---
@@ -340,7 +388,7 @@
 # Skill Content

 This is the instruction text that will be added to the agent's context.
 Dynamic values: !`git branch --show-current`
 ```

 **Frontmatter Fields:**
@@ -349,6 +397,7 @@
 |-------|----------|-------------|
 | **name** | Yes | Unique skill identifier |
 | **trigger** | Yes* | Activation trigger (`null` for always active) |
+| **paths** | No | Glob patterns that make the skill a path-triggered rule (`PathTrigger`); takes precedence over `triggers` |
 | **mcp_tools** | No | MCP server configuration (repo skills only) |
 | **inputs** | No | User input metadata (task skills only) |
 

@@ -19,6 +19,7 @@
 | **AgentSkills** (`SKILL.md`) | Has triggers | `<available_skills>` + auto-inject on match | ✅ Yes |
 | **Legacy** (inline/`*.md`) | `None` | **`<REPO_CONTEXT>` (full content in the initial system prompt; included in LLM context for each turn)** | ❌ No |
 | **Legacy** (inline/`*.md`) | Has triggers | `<available_skills>` + auto-inject on match | ✅ Yes |
+| **Rule** (inline/`*.md`) | `PathTrigger` (`paths:` globs) | Injected into the **tool result** (`<EXTRA_INFO>`) when a matching file is touched; never in `<available_skills>` or `<REPO_CONTEXT>` | ❌ No — deterministic on file-touch |
 
 <Warning>
 **Token Usage Warning**: Legacy skills with `trigger=None` add their **full content** to `<REPO_CONTEXT>` in the initial `SystemPromptEvent`. That system message remains part of the conversation context for subsequent LLM calls, so the content still affects token usage on each turn. Consider using AgentSkills format (`SKILL.md`) for progressive disclosure instead.
@@ -66,6 +67,7 @@
 |--------|-------------------|----------|
 | **Always-loaded** | At conversation start | Repository rules, coding standards |
 | **Trigger-loaded** | When keywords match | Specialized tasks, domain knowledge |
+| **Path-triggered** | When the agent touches a matching file | File-scoped rules (e.g. API validation, migration conventions) |
 | **Progressive disclosure** | Agent reads on demand | Large reference docs (AgentSkills) |
 
 ## Always-Loaded Context
@@ -81,7 +83,7 @@

 # Automatically finds AGENTS.md, CLAUDE.md, GEMINI.md at workspace root
 skills = load_project_skills(workspace_dir="/path/to/repo")
 agent_context = AgentContext(skills=skills)
 ```

 ### Option 2: Inline Skill (Code-defined)
@@ -130,6 +132,69 @@
 </EXTRA_INFO>
 ```
 
+## Path-Triggered Rules
+
+A **rule** is a skill with a `PathTrigger` (`paths:` glob frontmatter). Its content is injected
+**deterministically** when the agent reads, edits, or creates a file whose workspace-relative path
+matches one of the globs — no reliance on the model choosing a skill. See [Path-Triggered Rules](/overview/skills/path)
+for the conceptual overview.
+
+Rules add **zero baseline cost**: they are excluded from `<available_skills>` and `<REPO_CONTEXT>`
+and are never model-invocable (`disable_model_invocation` is forced on). Nothing is loaded until a
+matching file is touched, and each rule is injected only once per conversation.
+
+```python icon="python" focus={6}
+from openhands.sdk.skills import PathTrigger, Skill
+
+Skill(
+    name="api-validation",
+    content="API RULE: validate all request inputs with zod before using them.",
+    trigger=PathTrigger(paths=["src/api/**/*.ts", "**/*.route.ts"]),
+)
+```
+
+As a file-based skill, this is just a `*.md` file with `paths:` frontmatter in a skills directory
+(e.g. `.agents/skills/api-validation.md`):
+
+```markdown icon="markdown"
+---
+paths:
+  - "src/api/**/*.ts"
+  - "**/*.route.ts"
+---
+
+API RULE: validate all request inputs with zod before using them.
+```
+
+When the agent creates or edits `src/api/users.ts`, the rule content is appended to that **tool
+result** (not the user message) inside an `<EXTRA_INFO>` block, so the agent reads it on its next step:
+
+```xml icon="file"
+<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.
+</EXTRA_INFO>
+```
+
+### Glob Semantics
+
+Patterns use gitignore-style matching against the workspace-relative POSIX path (case-sensitive):
+
+| Pattern           | Matches                                                       |
+|-------------------|---------------------------------------------------------------|
+| `**`              | 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`.      |
+
+<Note>
+- A skill is **either** path-triggered **or** model-invocable, not both: if a file declares both `paths:` and `triggers:`, `paths:` wins.
+- Rules 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.
+</Note>
+
 ## Progressive Disclosure (AgentSkills Standard)
 
 For the agent to trigger skills, use the [AgentSkills standard](https://agentskills.io/specification) `SKILL.md` format. The agent sees a summary and reads full content on demand.
@@ -627,7 +692,7 @@
 Skills are defined with a name, content (the instructions), and an optional trigger:

 ```python icon="python" focus={3-14}
 agent_context = AgentContext(
    skills=[
        Skill(
            name="AGENTS.md",
@@ -636,7 +701,7 @@
            trigger=None,  # Always active
        ),
        Skill(
            name="flarglebargle",
            content='IMPORTANT! The user has said the magic word "flarglebargle". '
                    "You must only respond with a message telling them how smart they are",
            trigger=KeywordTrigger(keywords=["flarglebargle"]),
@@ -689,7 +754,7 @@

 | Component | Required | Description |
 |-------|----------|-------------|
 | `SKILL.md` | Yes | Skill definition with frontmatter |
 | `scripts/` | No | Executable scripts |
 | `references/` | No | Reference documentation |
 | `assets/` | No | Static assets |
@@ -698,7 +763,7 @@

 ### `SKILL.md` Format

 The `SKILL.md` file defines the skill with YAML frontmatter:

 ```md icon="markdown"
 ---
@@ -720,7 +785,7 @@
 Instructions and documentation for the agent...
 ```

 #### Frontmatter Fields

 | Field | Required | Description |
 |-------|----------|-------------|
@@ -888,7 +953,7 @@
 ```python icon="python" focus={3}
 from openhands.sdk.context.skills import load_skills_from_dir

 repo_skills, knowledge_skills, agent_skills = load_skills_from_dir(skills_dir)
 ```

 | Return Value | Source Files | Injection Behavior |
@@ -974,7 +1039,7 @@
 Enable public skills loading in your `AgentContext`:

 ```python icon="python" focus={2}
 agent_context = AgentContext(
    load_public_skills=True,  # Auto-load from public registry
    skills=[
        # Your custom skills here
@@ -1039,7 +1104,7 @@
 from openhands.sdk.context.skills import load_public_skills

 # Load from a custom repository
 custom_skills = load_public_skills(
    repo_url="https://github.com/my-org/my-skills",
    branch="main"
 )
@@ -1206,8 +1271,8 @@

 | Scenario | Output |
 |----------|--------|
 | Command fails | `[Error: Command `xyz` exited with code 1: error message]` |
 | Command times out | `[Error: Command `xyz` timed out after 10s]` |
 | Large output (>50KB) | Output truncated with `... [output truncated]` |

 ### Programmatic Rendering