Skip to content

Commit 5a885e4

Browse files
mythzmythz
committed
Add skills docs for different harness/models
1 parent 27d93f8 commit 5a885e4

3 files changed

Lines changed: 548 additions & 0 deletions

File tree

‎docs/SKILLS_ANTIGRAVITY_OPUS.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Skills
2+
3+
Extend your AI agent with specialized knowledge, workflows, and reusable tools through modular skill packages.
4+
5+
## What Are Skills?
6+
7+
Skills are packages of domain-specific instructions, scripts, and resources that enhance your AI agent's capabilities. They allow you to:
8+
9+
- **Encode expertise** — Capture specialized knowledge, company workflows, or best practices that persist across sessions
10+
- **Save context** — Only load what's needed, keeping your conversation focused
11+
- **Reuse tools** — Bundle executable scripts that work consistently every time
12+
- **Share knowledge** — Package and distribute skills across teams
13+
14+
## UI Overview
15+
16+
### Skill Selector (Top Bar)
17+
18+
Click the **Skills icon** in the top toolbar to access the Skill Selector dropdown:
19+
20+
![Skill Selector](/docs/images/skills-selector.png)
21+
22+
| Control | Description |
23+
|---------|-------------|
24+
| **All Skills** | Include all available skills in conversations (green indicator) |
25+
| **No Skills** | Exclude all skills from conversations |
26+
| **Individual Skills** | Click skill names to toggle them on/off (blue = custom selection) |
27+
| **Group Controls** | Use `all` / `none` buttons to toggle entire skill groups |
28+
29+
The Skills icon color indicates the current state:
30+
- 🟢 **Green** — All skills included
31+
- 🔵 **Blue** — Custom selection active
32+
- ⚪ **No color** — No skills included
33+
34+
> [!NOTE]
35+
> The `skill` tool must be enabled for skills to work. If disabled, you'll see a warning in the Skill Selector.
36+
37+
### Skills Management Page
38+
39+
Access the full management interface by clicking the **Skills icon** in the left sidebar, or navigate to `/skills`.
40+
41+
**Features:**
42+
- **Browse skills** organized by location (global vs project-specific)
43+
- **Search** to quickly find skills by name or description
44+
- **Create new skills** in your global user directory
45+
- **View and edit** skill files and documentation
46+
- **Add files** to existing skills (scripts, references, assets)
47+
- **Delete** skills or individual files
48+
49+
> [!IMPORTANT]
50+
> Only skills in your user directory (`~/.llms/.agents`) are editable. Project and built-in skills are read-only (indicated by a lock icon).
51+
52+
## Skill Locations
53+
54+
Skills are discovered from multiple locations, with later locations taking precedence:
55+
56+
| Location | Scope | Editable |
57+
|----------|-------|----------|
58+
| Built-in | Extension default skills | ❌ |
59+
| `~/.claude/skills` | Global Claude skills | ❌ |
60+
| `.claude/skills` | Project Claude skills | ❌ |
61+
| `~/.llms/.agent/skills` | Global user skills | ✅ |
62+
| `.agent/skills` | Project skills | ❌ |
63+
64+
## Creating a Skill
65+
66+
### From the UI
67+
68+
1. Open the Skills page (`/skills` or left sidebar icon)
69+
2. Click **Create Skill**
70+
3. Enter a name (lowercase letters, numbers, and hyphens only)
71+
4. A new skill folder is created with a template `SKILL.md`
72+
5. Click **Edit** to customize the skill instructions
73+
74+
### Skill Structure
75+
76+
Each skill is a folder containing:
77+
78+
```
79+
my-skill/
80+
├── SKILL.md # Required: Instructions and documentation
81+
├── scripts/ # Optional: Executable code (Python, Bash, etc.)
82+
├── references/ # Optional: Additional documentation
83+
└── assets/ # Optional: Templates, images, fonts
84+
```
85+
86+
### SKILL.md Format
87+
88+
```yaml
89+
---
90+
name: my-skill
91+
description: Brief description of what this skill does and when to use it.
92+
---
93+
94+
# My Skill
95+
96+
Detailed instructions for the AI agent...
97+
```
98+
99+
> [!TIP]
100+
> The `description` is key — it tells the AI when to use this skill. Be specific about triggers and use cases.
101+
102+
## Built-in Skills
103+
104+
| Skill | Description |
105+
|-------|-------------|
106+
| `create-plan` | Creates structured, actionable plans for coding tasks |
107+
| `skill-creator` | Comprehensive guide for creating new skills |
108+
109+
## Best Practices
110+
111+
### Writing Effective Skills
112+
113+
1. **Clear descriptions** — Include what the skill does AND when to use it
114+
2. **Concise instructions** — Keep SKILL.md under 500 lines
115+
3. **Use references** — Move detailed docs to `references/` folder
116+
4. **Bundle scripts** — Executable code in `scripts/` runs without using context
117+
5. **Templates in assets** — Store reusable templates and resources in `assets/`
118+
119+
### Organizing Skills
120+
121+
- **Simple skills**: Single SKILL.md with all instructions
122+
- **Domain skills**: SKILL.md overview + multiple reference files organized by topic
123+
- **Tool skills**: SKILL.md + scripts for specific operations
124+
125+
## Use Cases
126+
127+
### Personal Workflow Automation
128+
Create skills for repetitive tasks like code review checklists, deployment procedures, or documentation templates.
129+
130+
### Team Knowledge Sharing
131+
Package team conventions, coding standards, and best practices as skills that persist across sessions.
132+
133+
### Project-Specific Context
134+
Add `.agent/skills/` to your project with skills containing architecture decisions, API conventions, or test patterns.
135+
136+
### Domain Expertise
137+
Capture specialized knowledge (database optimization, security practices, framework patterns) for consistent application.
138+
139+
## Keyboard Shortcuts
140+
141+
| Shortcut | Action |
142+
|----------|--------|
143+
| Click skill group header | Expand/collapse the group |
144+
| Click skill name | Expand/collapse skill files |
145+
| Click file | View file contents |
146+
147+
## Troubleshooting
148+
149+
### Skills not appearing
150+
- Verify the `skill` tool is enabled in the Tools selector
151+
- Check that `SKILL.md` exists in the skill folder
152+
- Ensure proper YAML frontmatter with `name` and `description`
153+
154+
### Can't edit a skill
155+
- Only skills in `~/.llms/.agent/skills` are editable
156+
- Look for the lock icon on read-only skill groups
157+
158+
### Skill not triggering
159+
- Make the `description` more specific about when to use the skill
160+
- Ensure the skill is enabled in the Skill Selector

