Skip to content

[BUG] pattern_references and progressive_disclosure checks dont follow symlinks #444

@cdrage

Description

@cdrage

Bug Description

The pattern_references and progressive_disclosure assessors fail to detect SKILL.md files when .claude/skills/ contains symlinked directories pointing to the actual skill locations (e.g., .agents/skills/).

The assessors score 0/100 and 60/100 respectively despite valid SKILL.md files being accessible through the symlinks :(

I tested this against https://github.com/podman-desktop/extension-bootc with symlinks.

To Reproduce

  1. Create a repo with skills in .agents/skills/*/SKILL.md.
  2. Symlink them into .claude/skills/:
    mkdir -p .claude/skills
    ln -s ../../.agents/skills/my-skill .claude/skills/my-skill
  3. Verify the symlinks resolve: ls .claude/skills/my-skill/SKILL.md succeeds
  4. Run agentready assess .
  5. pattern_references scores 0/100 — "No pattern references or skills found"
  6. progressive_disclosure loses 30 points it would get from skills detection

Expected Behavior

skills_dir.rglob("SKILL.md") should follow directory symlinks and find SKILL.md files inside symlinked.

Actual Behavior

(claude output below:)

The assessor finds .claude/skills/ exists and is a directory (these checks follow symlinks), but rglob("SKILL.md") returns no results when the subdirectories are symlinks. Replacing symlinks with cp -r copies of the same content immediately scores 60/100 for pattern_references and +30 for progressive_disclosure.

Environment

  • OS: macOS 15.5 (Darwin 25.4.0)
  • Version: agentready 2.38.0
  • Python Version: 3.13

Additional Context

(claude output below):

The affected code is in src/agentready/assessors/patterns.py:

  • Lines 43-51 (PatternReferencesAssessor.assess()) — skills_dir.rglob("SKILL.md")
  • Lines 401-408 (ProgressiveDisclosureAssessor.assess()) — same pattern

Note: Python's pathlib.Path.rglob() changed symlink-following behavior across versions. In Python < 3.13, rglob does NOT follow symlinks by default. In Python 3.13+, follow_symlinks=None (the default) follows symlinks for traversal but not for matching. This means on Python < 3.13, symlinked directories are silently skipped during recursive glob.

Separately, the assessors also only check .claude/skills/ and not .agents/skills/ — both are valid conventions for agent configuration. That's a related but distinct issue.

Possible Solution

(claude output below):

Pass follow_symlinks=True explicitly to rglob:

skill_files = list(skills_dir.rglob("SKILL.md", follow_symlinks=True))

Or resolve the directory first:

skills_dir = (repository.path / ".claude" / "skills").resolve()

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions