How Skills Work

Technical deep dive into skill execution, MCP integration, and token optimization

Skills = Step-by-Step Workflows for AI

Skills are Markdown documents that give your AI assistant detailed, reproducible workflows for common development tasks.

Key insight: Skills solve the “AI memory problem”

Without skills, you re-explain patterns every conversation. With skills, patterns are encoded once and reused forever.

---

Skill Anatomy

Every skill follows a consistent structure:

# Skill Name

Brief description of what this skill accomplishes.

## Prerequisites
- Required tools (Laravel 11.x, Node.js 20+)
- Required knowledge (REST APIs, database design)

## Steps

1. **First Step**
   ```bash
   command to run

Explanation of what this does

2. Second Step Code example with explanation

3. Third Step More details…

Testing

How to verify the implementation works

Next Steps

Suggested follow-up tasks

---

## How Skills Execute

<Steps>
  <Step title="You Invoke a Skill">

You: “Use the Create Laravel API Endpoint skill for /api/posts”

Your AI assistant sends request to ULPI Skills MCP server
</Step>

<Step title="MCP Server Fetches Skill">
**MCP server:**
1. Authenticates with ULPI API
2. Fetches skill content from ULPI
3. Returns skill to AI assistant

**Response time:** 50-150ms (cached after first fetch)
</Step>

<Step title="AI Reads Entire Skill">
AI receives complete skill workflow:
- Prerequisites
- All steps
- Code examples
- Testing instructions

**Token usage:** 500-3,000 tokens depending on skill complexity
</Step>

<Step title="AI Executes Each Step">
AI follows steps sequentially:

✅ Step 1: Creating FormRequest validation Generated: StorePostRequest.php

✅ Step 2: Building API Resource transformation Generated: PostResource.php

✅ Step 3: Implementing Service layer Generated: PostService.php

[… continues through all steps …]

**AI remembers:** All previous steps while executing current step
</Step>

<Step title="Skill Completes">
AI reports completion:

Complete! Generated 6 files, all tests passing.

**Usage recorded:** 1 skill run counted against your quota
</Step>
</Steps>

---

## Tech Stack Filtering

Skills are automatically filtered based on your repository's detected technologies. ULPI scans package managers (`package.json`, `composer.json`, `requirements.txt`, `pom.xml`, `Gemfile`) and configuration files (`.php`, `.ts`, `.tsx`, `.jsx`, `Dockerfile`) to detect your stack.

**How matching works:** Each skill has filters (e.g., `["php", "laravel"]`). Skills with empty filters are universal. Your Laravel repo sees Laravel-specific skills + universal skills, while a React repo sees React skills + universal skills.

**Manual override:** If detection is incorrect, go to Dashboard → Your Project → Tech Stack → Edit Tech Stack to add missing technologies manually. Skills re-filter immediately. 288+ technologies supported.

---

## Token Usage & Optimization



### Token Breakdown

**How tokens are consumed:**

**1. Skill Fetch (one-time per session):**

Skill: “Create Laravel API Endpoint” Size: 2,400 tokens

Cached for: Duration of conversation Subsequent uses: 0 tokens (cached)

**2. AI Execution:**

AI reads skill: 2,400 tokens (input) AI generates code: 1,800 tokens (output) Total: 4,200 tokens per skill run

**3. Multi-step conversations:**

You: “Use Laravel API Endpoint skill for /api/posts” → 4,200 tokens

You: “Now add validation for email field” → 500 tokens (context already loaded)

You: “Add rate limiting to this endpoint” → 600 tokens

Total for feature: ~5,300 tokens

<Info>
**Skill token usage is included in your plan's token quota**

Starter: 50,000 tokens/month
Pro: 300,000 tokens/month
Enterprise: 1,000,000 tokens/month
</Info>



### Optimization Tips

**Minimize token usage:**

**1. Use skills for complete workflows**

✅ Good: “Use Laravel API Endpoint skill for /api/posts” → One skill run, all steps included

❌ Bad: “Create a controller for posts” “Add validation” “Add tests” → 3 separate prompts, more tokens

**2. Batch similar tasks**

✅ Good: “Use Laravel API Endpoint skill for /api/posts, /api/comments, /api/tags” → Skill loaded once, used 3 times

❌ Bad: Three separate conversations → Skill loaded 3 times

**3. Leverage caching**

Skills are cached per conversation

Same conversation:

• First use: 2,400 tokens
• Second use: 0 tokens (cached)
• Third use: 0 tokens (cached)

New conversation:

• First use: 2,400 tokens (cache expired)

**4. Use custom skills for repetitive patterns**

If you use same workflow 10+ times/month: → Create custom skill → Optimized token usage → Consistent results

### Cost Examples

**Real-world token usage:**

**Scenario 1: API Development**

Task: Build /api/posts endpoint with tests and docs

Without skills:

• Prompt for controller: 800 tokens
• Prompt for validation: 600 tokens
• Prompt for tests: 1,200 tokens
• Prompt for docs: 900 tokens
• Back-and-forth fixes: 2,000 tokens Total: 5,500 tokens

With skills:

• “Use Laravel API Endpoint skill”: 4,200 tokens
• Zero back-and-forth (done right first time) Total: 4,200 tokens

Savings: 1,300 tokens (24%)

**Scenario 2: Monthly usage**

100 skill runs/month (average team)

Token usage:

• 100 runs × 4,200 tokens = 420,000 tokens

Plan needed: Pro ($69/month)

• Includes: 300,000 tokens
• Overage: 120,000 tokens × $0.02/1k =$2.40

Total cost: $69 +$2.40 = $71.40/month

<Check>
**ROI Calculation:**

Time saved: 2 hours/feature × 100 features = 200 hours
Cost: $71.40/month
Value: 200 hours × $100/hour = $20,000

**ROI: 28,000%**
</Check>



---

## MCP Integration

Skills work through the **Model Context Protocol** - a standard way for AI assistants to access external tools.

### What is MCP?

**Model Context Protocol (MCP)** is an open standard that allows AI assistants to access external tools, fetch dynamic data, execute workflows, and connect to APIs.

Think of it like USB: USB is a standard for connecting devices, while MCP is a standard for connecting AI to tools.

**Benefits:** Works with 29+ AI assistants, no vendor lock-in, open source protocol, and growing ecosystem.

### ULPI Skills MCP Server

The ULPI Skills MCP Server runs locally on your machine (Node.js) and authenticates with ULPI API using your API key. It fetches skills filtered for your repository, exposes skills as tools to your AI assistant, and caches skill content for performance.

**Architecture Flow:**
Your AI Assistant (Claude Desktop, Cursor, etc.) → ULPI Skills MCP Server (local, npx @ulpi/mcp-client skills) → ULPI API (api.ulpi.io) → Your Repository Tech Stack + Skills Database

**Security:** MCP server runs locally (not in cloud), API key stored in local config only, no code sent to ULPI servers, only skill metadata fetched.

### How AI Uses Skills

When you invoke a skill, the AI assistant calls the MCP server, which fetches the skill from ULPI API. ULPI returns the skill content (including steps, code examples, and metadata), the MCP server returns the full skill workflow to the AI, and the AI executes each step and generates code.

**Total time:** 100-300ms for skill fetch.

### Caching & Performance

ULPI uses three levels of caching for optimal performance:

**MCP Server Cache (session-based):** First skill use takes 100ms (fetched from ULPI), subsequent uses return from cache in 0ms. Cache duration is for the current conversation only.

**ULPI API Cache (CDN):** Popular skills are cached at edge locations for 5 minutes, with automatic invalidation on skill updates.

**AI Assistant Context:** Skills are loaded once per conversation, subsequent uses are already in the AI's context with 0 token cost.

**Performance benchmarks:** First skill fetch: 100-150ms, cached skill: 0-5ms, skill execution depends on AI model (1-30 seconds). Total time to complete workflow: simple skill (3 steps) takes 5-10 seconds, complex skill (10 steps) takes 20-60 seconds.


---

## Public vs. Custom Skills



### Public Skills

**Maintained by ULPI:**

- ✅ **10 production-ready skills** included
- ✅ Regular updates with best practices
- ✅ Tested across 1,000+ projects
- ✅ Framework version updates
- ❌ **Cannot be edited** (ULPI maintains)

**Update process:**

ULPI updates skill:

1. New Laravel version released
2. ULPI updates “Create Laravel API Endpoint” skill
3. Your projects get updated skill automatically
4. No action required from you

**Benefits:**
- Always current with framework changes
- Tested patterns
- Industry best practices
- Zero maintenance



### Custom Skills

**Created by your team:**

- ✅ **Unlimited custom skills** (all plans)
- ✅ Encode your company patterns
- ✅ Full control over content
- ✅ Share across team
- ✅ Version control

**Active skill limits:**
- Starter: 5 active skills
- Pro: 25 active skills
- Enterprise: Unlimited active skills

**What "active" means:**

You create 50 custom skills But only 25 can be “active” (Pro plan)

Active skills: Available to AI assistants Inactive skills: Stored but not available

Swap active/inactive anytime (instant)

**Use cases:**
- Your deployment process
- Company code standards
- Internal tool usage
- Security procedures
- Testing standards



### Versioning

**Skills use semantic versioning:**

Version format: MAJOR.MINOR.PATCH

Example:

• 1.0.0: Initial release
• 1.1.0: Add new step (minor)
• 1.0.1: Fix typo (patch)
• 2.0.0: Breaking change (major)

**Version history:**
- Dashboard → Skills → Select skill → **Version History**
- See all changes
- Rollback to previous version
- Compare versions

**Auto-updates (public skills):**

Public skill updated: 1.0.0 → 1.1.0 Your projects: Automatically use 1.1.0

Breaking change: 1.1.0 → 2.0.0 Your projects: Opt-in to upgrade Dashboard shows: “New version available”

---

## Skill Composition Patterns



### Sequential Skills (Workflow Chain)

**Use multiple skills in sequence:**

1. “Use Laravel API Endpoint skill for /api/posts” → Creates endpoint with tests

2. “Use API Documentation with OpenAPI skill for /api/posts” → Documents the endpoint

3. “Use Git Commit Best Practices skill” → Creates proper commit message

4. “Use Deploy to Staging skill” → Deploys to staging (custom skill)

**Result:** Complete feature workflow automated


  
### Nested Skills (Sub-workflows)

**Custom skill that uses other skills:**

```markdown
# Complete Feature Workflow (Custom Skill)

