Agents Skill: Missing explicit path to Traits.yaml causes agent read errors

[Steffen025]

Problem

When agents try to use the AgentFactory system, they frequently fail to read Traits.yaml because the documentation doesn't specify its location clearly.

Error observed:

Read(.claude/skills/Agents/Tools/Traits.yaml)
  ⎿  Error reading file

Root cause: Agents see AgentFactory.ts is in Tools/ and assume Traits.yaml is in the same directory.

Actual structure:

skills/Agents/
├── Tools/
│   └── AgentFactory.ts  ← The tool
└── Data/
    └── Traits.yaml      ← The data (NOT in Tools!)

Where the confusion comes from

In Packs/pai-agents-skill/src/skills/Agents/SKILL.md:

1. The CLI examples show:

   bun run $PAI_DIR/skills/Agents/Tools/AgentFactory.ts --traits "..."
   

2. The components section says:

   **Data/Traits.yaml** - 28 composable traits with voice mappings
   

But there's no explicit statement that Traits.yaml is in a different folder than AgentFactory.ts. Agents (and humans) naturally assume related files are co-located.

Suggested Fix

Add explicit path comments in the CLI usage section:

# Paths:
# - AgentFactory: $PAI_DIR/skills/Agents/Tools/AgentFactory.ts
# - Traits.yaml:  $PAI_DIR/skills/Agents/Data/Traits.yaml (NOT in Tools!)

bun run $PAI_DIR/skills/Agents/Tools/AgentFactory.ts --traits "..."

Or add a note in the Architecture section:

Note: Traits.yaml is in the Data/ folder, NOT in Tools/ where AgentFactory.ts lives.

Impact

This bug causes repeated failures when:

• Agents try to read traits for dynamic composition
• Users manually look up available traits
• Any workflow that needs to reference the traits file directly

---

Discovered while using PAI in production. Happy to submit a PR if preferred.