docs: Clarify skill naming and trigger behavior for custom skills

sdk/guides/github-workflows/pr-review.mdx

@@ -41,56 +41,73 @@ cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-r
 
 ## Customizing the Code Review
 
-Instead of forking the `agent_script.py`, you can customize the code review behavior by adding a `.agents/skills/code-review.md` file to your repository. This is the **recommended approach** for customization.
+Instead of forking the `agent_script.py`, you can customize the code review behavior by adding a skill file to your repository. This is the **recommended approach** for customization.
 
 ### How It Works
 
-The PR review agent uses skills from the [OpenHands/extensions](https://github.com/OpenHands/extensions) repository by default. When you add a `.openhands/skills/code-review.md` file to your repository, it **overrides** the default skill with your custom guidelines.
+The PR review agent uses skills from the [OpenHands/extensions](https://github.com/OpenHands/extensions) repository by default. You can add your project-specific guidelines alongside the default skill by creating a custom skill file.
+
+<Note>
+**Skill paths**: Place skills in `.agents/skills/` (recommended). The legacy path `.openhands/skills/` is also supported. See [Skill Loading Precedence](/overview/skills#skill-loading-precedence) for details.
+</Note>
 
 ### Example: Custom Code Review Skill
 
-Create `.openhands/skills/code-review.md` in your repository:
+Create `.agents/skills/custom-codereview-guide.md` in your repository:
 
 ```markdown
 ---
-name: code-review
-description: Custom code review guidelines for my project
+name: custom-codereview-guide
+description: Project-specific review guidelines for MyProject
 triggers:
 - /codereview
 ---
 
-# My Project Code Review Guidelines
+# MyProject-Specific Review Guidelines
 
-You are a code reviewer for this project. Follow these guidelines:
+In addition to general code review practices, check for:
 
-## Review Decisions
+## Project Conventions
 
-- **APPROVE** straightforward changes (config updates, typo fixes, documentation)
-- **COMMENT** when you have feedback or concerns
+- All API endpoints must have OpenAPI documentation
+- Database migrations must be reversible
+- Feature flags required for new features
 
-## What to Check
+## Architecture Rules
 
-- Code follows our project conventions
-- Tests are included for new functionality
-- No security vulnerabilities introduced
-- Documentation is updated if needed
+- No direct database access from controllers
+- All external API calls must go through the gateway service
 
 ## Communication Style
 
 - Be direct and constructive
 - Use GitHub suggestion syntax for code fixes
-- Approve quickly when code is good
 ```
 
+<Note>
+**Note**: These rules supplement the default `code-review` skill, not replace it.
+</Note>
+
+<Tip>
+**How skill merging works**: Using a unique name like `custom-codereview-guide` allows BOTH your custom skill AND the default `code-review` skill to be triggered by `/codereview`. When triggered, skill content is concatenated into the agent's context (public skills first, then your custom skills). There is no smart merging—if guidelines conflict, the agent sees both and must reconcile them.
+
+If your skill has `name: code-review` (matching the public skill's name), it will completely **override** the default public skill instead of supplementing it.
+</Tip>
+
+<Note>
+**Migrating from override to supplement**: If you previously created a skill with `name: code-review` to override the default, rename it (e.g., to `my-project-review`) to receive guidelines from both skills instead.
+</Note>
+
 ### Benefits of Custom Skills
 
 1. **No forking required**: Keep using the official SDK while customizing behavior
 2. **Version controlled**: Your review guidelines live in your repository
 3. **Easy updates**: SDK updates don't overwrite your customizations
 4. **Team alignment**: Everyone uses the same review standards
+5. **Composable**: Add project-specific rules alongside default guidelines
 
 <Note>
-See the [software-agent-sdk's own code-review skill](https://github.com/OpenHands/software-agent-sdk/blob/main/.agents/skills/code-review.md) for a complete example of a custom code review skill.
+See the [software-agent-sdk's own custom-codereview-guide skill](https://github.com/OpenHands/software-agent-sdk/blob/main/.agents/skills/custom-codereview-guide.md) for a complete example.
 </Note>
 
 ## Reference Workflow

sdk/guides/skill.mdx

@@ -608,7 +608,29 @@ When enabled, the SDK will:
 2. Load all available skills from the repository
 3. Merge them with your explicitly defined skills
 
-**Skill Precedence**: If a skill name conflicts, your explicitly defined skills take precedence over public skills.
+### Skill Naming and Triggers
+
+**Skill Precedence by Name**: If a skill name conflicts, your explicitly defined skills take precedence over public skills. For example, if you define a skill named `code-review`, the public `code-review` skill will be skipped entirely.
+
+**Multiple Skills with Same Trigger**: Skills with different names but the same trigger can coexist and will ALL be activated when the trigger matches. To add project-specific guidelines alongside public skills, use a unique name (e.g., `custom-codereview-guide` instead of `code-review`). Both skills will be triggered together.
+
+```python icon="python"
+# Both skills will be triggered by "/codereview"
+agent_context = AgentContext(
+    load_public_skills=True,  # Loads public "code-review" skill
+    skills=[
+        Skill(
+            name="custom-codereview-guide",  # Different name = coexists
+            content="Project-specific guidelines...",
+            trigger=KeywordTrigger(keywords=["/codereview"]),
+        ),
+    ]
+)
+```
+
+<Tip>
+**Skill Activation Behavior**: When multiple skills share a trigger, all matching skills are loaded. Content is concatenated into the agent's context with public skills first, then explicitly defined skills. There is no smart merging—if guidelines conflict, the agent sees both.
+</Tip>
 
 ### Programmatic Loading