## Steps

1. **Create API Endpoint**
   Use the "Create Laravel API Endpoint" skill

2. **Add Comprehensive Tests**
   Use the "Write PHPUnit Tests" skill

3. **Document API**
   Use the "API Documentation with OpenAPI" skill

4. **Deploy to Staging**
   Run deployment script...

Benefit: One command executes entire workflow

Conditional Skills (Context-Aware)

Skills that adapt to context:

# Deploy Application (Custom Skill)

## Steps

1. **Detect Environment**
   Check if deploying to staging or production

2. **Run Tests**
   If production: Run full test suite
   If staging: Run smoke tests only

3. **Build Assets**
   If Laravel: php artisan build
   If React: npm run build

4. **Deploy**
   Push to appropriate environment

AI adapts: Based on project context

---

Best Practices

Keep Skills Focused

Good: One skill = one clear task

• “Create Laravel API Endpoint”
• “Write PHPUnit Tests”

Bad: One skill = many unrelated tasks

• “Build Entire Application”

Include Code Examples

Every step should have code examples

Shows AI exactly what to generate

Reduces ambiguity and errors

Test Your Skills

Before marking skill as active:

1. Test with real projects
2. Verify all steps work
3. Check edge cases
4. Get team feedback

Version Control Custom Skills

Store custom skill markdown in git:

team-skills/
  deploy-staging.md
  pre-review-checklist.md
  setup-local-env.md

Benefits:

• Code review for skills
• Change tracking
• Team collaboration

---

What’s Next?

1. Learn Tech Stack Matching

   Understand how skills are filtered for your projects

2. Create Custom Skills

   Encode your team’s patterns into reusable workflows

3. Configure MCP

   Set up Skills in your IDE for seamless integration

---

Need Help?

Getting Started

Quick setup guide

Support

Email us anytime

Community

Join our Discord