Skip to content

Composed skills generate broken reference links for deps without usage-rules.md #69

@Munksgaard

Description

@Munksgaard

Code of Conduct

  • I agree to follow this project's Code of Conduct

AI Policy

  • I agree to follow this project's AI Policy, or I agree that AI was not used while creating this issue.

Versions

  • usage_rules v1.2.4
  • Elixir 1.18.4

Operating system

NixOS

Current Behavior

When using build: in the skills config with a regex to match multiple dependencies, the generated SKILL.md includes reference links for all matching deps, even those that don't ship a usage-rules.md file. This results in broken links in the "Additional References" section pointing to files that were never created.

Reproduction

Add usage_rules like the following in your mix.exs:

  defp usage_rules do
    [
      skills: [
        location: ".claude/skills",
        build: [
          "ash-framework": [
            description: """
            Use when working with Ash Framework or any Ash extension (ash_postgres, ash_oban, ash_ai, etc.).
            Consult for actions, queries, relationships, calculations, code generation, and general Ash patterns.
            For Leaf-specific patterns, also consult the ash-migrations and ash-resource-creation skills.
            """,
            usage_rules: [:ash,  ~r/^ash_/]
          ]
        ]
      ]
    ]
  end

Expected Behavior

The generated SKILL.md should only list references to files that were actually created. Deps matched by the regex but lacking a usage-rules.md file should be silently skipped in the "Additional References" section.

The "Searching Documentation" command and "Available Mix Tasks" sections can still include all matched deps (they have hexdocs and mix tasks regardless of usage-rules).

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions