docs/SKILLS.md

Skills

Teach AI your preferences and workflows.

Skills are instruction documents that guide how AI builds your projects. Enable skills to make AI follow your preferred patterns, best practices, and coding styles automatically.

---

What Are Skills?

Skills are markdown documents that teach the AI how you want things done:

• Workflow guides - Step-by-step processes to follow
• Best practices - Coding standards and patterns
• Domain knowledge - Specific expertise (e.g., accessibility)
• Preferences - Your personal coding style

Think of skills as:

• Training manuals for the AI
• Automated best practices
• Consistency enforcers
• Knowledge you don't have to repeat

Skills are NOT:

• Project templates (see Templates)
• Executable code
• Data storage
• Replacement for good prompts

---

How Skills Work

When you enable a skill, OSW Studio makes it available to the AI, but doesn't load the entire content into context automatically. Instead:

1. Metadata is revealed - AI sees skill names, descriptions, and tags
2. Dynamic loading - Skills are loaded into project context only when needed
3. Smart selection - AI chooses to read a skill when it seems relevant to the task
4. User control - You can explicitly ask AI to use a specific skill

Example: Enable the "Accessibility" skill:

• AI sees "Accessibility skill available - WCAG guidelines and best practices"
• When you ask to build a form, AI recognizes accessibility is relevant
• AI reads the full skill content and applies the guidance:
  • Add proper ARIA labels
  • Ensure keyboard navigation
  • Include alt text for images
  • Follow accessibility best practices

This approach keeps the AI's context clean while making expertise available when needed.

Skill Evaluation (Optional)

By default, the AI decides on its own whether to read a skill — but it doesn't always get it right. In practice, skills can be ignored even when they're clearly relevant, because the instruction to check skills is buried in a large system prompt.

Skill Evaluation solves this with a pre-flight check: before the main AI call, a quick non-streaming call evaluates your prompt against enabled skills. If any match, an explicit "read this skill" directive is injected into your message so the AI treats it as a high-priority instruction rather than an easily overlooked system prompt note.

To enable:

1. Go to Skills view
2. Toggle Skill Evaluation on (below the global skills toggle)

What changes:

• Each message triggers an additional API call using your selected model
• Matched skills appear as explicit read directives in the AI's input
• A skill_evaluation event appears in the debug panel showing what was evaluated

Trade-off: This adds an extra API call per message, increasing initial token usage. It's disabled by default — enable it if you find skills aren't being picked up consistently.

---

Built-in Skills

OSW Studio includes skills to get you started:

Workflow

Teaches AI the recommended workflow for building in OSW Studio.

What it does:

• Plan before coding (PLAN.md)
• Build incrementally (main page first)
• Run build to verify compilation
• File structure and modularity guidance

When to use: Always - this is the foundation

Responsive

Dedicated responsive design skill.

What it does:

• Mobile-first CSS with key breakpoints
• Navigation collapse patterns (hamburger menus)
• Fluid typography with clamp()
• Touch targets and common mobile failures

When to use: When building sites that need to work on mobile

Frontend Design (12 sub-skills)

Visual design quality guidance with 12 distinct aesthetic directions: bold-geometric, soft-organic, editorial, minimal, brutalist, retro-futuristic, art-deco, maximalist, playful, industrial, luxury, and terminal.

What it does:

• Typography character and font pairing
• Color systems with CSS custom properties
• Spatial composition and motion intent
• Strong aesthetic commitment — each sub-skill pushes toward a distinct visual identity

When to use: When you want polished, professional-looking output with a specific aesthetic direction. Enable the whole group or individual sub-skills.

Handlebars Advanced

Advanced Handlebars templating techniques.

What it does:

• Use Handlebars helpers
• Create reusable components
• Implement dynamic content
• Follow template best practices

When to use: When building Handlebars-based sites

Accessibility

Web accessibility best practices (WCAG guidelines).

What it does:

• Add semantic HTML
• Include ARIA attributes
• Ensure keyboard navigation
• Provide alt text
• Use proper heading hierarchy

When to use: Always - accessibility should be standard

Server Mode Skills

These skills guide the AI when working with a published deployment's backend:

• Server - Overview of Server Mode's backend features and /.server/ context
• Functions - Edge functions (API endpoints) and server functions (helpers)
• Database - SQLite access from edge functions, schema design, migrations
• Secrets - Managing API keys and sensitive configuration

When to use: When a deployment is selected and you're building or extending backend features.

---

Using Skills

Enable a Skill

1. Click Skills in sidebar
2. Browse available skills
3. Click the toggle to enable a skill
4. Return to your project

The AI can now access this skill when it's relevant to your task. You can also explicitly ask the AI to use a specific skill (e.g., "Use the Accessibility skill to build this form").

Disable a Skill

1. Go to Skills view
2. Find the enabled skill
3. Click the toggle to disable

The AI will no longer have access to that skill's content.

Multiple Skills

Enable multiple skills at once. The AI can access any enabled skill when relevant to the task at hand.

Recommendation: Start with OSW Workflow + Accessibility as your baseline. The AI will intelligently choose which skills to reference based on what you're building.

---

Creating Custom Skills

Teach AI your own preferred workflows and patterns.

When to Create Skills

Create skills for:

