[Improvement] coax claude to use available skills

[strangemonad]

This will probably be true until the next claude training run starts favoring skills more. For rare skills and tasks, I'd imagine the model would default to reading the skills but it might need more direct instruction for more common tasks

This is not a plugin skill loading error. The plugin and skills loading work fine. It's claude not choosing to read in the rest of the skill file.

I wonder if it might make sense to have the plugin also inject a prompt hint similar to the manual workaround described below? Otherwise, a documentation update?

The manual workaround:
Instruct the model to at least read the SKILL.md for skills that might be appropriate.

Test case:

I only tested this with sonnet 4.5

Pick a task that the model would have been trained on and would have very high confidence. "Create a new python project" is what I picked to test this.

Prompt 1:

"Create a new python project"

If I just prompt the model to do that in an empty directory, it completely disregards the skill I wrote and instead defaults to creating a requirement.txt and use pip / venv.

Prompt 2/3:
I tried both a simple and aggressive nudge. Both seemed to work fine.

Create a new python project, using the most appropriate skills

IMPORTANT first check if we have any relevant skills for the task.
Create a new python project

Both of these performed flawslessly. In both cases, sonnet 4.5 read my simple .../;skills/python-package-management/SKILL.md and then ran uv init instead of manually creating requirements.txt, README.md with instructions to use pip, etc.

Skill

---
name: python-package-management
description: Instructions and commands to use when working with python projects.
---

# Purpose

This skill provides guidance for managing dependencies and running python code. Because python has existed for so long and been so widely adopted, there exist many ways to define and manage python projects and depdendencies. The python package management skill defines the modern conventions and tools choices to use.

# Instructions

- IMPORTANT always use uv to manage python projects and dependencies
- IMPORTANT python projects are defined with a `pyproject.toml` file.
- Projects we author will NEVER have a requirements.txt.
- Projects follow the `src` layout convention.

# Example project structure

```
./my-awesome-project/
    src/
        my_awesome_project/
            __init__.py
            ...
    tests/
        ...
    pyproject.toml
```

[malhashemi]

Hi @strangemonad — have you tried making the skill description way more explicit / “salesy” about when it should be used?

In practice, the description is less “what this skill contains” and more the ad copy that convinces the model to pick it. If it reads like neutral documentation, Claude will often ignore it for high-confidence, default tasks (like “create a new python project”) and fall back to its baked-in habits.

I’d try rewriting the description to directly mirror your working nudges, e.g. something along the lines of:

“Use this whenever the task involves creating/managing Python projects/deps. Prefer this over default pip/venv/requirements.txt workflows.”

“If the user asks to start a Python project, ALWAYS call this.”

Basically: treat the description like marketing material, not a README. I’ve seen people go full clickbait (“if you don’t use this you’re doing it wrong” energy), and it genuinely helps routing. Humanlayer even uses spicy language in agent descriptions sometimes 😄

This might not eliminate the need for a prompt hint injection, but it’s a cheap lever to pull first—because routing starts at the description. Also see #38 where we discussed the trigger patterns in more details

[taqtiqa-mark]

@strangemonad, there is a discussion of what a native OpenCode Skill implementation would support out-of-the-box. You might like to weigh in here, anomalyco/opencode#3235