feat(iii-directory): alias bare worker name to <worker>/index in skills::get

[andersonleal]

Summary

• directory::skills::get { id: "sandbox" } now resolves to the same body as { id: "sandbox/index" } whenever <skills_folder>/sandbox/index.md exists. The response carries the canonical id ("sandbox/index") so the agent still learns the real form on the way through.
• Mirrors the existing filesystem-side alias (SKILLS.md → index.md in fs_source::rel_to_id) onto the request side.
• Lookup-time fallback (find_fs_skill), not parse-time. Bare ids stay legitimate at the filesystem layer (hello.md at the skills root has id hello); the alias only fires when no exact match exists.

Why

LLM agents calling directory::skills::get reach for the worker name (sandbox, provider-lmstudio) when they want the worker overview — it's the shortest form and the one already referenced in our own error hints. The bare form previously failed with Skill not found: <worker>, surfacing through the gate as gate_unavailable / handler error. Observed in QA against zai-org/glm-4.7-flash (sandbox flow): the agent burned turns recovering from this exact miss.

Guard rails

Pinned via tests:

• Multi-segment ids match literally — sandbox/exec does NOT auto-alias to sandbox/exec/index. Without this guard, a typo would silently resolve to the wrong skill.
• Literal root skill wins over the alias — if both <root>/sandbox.md and <root>/sandbox/index.md exist, bare sandbox returns the literal root skill.

Test plan

• cargo test --lib — 4 new unit tests pass:
  • get_accepts_bare_worker_name_as_alias_for_index
  • bare_name_and_explicit_index_return_same_body
  • multi_segment_id_does_not_auto_alias_to_slash_index
  • bare_id_with_literal_root_skill_wins_over_index_alias
• cargo test --lib functions::skills::tests — 54 passed (50 pre-existing + 4 new), 0 regressions.
• cargo test --test bdd — new Gherkin scenario (bare worker name as alias for <worker>/index) passes all 5 steps. 6 pre-existing failures remain in directory::engine::trigger-types::list / workers::list / function-info schema, none touch directory::skills::get — same engine-side breakage from commit 241509a.
• cargo fmt -- --check — clean.
• Operator: rebuild & restart iii-directory worker so the new binary loads. Manual smoke:
  • iii trigger directory::skills::get '{"id":"sandbox"}' → returns { "id": "sandbox/index", ... }.
  • iii trigger directory::skills::get '{"id":"sandbox/index"}' → identical body.
  • iii trigger directory::skills::get '{"id":"sandbox/exec"}' → returns the literal sandbox/exec how-to (no alias cascade).
  • iii trigger directory::skills::get '{"id":"no-such-worker"}' → existing not-found hint mentioning directory::skills::list and directory::skills::index.

Summary by CodeRabbit

Release Notes

• New Features

  • Skill lookups now support shorthand aliasing: a bare worker name resolves to worker/index.

• Bug Fixes

  • Enhanced error messages for missing skills include helpful guidance on available resources.

• Tests

  • Added verification for shorthand alias resolution and lookup precedence.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview, Comment	May 21, 2026 7:33pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 19edb237-a91b-45ea-ae17-b87253a8456a

📥 Commits

Reviewing files that changed from the base of the PR and between 89ad21e and 9a8264c.

⛔ Files ignored due to path filters (1)

• iii-directory/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (2)

• iii-directory/src/functions/skills.rs
• iii-directory/tests/features/read.feature

---

📝 Walkthrough

Walkthrough

The PR enhances skill lookup resolution by introducing bare worker name aliasing and improving error diagnostics. get_skill now surfaces richer "not found" errors with remediation guidance. find_fs_skill supports shorthand lookup (bare names resolve to <id>/index) while respecting precedence: exact matches win over aliases, and multi-segment ids require explicit paths.

Changes

Skill lookup with aliasing and improved error guidance

Layer / File(s)	Summary
Enhanced error messaging iii-directory/src/functions/skills.rs	get_skill's missing-skill error path now includes explicit remediation hints referencing directory::skills::list and directory::skills::index; a test verifies the error message contains the requested id and the required guidance.
Bare worker name aliasing and precedence iii-directory/src/functions/skills.rs	find_fs_skill recognizes bare worker names as aliases for <worker>/index, enforces exact matching for multi-segment ids, and ensures literal root skills (<root>.md) take precedence over aliased paths. Comprehensive unit tests validate bare-name resolution, equivalence of bare vs. explicit <worker>/index, rejection of multi-segment auto-aliasing, and precedence rules.
Feature test for bare worker alias iii-directory/tests/features/read.feature	A Gherkin scenario confirms that directory::skills::get accepts a bare worker name and resolves it to the canonical <worker>/index id with matching response content.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• iii-hq/workers#131: Both PRs modify the skills resolution API (directory::skills::get and error handling) in iii-directory/src/functions/skills.rs, with #131 introducing the enriched API and the main PR extending it with alias lookup and improved error messages.

Suggested reviewers

• sergiofilhowz

Poem

🐰 A worker seeks their skills by name,
No need for slashes in the game—
Bare sandbox finds index bright,
With errors pointing the right way in sight.
Aliases dance, and precedence wins! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main feature: aliasing bare worker names to /index in skills::get. It is specific, clear, and directly reflects the primary change in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/iii-directory-bare-worker-alias

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

skill-check — worker

0 verified, 11 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓

Three for three. Nicely done.