SubAgentConfig missing skill_dirs: sub-agents cannot load skills from config.hcl

[zoubo9034]

Summary

Sub-agents spawned via Orchestrator.spawn_subagent() cannot find skills defined in the parent session's config.hcl skill_dirs. The Skill tool returns "Skill 'xxx' not found" for any skill the sub-agent tries to call. SubAgentConfig exposes agent_dirs for agent definitions but has no equivalent skill_dirs parameter for skills.

---

Current Behavior

When a sub-agent calls the Skill tool to invoke a skill that exists in the parent's skill_dirs:

Tool execution error: Skill 'xxxxxxx' not found [permanent — do not retry without changing the arguments]

The skill file exists at the correct path, is properly formatted (YAML frontmatter with name, kind, allowed-tools as comma-separated string), and works in the parent session. But the sub-agent's isolated session cannot find it.

Expected Behavior

Sub-agents should be able to use skills defined in config.hcl's skill_dirs, either by:

1. Inheriting skill_dirs from the parent session's config.hcl automatically, or
2. Accepting an explicit skill_dirs parameter in SubAgentConfig (like agent_dirs)

Reproduction

config.hcl

model = "claude-sonnet-4-20250514"
skill_dirs = ["/absolute/path/to/skills"]
agent_dirs = ["./agents"]

mcp_servers {
  my_service { ... }
}

Skill file: skills/my-skill.md

---
name: my-skill
description: "A tool skill"
kind: tool
allowed-tools: "mcp__my_service__(*), Bash(*), Read(*)"
---

# My Skill

Instructions for the skill...

Agent file: agents/my-agent.md

---
name: my-agent
description: "Scoring agent"
mode: subagent
permissions:
  allow:
    - "Skill(*)"
    - "Bash(*)"
    - "Read"
---

Use the `my-skill` skill to perform the task.

Python code

from a3s_code import Agent, Orchestrator, SubAgentConfig

agent = Agent.create("config.hcl")
orchestrator = Orchestrator.create(agent=agent)

handle = orchestrator.spawn_subagent(SubAgentConfig(
    agent_type="my-agent",
    prompt="Use the my-skill skill to analyze this data",
    workspace="/absolute/path/to/project",
    permissive=True,
))

result = handle.wait()
# Sub-agent output: "Skill 'my-skill' not found"

Root Cause Analysis

SubAgentConfig signature:

SubAgentConfig(agent_type, prompt, description=None, permissive=False,
               permissive_deny=None, max_steps=None, timeout_ms=None,
               parent_id=None, workspace=None, agent_dirs=None, lane_config=None)

Parameter	Purpose	Status
agent_dirs	Directories for agent .md definitions	✅ Available
skill_dirs	Directories for skill .md definitions	❌ Missing
workspace	Sets CWD for sub-agent	✅ Available (but does NOT load config.hcl from it)

Sub-agents are isolated child sessions. Agent definitions work because agent_dirs is passed explicitly. But there is no equivalent for skills, and the parent's config.hcl skill_dirs are not inherited.

Proposed Solution

Option A (preferred): Add skill_dirs to SubAgentConfig

SubAgentConfig(
    agent_type="my-agent",
    prompt="...",
    workspace="/path/to/project",
    agent_dirs=["/path/to/agents"],
    skill_dirs=["/path/to/skills"],  # NEW
)

Option B: Auto-inherit from parent config

When workspace points to a directory containing config.hcl, the sub-agent session should load both agent_dirs and skill_dirs from that config file, just like the parent session does.

Impact

This is a blocking issue for the Skill Tool architecture (issue #8). The Skill Tool was designed so sub-agents call MCP tools indirectly through skills (with permissive_deny blocking direct MCP access). Without skill_dirs inheritance, sub-agents cannot find any skills, making the entire pattern unusable.

Current workaround: embed skill instructions directly in the sub-agent prompt and remove permissive_deny to allow direct MCP tool access, which defeats the purpose of the Skill Tool isolation architecture.

Environment

• a3s-code SDK (Python bindings)
• Related: issue Feature Request: Implement Skill Tool Mechanism for Enforcing Skill-Based Tool Access #8 (Skill Tool mechanism)

[ZhiXiao-Lin]

Fixed in commit 4211440.

Added skill_dirs parameter to SubAgentConfig and AgentSlot, allowing sub-agents to load skills from custom directories.

Changes

• Added skill_dirs field to SubAgentConfig and AgentSlot structs
• Added with_skill_dirs() builder method
• Sub-agent sessions now pass skill_dirs to SessionOptions
• Updated Python SDK (PySubAgentConfig, PyAgentSlot)
• Updated Node.js SDK (SubAgentConfig, AgentSlot)

Usage Example

Python:

from a3s_code import Agent, Orchestrator, SubAgentConfig

agent = Agent.create("config.hcl")
orchestrator = Orchestrator.create(agent=agent)

handle = orchestrator.spawn_subagent(SubAgentConfig(
    agent_type="my-agent",
    prompt="Use the my-skill skill to analyze this data",
    workspace="/absolute/path/to/project",
    agent_dirs=["/path/to/agents"],
    skill_dirs=["/path/to/skills"],  # NEW - skills now accessible
    permissive=True,
))

result = handle.wait()

Node.js:

const handle = orchestrator.spawnSubagent({
  agentType: 'my-agent',
  prompt: 'Use the my-skill skill',
  workspace: '/path/to/project',
  agentDirs: ['/path/to/agents'],
  skillDirs: ['/path/to/skills'],  // NEW
  permissive: true,
});

The fix will be included in the next release (v1.4.3).