fix: workspace skill prompt injection and guidance for skill access t…

[omeraplak]

…ools

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

What is the new behavior?

fixes (issue)

• [BUG] System prompt incorrectly injects full skill instructions and lacks skill access guidance #1045

Notes for reviewers

---

Summary by cubic

Limit workspace skill prompt injection to metadata and add clear guidance to access skills via workspace tools, improving safety and reducing prompt size. Fixes #1045.

• Bug Fixes
  • Inject only activated skill metadata (name, id, description); do not embed SKILL.md instruction bodies.
  • Update skills system prompt to use workspace skill tools and avoid sandbox commands (e.g., execute_command, ls /skills, cat ...).
  • Add tests for metadata-only injection and guidance text.
  • Update docs to clarify metadata injection and using workspace_read_skill for full instructions.

^{Written for commit bef9636. Summary will update on new commits.}

Summary by CodeRabbit

Release Notes

• Improvements

  • Skill prompts now display only metadata (name, ID, description) instead of full instruction bodies for activated skills.
  • Skill descriptions are automatically truncated for improved readability.
  • Workspace system prompts now provide clearer guidance on skill tool usage.

• Documentation

  • Updated documentation clarifying that injected skill prompts include metadata and full instructions are accessible via dedicated workspace tools.

[changeset-bot]

🦋 Changeset detected

Latest commit: bef9636

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@voltagent/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR modifies how workspace skills are presented to agents by replacing full SKILL.md instruction injection with metadata-only approach (name, id, description), updates the system prompt to guide agents toward workspace skill tools, and refactors skill listing logic to eliminate per-skill async loading operations.

Changes

Cohort / File(s)	Summary
Changeset Documentation .changeset/curly-ants-provide.md	Patch release note documenting the shift from full skill instructions to metadata-only injection and system prompt clarification.
Core Implementation packages/core/src/workspace/skills/index.ts	Updated SKILLS_SYSTEM_PROMPT with expanded guidance and tool names; refactored activated/available skills listing to use truncation strategy and eliminate per-skill async loading via loadSkill.
Test Suite packages/core/src/workspace/skills/index.spec.ts	Added 51 lines of tests verifying prompt generation includes skill metadata only (excluding full instructions) and confirming workspace skill tool guidance is present in output.
User Documentation website/docs/workspaces/skills.md	Updated documentation to clarify that injected prompts now contain skill metadata and that full instructions can be accessed via workspace_read_skill.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [BUG] System prompt incorrectly injects full skill instructions and lacks skill access guidance #1045: This PR directly addresses the code-level changes in packages/core/src/workspace/skills/index.ts mentioned in the issue, implementing skill metadata-only injection and system prompt refinements for workspace skill tool guidance.

Poem

🐰 Once skills were stuffed with endless lore,
Now metadata's the prompt core!
No more async hops, no more delay—
Just names and IDs light the way! 🌟
Agents hop wisely, tool by tool bright! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: fixing workspace skill prompt injection and adding guidance for skill access tools, which aligns with the core modifications across multiple files.
Description check	✅ Passed	The description follows the template with all required sections completed, including checklist items, current/new behavior, issue links, and a comprehensive auto-generated summary by cubic detailing the bug fixes and changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/workspace-skill

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/core/src/workspace/skills/index.spec.ts (1)

185-197: System prompt guidance assertions look solid.

Validates the three key aspects of the updated SKILLS_SYSTEM_PROMPT: tool-only access directive, sandbox command prohibition, and presence of the new tool names. Consider also asserting workspace_read_skill_asset if you want full tool coverage, though this is optional.

---

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.}

[cubic-dev-ai]

No issues found across 4 files

[cloudflare-workers-and-pages]

Deploying voltagent with    Cloudflare Pages

Latest commit:	bef9636
Status:	✅  Deploy successful!
Preview URL:	https://923776b1.voltagent.pages.dev
Branch Preview URL:	https://fix-workspace-skill.voltagent.pages.dev

View logs