xonecas.io
64875
Mc

mini-coder / commit 4f2e10f

docs: align skill docs and prune stale todo

xonecas2026-03-15 4f2e10f90493d959e236933f64b23b07f45a06b6 parent a77af2e

3 files changed

TODO.md+1−3
@@ -1,6 +1,6 @@
11 # TODO
22
3-- UI hangs for a short time before reasoning blocks. Reasoning blocks should use our colors library for italic styling.
3+- Reasoning blocks should use our colors library for italic styling.
44 - Assistant responses are no longer rendered with highlighted markdown syntax. It's just plain text with no coloring. Let's condider markdown rendering libraries and their performance costs and completly rethink our approach. We want to keep our fast output above all, even if that means no markdown rendering.
55
66 ---
@@ -26,7 +26,5 @@ We need to do research first and find an approach that fits the current shell-fi
2626
2727 ## Deferred fixes
2828
29-- model-info: in `resolveFromProviderRow`, when canonical capability exists but `contextWindow` is null, fall back to provider row context (`capability.contextWindow ?? row.contextWindow`).
30-- subagent-runner: avoid unconditional full buffering of child `stdout`/`stderr` in `runSubagent`; capture diagnostics only on failure or via a bounded tail buffer to prevent latency/memory regressions.
3129 - Subagent and shell tools are very similar, shell could do what subagent does without changes. This could be leveraged to reduce code. Subagent process runner is used for custom commands that fork context as well, there will need to be refactored.
3230 - `/_debug` hidden command that snapshots recent logs/db and creates a report in the cwd. For dev mostly but available to all. Do not list it anywhere, only documented here and in the code itself.
docs/configs.md+15−8
@@ -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.
docs/skills.md+5−3
@@ -34,16 +34,18 @@ If multiple skills share the same `name`, precedence is deterministic:
3434
3535 `SKILL.md` frontmatter supports:
3636
37-- `name` (optional — defaults to the folder name)
38-- `description` (optional — defaults to `"(no description)"`)
37+- `name` (**required**)
38+- `description` (**required**)
3939
40-`name` constraints (when provided):
40+`name` constraints:
4141
4242 - lowercase alphanumeric and hyphen format (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
4343 - 1–64 characters
4444
4545 Unknown frontmatter fields are allowed.
4646
47+If either `name` or `description` is missing, mini-coder skips the skill and prints a warning.
48+
4749
4850 ## Create a skill