‎docs/SKILLS_CLAUDECODE_OPUS.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Skills
2+
3+
Skills are modular packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains—they transform Claude from a general-purpose assistant into a specialized agent equipped with procedural knowledge for particular tasks.
4+
5+
## What Skills Provide
6+
7+
- **Specialized Workflows** - Multi-step procedures for specific domains (e.g., creating plans, building frontends, processing documents)
8+
- **Tool Integrations** - Instructions for working with specific file formats like PDFs, DOCX, XLSX, or PPTX
9+
- **Domain Expertise** - Company-specific knowledge, schemas, business logic, and best practices
10+
- **Bundled Resources** - Scripts, reference materials, and templates for complex or repetitive tasks
11+
12+
## Using Skills
13+
14+
### Skill Selector Panel
15+
16+
Click the **Skills icon** in the top toolbar to open the Skill Selector panel. This panel lets you control which skills are available during your conversations.
17+
18+
**Global Controls:**
19+
20+
| Button | Description |
21+
|--------|-------------|
22+
| **All Skills** | Include all available skills (green indicator) |
23+
| **No Skills** | Exclude all skills (fuchsia indicator) |
24+
| Custom selection | Include only specific skills you choose (blue indicator) |
25+
26+
**Working with Skill Groups:**
27+
28+
Skills are organized into groups based on their source location:
29+
30+
- `~/.llms/.agents` - Your personal skills (editable)
31+
- `~/.claude/skills` - User-level global skills
32+
- `.claude/skills` - Project-level skills
33+
34+
Each group shows a count of active skills (e.g., "3/5") and provides quick actions:
35+
- **all** - Enable all skills in the group
36+
- **none** - Disable all skills in the group
37+
38+
Click individual skill names to toggle them on/off. Hover over a skill to see its description.
39+
40+
### Skills Management Page
41+
42+
Access the full skills management interface by clicking the **Skills icon** in the left sidebar. This page provides comprehensive skill management:
43+
44+
**Left Sidebar:**
45+
- Search skills by name or description
46+
- Browse skills organized by group
47+
- Expand skills to see their file structure
48+
- Lock icon indicates read-only skills
49+
50+
**Center Panel:**
51+
- View skill details (name, description, group, file count, location)
52+
- Browse and edit skill files
53+
- View file contents with syntax highlighting
54+
55+
### Creating Skills
56+
57+
1. Click **Create Skill** in the Skills Management page header
58+
2. Enter a skill name (lowercase letters, numbers, and hyphens only, max 40 characters)
59+
3. The new skill is created in your personal skills folder (`~/.llms/.agents`)
60+
4. A template `SKILL.md` file is generated automatically
61+
62+
### Editing Skills
63+
64+
Only skills in your home directory (`~/.llms/.agents`) can be edited. Read-only skills show a lock icon.
65+
66+
**To edit a file:**
67+
1. Select a skill and click on a file to view it
68+
2. Click **Edit** to enter edit mode
69+
3. Make your changes in the text editor
70+
4. Click **Save** to save changes or **Cancel** to discard
71+
72+
**To add a file:**
73+
1. Expand the skill in the sidebar
74+
2. Click **+ file** in the skill's file tree header
75+
3. Enter the relative file path (e.g., `scripts/helper.py`)
76+
77+
**To delete a file:**
78+
1. Hover over a file in the tree
79+
2. Click the **×** button that appears
80+
3. Confirm deletion in the dialog
81+
82+
Note: The `SKILL.md` file cannot be deleted directly—delete the entire skill instead.
83+
84+
### Deleting Skills
85+
86+
1. Expand the skill in the sidebar
87+
2. Click **delete** in the skill's header
88+
3. Confirm deletion in the dialog
89+
90+
## Skill Structure
91+
92+
Each skill consists of:
93+
94+
```
95+
skill-name/
96+
├── SKILL.md # Required - Main instructions and metadata
97+
├── scripts/ # Optional - Executable code (Python, Bash, etc.)
98+
├── references/ # Optional - Documentation and reference material
99+
└── assets/ # Optional - Templates, images, fonts, boilerplate
100+
```
101+
102+
### SKILL.md Format
103+
104+
The `SKILL.md` file contains:
105+
106+
**Frontmatter (YAML):**
107+
```yaml
108+
---
109+
name: my-skill
110+
description: What this skill does and when to use it
111+
---
112+
```
113+
114+
**Body (Markdown):**
115+
Instructions and guidance for using the skill.
116+
117+
## Common Use Cases
118+
119+
### Document Processing
120+
Skills like `docx`, `pdf`, `xlsx`, and `pptx` provide specialized capabilities for working with office documents—creating, editing, extracting data, and preserving formatting.
121+
122+
### Frontend Development
123+
The `frontend-design` skill helps create distinctive, production-grade web interfaces with high design quality.
124+
125+
### Planning & Architecture
126+
The `create-plan` skill generates concise, actionable plans for coding tasks with clear scope and action items.
127+
128+
### Creating New Skills
129+
The `skill-creator` skill guides you through building effective skills with proper structure and best practices.
130+
131+
### Internal Communications
132+
Skills for writing status reports, leadership updates, FAQs, and other internal documents in company-preferred formats.
133+
134+
### Testing & Validation
135+
The `webapp-testing` skill enables interaction with local web applications using Playwright for frontend verification and debugging.
136+
137+
## How Claude Uses Skills
138+
139+
When skills are enabled:
140+
141+
1. Claude sees the name and description of all available skills
142+
2. When a task matches a skill's description, Claude reads the skill's full instructions
143+
3. Claude follows the skill's guidance, using any bundled scripts, references, or assets as needed
144+
4. Skills can reference additional files that Claude reads only when necessary
145+
146+
This progressive loading ensures skills provide specialized capabilities without overwhelming the conversation context.
147+
148+
## Tips
149+
150+
- **Enable relevant skills** - Only include skills that match your current task to keep conversations focused
151+
- **Check the indicator** - The top toolbar icon shows your current skill status (green=all, blue=custom, fuchsia=none)
152+
- **Use skill groups** - Quickly enable/disable related skills together using group controls
153+
- **Create project skills** - Build skills specific to your project's workflows, schemas, and conventions
154+
- **Start with examples** - When creating new skills, look at existing skills like `create-plan` for structure guidance

0 commit comments

Comments
 (0)