TitleCase directory naming - rationale and Linux/WSL considerations?

[vichong]

I maintain a fork and recently aligned with upstream's TitleCase directory
convention (Skills/, Hooks/, History/, Agents/).

During migration on WSL/Linux, I discovered several issues caused by
case-sensitivity:

• TypeScript hooks checking .includes('/.claude/agents/') failed
  (directory is Agents/)
• Glob patterns like .claude/skills/*/ found nothing
• 70+ internal path references broke silently

Upstream works fine on macOS (case-insensitive), but Linux filesystems
are case-sensitive, so skills/ ≠ Skills/.

Questions:

1. Is there a specific rationale for TitleCase? (Readability? Semantic emphasis?)
2. Should PAI documentation note the case-sensitivity implications for
   Linux/WSL users?
3. Are there conventions for internal path references (always use exact case,
   use case-insensitive matching, etc.)?

Happy to contribute docs based on what I learned during the migration.

[vichong]

Update: Clarification on what actually broke

After further investigation, I want to clarify the distinction:

What works fine:

• Skill/agent invocation via Task(subagent_type="engineer") - this uses the name: field in YAML frontmatter, which can remain lowercase regardless of directory name

What broke on Linux:

• Claude Code expects lowercase directories (.claude/agents/, .claude/skills/) but upstream PAI uses TitleCase (Agents/, Skills/)
• TypeScript hooks doing path string matching like .includes('/.claude/agents/') when the actual directory is Agents/
• Glob patterns like .claude/skills/*/ failing to find Skills/ directories
• Any hardcoded path references in markdown files

Solution: Symlinks

I'm using symlinks to get the best of both worlds - TitleCase directories for upstream alignment, lowercase symlinks for Claude Code compatibility:

cd .claude
ln -s Agents agents
ln -s Skills skills
ln -s Commands commands

This way:

• Upstream PAI TitleCase convention is preserved
• Claude Code finds agents/skills via lowercase paths it expects
• Hooks and code can use either case (symlink resolves both)

Suggestion for PAI docs:

• Document that Linux filesystems are case-sensitive (macOS is not by default)
• Recommend symlink approach for Linux/WSL users who want to stay aligned with upstream TitleCase convention
• Note that the name: field in frontmatter is independent of directory name

[vichong]

Closing as duplicate - consolidating with existing issues

After reviewing existing issues, this discussion duplicates the ongoing conversation in:

• Linux case-sensitivity issue: Claude Code expects lowercase directories #239 - "Linux case-sensitivity issue: Claude Code expects lowercase directories" (primary issue)
• Hooks use lowercase 'raw-outputs' but directory is 'Raw-Outputs' (breaks on Linux) #237 - "Hooks use lowercase 'raw-outputs' but directory is 'Raw-Outputs' (breaks on Linux)"
• Critical: Workflow references broken due to case mismatch #229 - "Critical: Workflow references broken due to case mismatch"

See also Discussion #222 for additional context on the TitleCase convention decision.

TL;DR for future Linux/WSL users finding this:

The workaround is symlinks:

cd ~/.claude
ln -s Skills skills
ln -s Commands commands

(Only skills and commands are needed for Claude Code auto-discovery - other directories use explicit paths in settings.json)

Tracking continues in #239.