Skills Management

AI assistants are powerful, but they work best when they have context about your specific needs. Capuzzella's Skills Management system lets you extend your AI with specialized knowledge and workflows, making it an expert in your domain, your design system, and your content patterns.

What Are Skills?

Skills are specialized knowledge modules that extend your AI assistant's capabilities. Think of them as training manuals that teach the AI how to handle specific tasks, follow workflows, or adhere to your design and content standards.

Each skill is a Markdown file with YAML frontmatter containing:

• Name — A human-readable title
• Description — What the skill does and when to use it
• Tier — Either "essential" (always active) or "available" (loaded on demand)
• Content — Detailed instructions, templates, guidelines, or examples

---
name: Blog Templates
description: Article layouts, author sections, and blog-specific components
tier: available
---

## Blog Article Structure

### Standard Article Layout

<article class="container py-5">
  <header class="mb-4">
    <h1 class="display-4">Article Title</h1>
    <div class="text-body-secondary mb-3">
      <span>By Author Name</span> 
      &middot; 
      <time datetime="2024-01-15">January 15, 2024</time>
    </div>
  </header>
  ...
</article>

Understanding Skill Tiers

Skills come in two tiers that determine how they're loaded:

Essential Skills

Always active and loaded on every AI request. Perfect for design guidelines, page structure requirements, or universal standards that should always be followed. Use these sparingly to avoid bloating every AI request with unnecessary context.

Example: @design-guidelines, @page-templates

Available Skills

Loaded on-demand when needed. The AI can call a load_skill tool to retrieve detailed instructions for specific tasks. This keeps the context window clean while making deep expertise available when required.

Example: @blog-templates, @seo-guidelines, @contact-forms

Built-in Skills

Every Capuzzella project ships with a set of default skills that guide the AI in creating consistent, high-quality content:

Design Guidelines (Essential)

Teaches the AI to use your site's CSS framework consistently. By default, this covers Bootstrap 5.3 utility classes, components, grid system, and spacing utilities. The AI learns to match existing styling patterns and avoid mixing in other frameworks.

Page Templates (Essential)

Ensures every new page starts with the correct HTML structure. The AI learns to always include the DOCTYPE declaration, required CSS and JS assets, and proper meta tags. This skill prevents broken pages from missing essential elements.

Blog Templates (Available)

Provides ready-to-use templates for blog articles, including article structure, author bio sections, related articles grids, and navigation between posts. When you ask the AI to create a blog post, it references these patterns for professional results.

Contact Forms (Available)

Guides the AI in creating working contact forms using the data-contact attribute and form.js integration. Includes proper field naming, validation setup, and the required script inclusion pattern.

SEO Guidelines (Available)

Teaches best practices for search engine optimization: meta tag structure, title formatting, heading hierarchy, image alt text, and structured data implementation. Use this skill when creating pages that need to rank well in search results.

Managing Skills via the UI

Viewing Skills

Navigate to Settings → Skills in your Capuzzella dashboard to see all configured skills. Each skill card shows:

• The skill name and tier badge (essential or available)
• The skill ID, referenced as @skill-id
• A brief description
• Expandable content with full documentation

Tip: Use a skill in the Editor Panel by typing @skill-name (e.g., @blog-templates) in your message.

Creating a New Skill (Admin Only)

1. Click the "+ Add Skill" button on the Skills page
2. Enter a unique skill ID (lowercase, hyphens allowed, e.g., product-pages)
3. Paste your skill content in Markdown format with YAML frontmatter
4. Click Create Skill

Editing Skills (Admin Only)

Click the dropdown menu on any skill card and select Edit to modify the skill content. You can update the name, description, tier, or the full documentation.

Deleting Skills (Admin Only)

From the skill detail page, admins can delete skills using the dropdown menu. This action cannot be undone.

Managing Skills via CLI

The Capuzzella CLI provides powerful commands for skill management, perfect for automation and version-controlled workflows.

List All Skills

capuzzella skills list

View a Specific Skill

capuzzella skills get blog-templates

Add or Update a Skill

# Create or update from a file
capuzzella skills add my-skill --file ./my-skill.md

Delete a Skill

capuzzella skills delete my-skill

Note: CLI skill management requires an admin API key. Set your key with export CAPUZZELLA_API_KEY=cap_...

Example: Creating a Custom Skill

Let's say your website has a specific style for team member profiles. Instead of explaining this to the AI every time, you can create a skill:

---
name: Team Profiles
description: Team member profile cards with photo, bio, and social links
tier: available
---

# Team Profiles

Use this pattern when adding team member sections to your website.

## Profile Card Structure

Each team member should have:
- Circular profile photo (200x200px recommended)
- Full name as heading
- Job title with subtle styling
- Brief bio (2-3 sentences)
- Social links (LinkedIn, Twitter)

## HTML Template

<div class="col-md-4">
  <div class="card h-100 text-center">
    <div class="card-body">
      <img src="/images/team/member.jpg" 
           alt="Jane Doe" 
           class="rounded-circle mb-3" 
           width="120" height="120">
      <h3 class="h5 card-title">Jane Doe</h3>
      <p class="text-body-secondary small mb-2">Product Manager</p>
      <p class="card-text">Jane leads our product team...</p>
      <div class="d-flex justify-content-center gap-2">
        <a href="#" class="btn btn-outline-primary btn-sm">LinkedIn</a>
        <a href="#" class="btn btn-outline-secondary btn-sm">Twitter</a>
      </div>
    </div>
  </div>
</div>

Using This Skill

When a user says "Add a team section to our about page," the AI can load this skill and:

1. Follow the profile card structure
2. Use the correct image sizing and styling
3. Apply consistent spacing and alignment
4. Include proper social link buttons

Best Practices

• Be specific — Include exact code examples, class names, and measurements
• Keep it focused — Each skill should cover one domain or workflow
• Use markdown formatting — Tables, code blocks, and headers improve readability
• Version control — Store skill files in git for tracking changes
• Test before deploying — Validate skills work as expected with the AI
• Choose the right tier — Use "essential" sparingly; most skills should be "available"

Next Steps

Ready to create your first skill?

1. Identify a repetitive task or pattern in your projects
2. Create a Markdown file with clear instructions and examples
3. Upload it via the UI or CLI
4. Test it by asking the AI to perform the task
5. Refine based on results

Quick Reference

Command/Action	Description
@skill-id	Use a skill in chat
skills list	List all skills
skills get <id>	View skill content
skills add <id> --file <path>	Create or update a skill
skills delete <id>	Remove a skill