---
name: ao-skills-sh
description: "Wrap skills.sh for external skill discovery and use. Search, browse, and fetch skills from the skills.sh ecosystem."
category: extended
invokes: [ao-state]
invoked_by: [User request, ao-skills-advisor]
state_files:
  read: [external-skills.yaml]
  write: [external-skills.yaml]
---

# Skills.sh Integration

## Purpose

Wrap the [skills.sh](https://skills.sh/) platform for easy discovery and use of external AI agent skills within AO workflows.

## When to Use

- User asks to find/search for external skills
- User wants to apply an external skill pattern
- Skills Advisor agent recommends exploring skills.sh
- User says `/skills-sh search ...` or `/skills-sh browse`

## Skills.sh Platform

**URL Pattern**: `https://skills.sh/{org}/{repo}/{skill-name}`

**Examples**:
- `https://skills.sh/vercel-labs/ao-skills/vercel-react-best-practices`
- `https://skills.sh/obra/superpowers/brainstorming`
- `https://skills.sh/softaworks/ao-toolkit/writing-clearly-and-concisely`

## Commands

### Search Skills

```
/skills-sh search <query>
```

Search skills.sh for skills matching the query.

**Examples**:
- `/skills-sh search react` — Find React-related skills
- `/skills-sh search writing` — Find writing/documentation skills
- `/skills-sh search typescript testing` — Find TypeScript testing skills

### Browse by Category

```
/skills-sh browse [category]
```

Browse skills by domain/category.

**Categories** (common):
- `frontend` — React, Vue, CSS, UI/UX
- `backend` — APIs, databases, architecture
- `devops` — CI/CD, containers, infrastructure
- `writing` — Documentation, technical writing
- `productivity` — Brainstorming, planning, workflow

### Fetch Skill

```
/skills-sh fetch <url-or-name>
```

Fetch and display a specific skill's content.

**Examples**:
- `/skills-sh fetch vercel-labs/ao-skills/vercel-react-best-practices`
- `/skills-sh fetch obra/superpowers/brainstorming`
- `/skills-sh fetch https://skills.sh/softaworks/ao-toolkit/writing-clearly-and-concisely`

### Apply Skill

```
/skills-sh apply <skill> [to context]
```

Apply a skill's patterns to current work context.

**Examples**:
- `/skills-sh apply brainstorming` — Apply brainstorming techniques
- `/skills-sh apply react-best-practices to current component` — Apply to current work

### Add to Registry

```
/skills-sh add <url> [--triggers keyword1,keyword2]
```

Add a skill to the local external-skills.yaml registry.

**Examples**:
- `/skills-sh add vercel-labs/ao-skills/vercel-react-best-practices --triggers react,jsx`
- `/skills-sh add my-org/internal/team-patterns --triggers internal,team`

## Procedure

### Search Workflow

1. **Parse query** — Extract search terms
2. **Construct search** — Build skills.sh search URL or use API
3. **Fetch results** — Get matching skills
4. **Present results** — Display with name, description, URL
5. **Offer actions** — Fetch details, add to registry, apply

### Fetch Workflow

1. **Parse skill reference** — URL or org/repo/skill format
2. **Fetch skill content** — GET from skills.sh
3. **Parse skill format** — Extract metadata, instructions, examples
4. **Present skill** — Display formatted content
5. **Offer actions** — Apply, add to registry, save locally

### Apply Workflow

1. **Fetch skill** (if not already loaded)
2. **Analyze current context** — What is user working on?
3. **Extract relevant patterns** — Match skill techniques to context
4. **Present application** — How skill applies to current work
5. **Offer implementation** — Suggest specific actions

## Output Formats

### Search Results

```markdown
## 🔍 Skills.sh Search: "{query}"

Found {N} skills:

1. **[Skill Name](url)** — org/repo
   *{brief description}*
   Tags: `tag1`, `tag2`

2. **[Another Skill](url)** — org/repo
   *{brief description}*
   Tags: `tag3`

---
Actions: [1] Fetch details | [2] Add to registry | [3] Search again
```

### Skill Details

```markdown
## 📚 {Skill Name}

**Source**: [{org}/{repo}/{skill}](url)
**Author**: {author/org}
**Tags**: `tag1`, `tag2`, `tag3`

### Description

{skill description}

### Key Patterns

{extracted key patterns/techniques}

### Usage Examples

{examples from skill}

---
Actions: [A] Apply to current work | [R] Add to registry | [S] Save locally
```

## Integration with Skills Advisor

This skill is invoked by the **AO Skills Advisor** agent when:
- User requests skill discovery
- Context triggers suggest external skill would help
- Skills Advisor recommends exploring specific skills.sh resources

### Handoff Pattern

```
Skills Advisor → skills-sh (fetch/search) → Skills Advisor (recommend) → User
```

## Local Registry Integration

Skills can be added to `.agent/ops/external-skills.yaml` for:
- Faster access (cached locally)
- Custom trigger keywords
- Project-specific curations
- Offline availability

### Add to Registry

When user confirms adding a skill:

```yaml
# Appended to .agent/ops/external-skills.yaml custom_skills section
custom_skills:
  - name: "{Skill Name}"
    url: "https://skills.sh/{org}/{repo}/{skill}"
    domain: "{inferred domain}"
    description: "{skill description}"
    use_cases:
      - "{use case 1}"
    triggers:
      - "{keyword1}"
      - "{keyword2}"
```

## Error Handling

| Error | Response |
|-------|----------|
| Network unreachable | "⚠️ Cannot reach skills.sh. Check connection or try later." |
| Skill not found | "⚠️ Skill not found at {url}. Verify the path." |
| Rate limited | "⚠️ Rate limited. Wait a moment and try again." |
| Parse error | "⚠️ Could not parse skill content. Format may have changed." |

## Caching (Optional)

For frequently used skills:

1. **Memory cache** — Skills fetched this session
2. **Local cache** — Skills saved to `.agent/ops/skills-cache/`
3. **Registry cache** — Skills in external-skills.yaml

Cache invalidation:
- Memory: End of session
- Local: 7 days or manual refresh
- Registry: User-managed

## Anti-Patterns

- ❌ Auto-adding skills to registry without user confirmation
- ❌ Applying skills without explaining relevance
- ❌ Blocking on network issues (offer cached alternatives)
- ❌ Overwhelming user with too many search results
- ❌ Fetching skills in a loop (rate limit risk)

## Examples

### Example 1: Search and Apply

```
User: /skills-sh search brainstorming

Agent: ## 🔍 Skills.sh Search: "brainstorming"

Found 3 skills:

1. **[Brainstorming](https://skills.sh/obra/superpowers/brainstorming)** — obra/superpowers
   *Structured brainstorming and idea generation techniques*
   Tags: `ideation`, `creativity`, `planning`

2. **[Creative Problem Solving](https://skills.sh/example/toolkit/creative-problem)** — example/toolkit
   *Techniques for approaching problems creatively*
   Tags: `problem-solving`, `creativity`

---
Actions: [1] Fetch details | [2] Add to registry | [3] Search again

User: 1

Agent: ## 📚 Brainstorming

**Source**: [obra/superpowers/brainstorming](https://skills.sh/obra/superpowers/brainstorming)
**Author**: obra
**Tags**: `ideation`, `creativity`, `planning`

### Description

A comprehensive brainstorming skill with techniques for divergent thinking...

### Key Patterns

1. **SCAMPER Method**: Substitute, Combine, Adapt, Modify, Put to other uses, Eliminate, Reverse
2. **Six Thinking Hats**: Different perspectives for comprehensive analysis
3. **Mind Mapping**: Visual organization of ideas

---
Actions: [A] Apply to current work | [R] Add to registry | [S] Save locally
```

### Example 2: Direct Fetch

```
User: /skills-sh fetch vercel-labs/ao-skills/vercel-react-best-practices

Agent: ## 📚 Vercel React Best Practices

**Source**: [vercel-labs/ao-skills/vercel-react-best-practices](https://skills.sh/vercel-labs/ao-skills/vercel-react-best-practices)
...
```

## Completion Criteria

- [ ] Query parsed and search executed
- [ ] Results or skill content presented clearly
- [ ] Actions offered for next steps
- [ ] Errors handled gracefully
- [ ] Integration with registry working
