ai-docs/docs/ai/skills.md

# Skills Library

You are here: [AI Docs Home](index.md) > Skills Library

## Contents
- Skills vs Agents vs Instructions
- Skills Governance And Sync
- skills.sh (Optional Skills Installer)
- skills CLI Commands
- How To Connect Skills
- Central Assets Repo
- Next Steps

## Skills vs Agents vs Instructions
- Skills are reusable workflows you load for specific tasks.
- Agents are full modes/personas that control behavior end-to-end.
- Instructions are always-on repo rules that auto-apply by file pattern.

## What Skills Are
Skills are reusable instructions and workflows that guide the assistant through specialized tasks.

## When To Use A Skill
- The task has a repeatable workflow.
- You want consistent structure and outputs.
- The task spans multiple files or steps.

## Skills Directory
Store skills in the team-approved skills directory for your environment. If you do not know the location, ask your team lead or check your internal setup docs.

### Example Question To Ask
Example prompt:
```text
Where is the approved skills directory for our team, and how do I add a new skill?
```

## Skills Governance And Sync
To keep skills consistent across teams, use a central skills registry plus a per-project manifest. Avoid copying skills into every repo unless the skill is tightly coupled to the project.

### Recommended Pattern
- Central skills registry repo (single source of truth)
- Project-level manifest that pins required skills and versions
- Sync script that pulls the approved set to each developer's laptop
- Agents.md points to the manifest and sync command

### Proposed Curated Repo Structure
Keep the approved list in a single repo and organize by platform:

```text
repo-root/
	ios-skills.yaml
	android-skills.yaml
	shared-skills.yaml
	agents/
	instructions/
	README.md
```

### Project Manifest Example
Use a small manifest to declare the approved skills and versions for the project:

```yaml
version: 1
registry: git@<host>:org/mobile-ai-skills.git
skills:
	- name: swiftui-expert-skill
		version: 1.2.0
	- name: onboarding-cro
		version: 1.0.0
```

### Sync Workflow
1. Run the sync script.
2. The script pulls the registry and copies required skills to your local skills directory.
3. Restart your editor if required.

### Example Sync Command
```bash
./scripts/sync-skills.sh
```

## skills.sh (Optional Skills Installer)
skills.sh provides a public skills catalog and a CLI to install skills by name. Use this only if your team allows it and you understand the source of the skills you install.

If you have a curated repo, treat skills.sh as a discovery tool only. The source of truth should remain your curated lists.

### Where To Find Skills
- Homepage: https://skills.sh/
- Docs: https://skills.sh/docs
- CLI reference: https://skills.sh/docs/cli

### How It Works (High-Level)
1. You run the `skills` CLI via `npx`.
2. The CLI downloads the skill and configures it for your agent environment.
3. The skill becomes available to your AI agent.

### Install The CLI (No Global Install Required)
The CLI runs via `npx`, so you do not need a global install.

### Example Install Command
```bash
npx skills add vercel-labs/agent-skills
```

### Example Install From A Repo URL
```bash
npx skills add https://github.com/avdlee/swiftui-agent-skill --skill swiftui-expert-skill
```

### Notes
- The leaderboard uses anonymous telemetry from the CLI. You can opt out by setting `DISABLE_TELEMETRY=1`.
- Review skills before installing. The ecosystem is audited, but quality varies.

## skills CLI Commands
Common commands shown in the CLI help output:

```text
npx skills add <package>     Install a skill
npx skills list              List installed skills
npx skills find [query]      Search for skills
npx skills check             Check for updates
npx skills update            Update all skills
npx skills remove            Remove installed skills
npx skills init [name]       Create a new skill
```

![Skills Find](images/skills-find.png)

## How to Download Existing Skills
1. Locate the skill in the team or org repository.
2. Add the skill to your local skills directory following team guidance.
3. Restart the editor or chat if required so the skill is recognized.

## How to Download Agents
Agents are distributed in the curated repo under an agents folder. A simple approach is to clone the repo and copy the agents into your user-level agents directory.

Example:
```bash
git clone git@<host>:org/ai-assets.git
mkdir -p ~/.agents/agents
cp -R ai-assets/agents/* ~/.agents/agents/
```

If your team provides a sync script, use that instead of manual copy.

## How to Enable or Configure Skills
- Follow the instructions provided in each skill's README or SKILL file.
- Some skills require additional setup, such as environment variables or tools.

## How To Connect Skills
1. State the primary skill you want to use.
2. Provide the inputs that skill expects.
3. If needed, add a secondary skill and explain the handoff.

### Example Skill Request
Example prompt:
```text
Use swiftui-expert-skill to review this view for best practices. Then use webapp-testing to validate the web flow.
```

## Central Assets Repo (Recommended)
Do not list every skill in this guide. Instead, point readers to a single repo that contains the approved agents, skills, and instructions they can download.

### What To Include In The Assets Repo
- Agents (agent prompt files)
- Skills (SKILL files and any required setup)
- Instructions (repo-level and editor-level guidance)
- A short README with install and update steps
- Curated skill lists (for example, ios-skills.yaml, android-skills.yaml)

### Link To The Assets Repo
- Repo: (link)

## Next Steps
- For day-to-day workflows, read [Cross-Platform AI Usage](cross-platform.md).
- For setup issues, follow [Troubleshooting and FAQ](troubleshooting.md).