• Company coding standards
• Personal workflow preferences
• Specific technologies you use
• Domain expertise (e.g., e-commerce patterns)
• Repeated instructions you give

How to Create a Skill

1. Write your skill

   • Use markdown format
   • Be clear and specific
   • Include examples
   • Keep it focused on one topic

2. Save as skill

   • Go to Skills view and click Create Skill, or
   • Click the + button in the Skills panel header inside a workspace
   • Paste your content
   • Add metadata (name, description, tags)
   • Save — the skill is immediately available to the AI on the next message

3. Use your skill

   • Enable it like built-in skills
   • Test it on a project
   • Refine as needed

Skill Writing Tips

✅ Good skill content:

Example of a well-written skill:

# Mobile-First Responsive Design

Always build mobile layouts first, then desktop.

## Process
1. Start with mobile viewport (375px)
2. Build layout that works on small screens
3. Add media queries for tablet (768px+)
4. Add media queries for desktop (1024px+)

## CSS Structure
- Use min-width media queries
- Avoid max-width
- Test on real devices

## Example CSS
/* Mobile first */
.container {
  padding: 1rem;
}

/* Tablet and up */
@media (min-width: 768px) {
  .container {
    padding: 2rem;
  }
}

❌ Avoid:

• Vague instructions ("make it good")
• Too many topics in one skill
• Contradictory guidance
• Overly long documents (keep under 2 pages)

---

Managing Skills

Browse Skills

1. Click Skills in sidebar
2. View built-in and custom skills
3. Read descriptions
4. Enable/disable as needed

Edit Custom Skills

1. Find your skill in Skills view
2. Click Edit
3. Make changes
4. Save

Built-in skills can't be edited.

Delete Custom Skills

1. Find skill in Skills view
2. Click Delete (trash icon)
3. Confirm deletion

Built-in skills can't be deleted.

---

Skill Groups

Groups let you enable or disable a set of related skills with one toggle.

Built-in Groups

• Frontend Design — All 12 aesthetic sub-skills. Disable to remove design direction guidance entirely.
• Server Mode — Server, Functions, Database, and Secrets skills. Disable when working on browser-only projects.
• Web Standards — Responsive and Accessibility. Keep enabled for production-quality output.

How Groups Work

• Enabling a group activates all its member skills
• Disabling a group falls through to each skill's individual toggle
• A skill can belong to multiple groups — enabling any one of them makes the skill active
• Built-in group membership is fixed, but you can disable built-in groups

Custom Groups

Create your own groups for project-specific workflows:

1. Go to Skills view → Groups tab
2. Click New Group
3. Name it, add an optional description, and select member skills
4. Toggle the group on/off as needed

Edit or delete custom groups any time.

---

Importing & Exporting Skills

Export a Skill

Share your skills with others or back them up:

1. Go to Skills view
2. Find your skill
3. Click Export (download icon)
4. Save the skill file (.md)

Import a Skill

Use skills created by others:

1. Click Skills in sidebar
2. Click Import Skill
3. Select skill file
4. Skill appears in your library

Skills are compatible with Anthropic's SKILL.md convention, so you can use skills from other sources.

---

Skill Tips

💡 Start with built-in skills Learn how skills work before creating your own

💡 One skill per topic Don't try to teach everything in one skill

💡 Be specific Vague guidance leads to unpredictable results

💡 Include examples Show the AI exactly what you want

💡 Test and refine Create a skill, test it, improve it based on results

💡 Don't over-skill Too many skills can confuse the AI. Start with 2-3 essential ones.

---

Skills vs Templates

Skills = Instructions for AI

• Markdown documents
• Teach AI how to work
• Apply to any project
• Reusable across all projects

Templates = Project starting points

• Complete file structures
• HTML, CSS, JavaScript
• One-time use per project

Use skills to improve how AI works. Use templates to start projects faster.

Learn about Templates →

---

Common Use Cases

Company Standards

Create a skill with your company's:

• Code formatting rules
• File naming conventions
• Comment standards
• Framework preferences

Personal Workflow

Teach AI your preferences:

• CSS methodology (BEM, Tailwind, CSS-in-JS)
• JavaScript style (ES6+ features you prefer)
• HTML structure patterns
• Testing requirements

Technology-Specific

Create skills for:

• React best practices
• Vue patterns
• Specific CSS frameworks
• Animation libraries

Domain Expertise

Share knowledge about:

• E-commerce best practices
• Blog structures
• Portfolio patterns
• SaaS landing pages

---

Common Questions

Q: How many skills should I enable? A: Start with 2-3 core skills. Add more as needed. Too many can be overwhelming.

Q: Can skills conflict? A: Yes. If two skills give opposite guidance, AI may get confused. Keep skills complementary.

Q: Do skills slow down AI? A: Minimal impact. Only skill metadata is always present. Full skill content is loaded on-demand, so you only pay for tokens when the skill is actually used. If you enable Skill Evaluation, there's an additional API call per message for the pre-flight check.

Q: Can I use Anthropic's SKILL.md files? A: Yes! OSW Studio is compatible with the SKILL.md convention.

Q: Should every team member have the same skills? A: For consistency, yes. Export/import skills to share with your team.

---

Next Steps:

• Working with AI - Get better results
• Templates - Start projects faster
• Projects - Manage your work

---

Ready to create your first skill? Think about instructions you repeat often, and turn them into a reusable skill!