---
name: ao-skills-advisor
description: "Recommends external skills from skills.sh based on current work context. Detects when work could benefit from external expertise."
category: utility
invokes: [ao-skills-sh]
invoked_by: []
state_files:
  read: []
  write: []
---

# External Skills Advisor

Recommends external skills from skills.sh based on current work context.

## Purpose

- Detect when current work could benefit from external expertise
- Recommend relevant skills.sh resources contextually
- Provide guidance on how to apply external skill patterns
- Invoke `ao-skills-sh` skill for discovery and fetching

## Skills Discovery

For searching and fetching skills from skills.sh, invoke the **`ao-skills-sh`** skill:
- `/skills-sh search <query>` — Search for skills
- `/skills-sh fetch <url>` — Fetch skill details
- `/skills-sh add <url>` — Add to local registry

## External Skills Registry

The skill reads skills from **`.agent/ops/external-skills.yaml`** (per-project configuration).

If the file doesn't exist, offer to create it from the template:
```
.ao/templates/external-skills.yaml → .agent/ops/external-skills.yaml
```

### Registry Structure

```yaml
skills:
  - name: "Skill Name"
    url: "https://skills.sh/org/repo/skill"
    domain: "Domain"
    description: "What it does"
    use_cases: ["use case 1", "use case 2"]
    triggers: ["keyword1", "keyword2"]
```

## Detection Heuristics

Suggest skills when:

1. **Trigger keyword match** — User's request or current file contains trigger keywords
2. **Domain alignment** — Work involves a domain covered by a registered skill
3. **Explicit request** — User asks for help in a specific area

### Trigger Matching

```
IF user_request contains trigger_keyword:
    AND skill.domain is relevant to current_work:
        SUGGEST skill with confidence based on match_count
```

### Confidence Scoring

| Match Type | Confidence |
|------------|------------|
| Multiple triggers + domain match | HIGH |
| Single trigger + domain match | NORMAL |
| Domain match only | LOW |
| User explicit request | HIGH |

## Behavior

### Proactive Mode (default)

When `settings.proactive_suggestions: true`:
- Monitor work context for trigger matches
- Suggest skills when confidence > threshold
- Limit to `max_suggestions` per context
- Don't repeat suggestions in same session

### On-Demand Mode

When user asks for skill recommendations:
1. Analyze current work context
2. Search registry for relevant skills
3. Present ranked suggestions with rationale
4. Explain how to apply each skill

## Output Format

### Skill Suggestion

```markdown
## 💡 External Skill Suggestion

**[Skill Name](url)** — Domain

*Why this might help:* Brief explanation based on detected context.

*Use cases:*
- Relevant use case 1
- Relevant use case 2

*To use:* Reference this skill in your prompt or ask for patterns from it.
```

### Multiple Suggestions

```markdown
## 💡 Relevant External Skills

Based on your current work with [detected context], these skills may help:

1. **[Skill Name](url)** — Brief description
   Triggers matched: `keyword1`, `keyword2`

2. **[Another Skill](url)** — Brief description
   Triggers matched: `keyword3`

Would you like me to apply patterns from any of these?
```

## User Management

### Adding Custom Skills

Users can add skills by editing `.agent/ops/external-skills.yaml`:

```yaml
custom_skills:
  - name: "My Team Patterns"
    url: "https://skills.sh/my-org/patterns"
    domain: "Internal"
    description: "Team-specific patterns"
    use_cases: ["team workflow"]
    triggers: ["our-app", "internal"]
```

### Initializing Registry

If `.agent/ops/external-skills.yaml` doesn't exist:

```
I notice you don't have an external skills registry yet.

Would you like me to create one from the default template?
This will add curated skills for:
- React development
- Technical writing
- Brainstorming
- Tailwind CSS
- UI/UX design

You can customize it later by adding your own skills.
```

## Integration Points

This skill integrates with:

| AO Skill | Integration |
|----------------|-------------|
| `ao-interview` | Suggest brainstorming skill for alternatives |
| `ao-idea` | Suggest brainstorming for enrichment |
| `ao-docs` | Suggest writing-clearly for documentation |
| `ao-planning` | Suggest domain skills for technical planning |
| `ao-implementation` | Suggest framework-specific skills |

## Commands

- `/skills` — Show all registered external skills
- `/skills search <keyword>` — Search skills by keyword
- `/skills suggest` — Get suggestions for current context
- `/skills add` — Interactive skill addition
- `/skills init` — Initialize registry from template

## Example Session

```
User: I'm building a React component for user profiles

Agent: 💡 External Skill Suggestion

**[Vercel React Best Practices](https://skills.sh/vercel-labs/ao-skills/vercel-react-best-practices)** — React

*Why this might help:* You're working on React component development. This skill provides production-ready patterns from Vercel.

*Use cases:*
- React component development
- React hooks patterns

Would you like me to apply patterns from this skill to your component?
```

## Constraints

- **Never require** external skills — they are suggestions only
- **Never block** work waiting for skill application
- **Respect** user preferences in settings
- **Don't spam** — limit suggestions per context
- **Stay relevant** — only suggest when genuinely helpful
