[DOCS] Clarify Skills Architecture: "Agent VM" vs Filesystem-Based Implementation

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

Section/Topic

Agent Skills

Current Documentation

The official Anthropic engineering article "Equipping agents for the real world with agent skills" presents skills as part of an "agent virtual machine" with bundled resources, but the actual implementation uses filesystem-based disk I/O without isolation. This creates false expectations about security and isolation.

The article shows this architecture diagram:
!Agent VM Architecture

Skills are depicted as part of the "agent virtual machine" alongside "tools" and "context window," with "bundled resources" (scripts, instructions, files) that give agents additional capabilities.

Implications of this presentation:

• Skills appear to be VM-isolated from the filesystem
• "Bundled resources" suggests packaged assets accessible without filesystem access
• Users might expect skills to work even with strict filesystem deny rules
• Security model appears to isolate skill resources from user's filesystem

What's Wrong or Missing?

Custom skills are actually:

• File-based (SKILL.md in directories)
• Read from disk via file I/O when invoked
• Dynamically loaded into context
• Consume token budget on each read

When skills reference "bundled" files:

1. Agent constructs filesystem path (e.g., ~/.claude/skills/template-scaffolding/templates/file.md)
2. Agent uses Read tool or Bash to access via filesystem
3. Subject to filesystem permissions and deny rules

Security Implications:

1. False isolation expectations: Users might architect skills assuming VM isolation that doesn't exist
2. Permission confusion: Combined with #6631 (Read/Write tools ignore deny rules), creates inconsistent security model
3. Deny rule conflicts: Skills in ~/.claude/skills/ may be inaccessible if user has ~/.claude in deny list, even though skills are "official" configuration
4. Documentation gap: No clear guidance that "bundled resources" = "files agent reads from skill directory via filesystem"

Suggested Improvement

Update documentation to clarify:

1. In the article: Add note that custom skills are filesystem-based, unlike built-in skills
2. In Claude Code docs: Explicitly state that:

• Custom skills = files read from .claude/skills/ directories
• "Bundled resources" = files in skill directory accessed via normal filesystem tools
• Skills are NOT VM-isolated
• Skill files are subject to filesystem permissions

1. Best practices: Guide users on permission configuration for skill directories

Impact

Medium - Makes feature difficult to understand

Additional Context

Related Issues

• #10067 - Architecture differences between built-in and custom skills (confirms file-based implementation)
• #6631 - Read/Write tools ignore deny rules (exacerbates permission confusion)
• #10833 - Skill-level permissions (acknowledges skills are "just markdown files")

Questions

1. Is VM-based skill isolation on the roadmap?
2. Should built-in skills vs custom skills be more clearly differentiated in documentation?
3. Should ~/.claude/skills/ have special permission handling (auto-allowed for skill resources)?