Skip to content

design-and-plan skill cannot resolve shared _data/ references #350

Description

@williamthorsen

Problem

Skills reference shared _data/ files using incorrect relative paths. From a skill's base directory (e.g., ~/.claude/skills/design-and-plan/), the path _data/foo.md resolves to a nonexistent subdirectory instead of the shared ~/.claude/skills/_data/ directory. When the file can't be found, agents fall back to hardcoded behavior — recommendation rules, naming conventions, and artifact conventions are never applied.

15 of 19 skills that reference _data/ have broken paths. Only 4 (commit, create-ticket, orchestrate, review-criteria) use the correct ../_data/ prefix.

A related issue: ~/.claude/CLAUDE.md duplicates guidance that belongs in ~/.agents/AGENTS.md, and AGENTS.md itself has a broken _data/ reference.

Context

  • The _data/ directory is a shared reference library installed as a sibling to skill directories
  • The agents CLI (commit 424828b) was updated to install _data/ alongside skills, but existing path references were never corrected
  • case-conventions.md in _data/ is unreferenced — its guidance migrated to AGENTS.md and CLAUDE.md, making the file redundant
  • CLAUDE.md contains no Claude-specific guidance; its unique content (writing style examples, prompt formatting) belongs in the platform-agnostic AGENTS.md

Solution

  1. Fix broken _data/ paths in 15 skill SKILL.md files: change _data/../_data/; normalize backtick references to markdown links
  2. Consolidate CLAUDE.md into AGENTS.md: merge unique CLAUDE.md sections into AGENTS.md, reduce CLAUDE.md to just the @~/.agents/AGENTS.md include
  3. Fix AGENTS.md broken reference: replace the unresolvable markdown link on line 42 with a backtick reference
  4. Delete case-conventions.md: unreferenced, redundant with AGENTS.md

Acceptance criteria

  • All _data/ references in skill files use ../_data/ and markdown link syntax
  • ~/.claude/CLAUDE.md contains only the AGENTS.md include directive (plus the "Read AGENTS.md" instruction)
  • ~/.agents/AGENTS.md includes the writing style examples and prompt formatting section from CLAUDE.md
  • AGENTS.md line 42 _data/ reference is resolvable
  • case-conventions.md is deleted from content/skills/_data/
  • Existing tests pass

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions