Raw view: Suggesting Skills

No invisible, zero-width, or bidi-control characters detected.

---
name: suggesting-skills
description: >-
  When the user struggles with a task that a known skill could handle, suggest
  installing or using a skill from the project's `.agents/skills/` directory.
user-invocable: false
---

# Suggesting Skills

Watch for moments where the user is working on something that an existing skill would make easier. Suggest it when the timing is natural.

## Triggers

Suggest a skill when:
- The user asks how to do something a project skill covers (e.g. "how do I write tests?" → check for `writing-tests`)
- The user is struggling with a task and a skill in `.agents/skills/` has a proven workflow for it
- You notice the project is missing something a skill could set up (e.g. no tests, no CI)
- The user is manually doing something a skill automates

## How to Suggest

Keep it brief and contextual:

```
There's a skill for that — `writing-tests` in `.agents/skills/` handles
detecting the test framework and writing coverage. Want me to use it?
```

Or when you notice a gap:

```
This project doesn't have tests set up. The `writing-tests` skill can
detect or scaffold a test runner. Want me to use it?
```

## Finding Available Skills

Before suggesting, list skills that actually exist:

1. **Project skills** — read `.agents/skills/*/SKILL.md` in the current repo
2. **Harness built-ins** — whatever the current harness lists (Cursor, Claude Code, and Codex each ship their own)

Do not reference skills that are not in `.agents/skills/` or the harness's own list.

## Common Mappings

| User is doing... | Check for... |
|-----------------|--------------|
| Writing tests | `writing-tests` |
| Writing commit messages | `writing-commit-messages` |
| Visual UI verification | `visual-qa-testing` |
| Responsive layout checks | `responsive-testing` |
| Dark mode verification | `dark-mode-testing` |
| UI design direction | `frontend-design` |
| Codebase exploration | `parallel-exploring` |
| Improving LLM prompts | `prompt-engineering` |
| Persisting project knowledge | `saving-workspace-context` |
| Verifying a change before reporting done | `visual-qa-testing` plus the `verification` rule |

## Rules

- Don't spam skill suggestions — one per conversation unless asked
- Only suggest when the timing is natural (user is about to do the thing, not mid-task)
- If the user declines, don't suggest the same skill again
- To add a new skill to a project: copy the skill folder to `.agents/skills/<name>/SKILL.md` or update the skills submodule