@@ -4,6 +4,12 @@ mini-coder supports both its native `.agents` convention and `.claude` layouts f
44
55 Only commands, skills, agents, and context files are loaded from these roots. Hook directories are ignored.
66
7+Discovery is not identical for every config type:
8+
9+- **Commands** and **agents** are loaded from the current working directory and the home directory only.
10+- **Skills** are loaded from the home directory plus local directories discovered by walking up from the current working directory to the git worktree root.
11+- **Context files** are only loaded from the current working directory and the home directory.
12+
713 ## Supported config roots
814
915 | Root | Purpose |
@@ -42,23 +48,23 @@ Filename becomes the command name (`review.md` => `/review`).
4248
4349 Supported locations:
4450
45-- `./.agents/skills/<skill-name>/SKILL.md`
46-- `~/.agents/skills/<skill-name>/SKILL.md`
47-- `./.claude/skills/<skill-name>/SKILL.md`
48-- `~/.claude/skills/<skill-name>/SKILL.md`
51+- local: `./.agents/skills/<skill-name>/SKILL.md` and `./.claude/skills/<skill-name>/SKILL.md`
52+- global: `~/.agents/skills/<skill-name>/SKILL.md` and `~/.claude/skills/<skill-name>/SKILL.md`
53+
54+For local skills, mini-coder searches not just the current working directory, but each ancestor directory up to the git worktree root.
4955
5056 Format:
5157
5258 ```md
5359 ---
54-name: optional-skill-name
55-description: Optional help text
60+name: required-skill-name
61+description: Required help text
5662 ---
5763
5864 Skill instructions/content.
5965 ```
6066
61-If `name` is omitted, folder name is used.
67+Both `name` and `description` are required. Invalid skills are skipped with a warning.
6268
6369 ## Agents
6470
@@ -107,5 +113,6 @@ Precedence rules for commands, skills, and agents:
107113
108114 1. **Local overrides global**
109115 2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same name, **`.agents` wins**
116+3. For **skills only**, when the same skill name exists in multiple local ancestor directories, the skill nearest to the current working directory wins
110117
111-When same-scope conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.
118+When same-scope `.agents` / `.claude` conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.