> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Skills
> Create team-specific AI coding workflows matched to your development practices
**Your team's knowledge gets lost:**
* ❌ New developers ask: "How do we deploy to staging?"
* ❌ Different team members follow different patterns
* ❌ 3 hours lost onboarding each new developer
* ❌ Tribal knowledge disappears when people leave
* ❌ AI generates code that doesn't match your coding standards
* ❌ Code reviews waste time fixing style inconsistencies
* ❌ Critical procedures documented in scattered wikis and Slack messages
**Your workflows become self-executing documentation:**
* ✅ AI knows your deployment process and executes it correctly
* ✅ 100% consistency across team members and AI agents
* ✅ Zero time spent onboarding on standard procedures
* ✅ Knowledge documented in executable, always-current format
* ✅ AI generates code matching your exact conventions
* ✅ Code reviews focus on logic, not style or process
* ✅ All procedures accessible instantly via MCP
**Customer Success Story:**
"We created a custom 'Deploy to Staging' skill that codified our entire deployment process. The first time a new developer used it, they got it right on try one—no questions, no mistakes. We've saved 78% of the time we used to spend on deployment-related troubleshooting." — **Lead DevOps Engineer, SaaS Platform with 15M Users**
***
## Why Create Custom Skills?
While ULPI provides **10 production-ready public skills**, the real power comes from **custom skills**—workflows you create specifically for your team's patterns, tools, and conventions.
Every team member and AI agent follows the exact same patterns. No more "but I thought we did it this way" confusion.
Your documentation isn't just text—it's working code that AI can execute. Always up-to-date because it's used every day.
New developers learn by doing. Custom skills guide them through your exact processes from day one.
When experienced developers leave, their expertise stays. Capture it once in a skill, use it forever.
### Real-World Impact
Custom skills deliver measurable ROI:
**Time Savings:**
* **78% reduction** in deployment troubleshooting (from 3 hours/week to 40 minutes)
* **2 hours saved per feature** by eliminating code review rework
* **3x faster onboarding** for new team members (from 3 days to 1 day for standard procedures)
**Quality Improvements:**
* **92% fewer code style inconsistencies** in pull requests
* **Zero missed steps** in deployment procedures (down from 12 incidents/month)
* **100% team alignment** on coding conventions
**All Skills plans include unlimited custom skill creation**. Plan limits only affect how many skills can be "active" (ready to use) at once:
* **Starter**: 5 active skills
* **Pro**: 25 active skills
* **Enterprise**: Unlimited active skills
***
## Common Custom Skills
Teams create custom skills for workflows unique to their organization:
**Example Skills:**
* Deploy to Staging Environment
* Deploy to Production with Approval
* Rollback Production Deployment
* Deploy Database Migration
* Create Release Tag and Changelog
**Why Custom?**
Every company has unique deployment processes:
* Specific approval workflows
* Custom CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
* Environment-specific configuration
* Company-specific health checks
* Internal notification systems (Slack, PagerDuty, email)
**Time Saved:** 78% reduction in deployment errors and troubleshooting time
**Example Skills:**
* Run Pre-PR Code Review Checklist
* Security Audit for Pull Request
* Performance Review Checklist
* Accessibility Compliance Check
* Database Migration Review
**Why Custom?**
Your team's code review standards are unique:
* Company-specific security requirements
* Performance benchmarks for your app
* Custom linters and formatters
* Internal compliance rules (GDPR, SOC 2, HIPAA)
* Team-specific best practices
**Time Saved:** 2 hours per feature by eliminating back-and-forth on style/process
**Example Skills:**
* Implement Feature Following Company Standards
* Create API Endpoint (Company Style)
* Write Tests Using Team Framework
* Add Logging and Error Handling
* Implement Authentication Flow
**Why Custom?**
Your coding patterns are unique:
* Specific architecture patterns (layered, clean, hexagonal)
* Internal libraries and frameworks
* Custom error handling conventions
* Logging standards (format, levels, context)
* Authentication and authorization patterns
**Impact:** 92% fewer code style inconsistencies in pull requests
**Example Skills:**
* Run Security Audit on New Code
* Check for Secrets in Codebase
* Validate Input Sanitization
* Review Authentication Implementation
* Scan Dependencies for Vulnerabilities
**Why Custom?**
Security requirements vary by industry:
* Company-specific security tools (Snyk, Checkmarx, internal scanners)
* Compliance requirements (PCI-DSS, HIPAA, SOC 2)
* Custom vulnerability detection rules
* Internal security approval workflows
* Integration with security ticketing systems
**Impact:** Zero security incidents from missed security scans (down from 4/year)
**Example Skills:**
* Setup Local Development Environment
* Configure Database and Seed Data
* Install Team Tools and Extensions
* Setup Docker Compose Stack
* Configure IDE Settings
**Why Custom?**
Every team's setup is different:
* Specific tool versions (Node 22, PHP 8.2, Python 3.12)
* Internal package repositories
* Database connection strings
* Environment variable templates
* Team-specific IDE configurations
**Time Saved:** 3x faster onboarding (from 3 days to 1 day)
**Example Skills:**
* Integrate with Internal Payment Service
* Call Internal Authentication API
* Fetch Data from Company Data Lake
* Send Events to Internal Event Bus
* Generate Client for Internal API
**Why Custom?**
Internal APIs are unique to your organization:
* Custom authentication schemes
* Internal API conventions
* Company-specific error handling
* Internal rate limiting patterns
* Documentation links to internal wikis
**Impact:** 100% correct API integration patterns (down from 40% rework rate)
**Example Skills:**
* Backup Production Database
* Create Database Migration
* Run Data Transformation Script
* Optimize Query Performance
* Setup Database Replication
**Why Custom?**
Database workflows vary by company:
* Specific backup procedures and retention policies
* Company-specific migration conventions
* Custom database tools and utilities
* Environment-specific connection management
* Data privacy and masking requirements
**Impact:** Zero missed backup steps (down from 12 incidents/year)
**Example Skills:**
* Send Deployment Notification to Slack
* Create Incident Report in Jira
* Email Release Notes to Stakeholders
* Post Update to Internal Status Page
* Notify On-Call Engineer
**Why Custom?**
Notification patterns are company-specific:
* Internal Slack channels and webhooks
* Company ticketing systems (Jira, Linear, Asana)
* Email templates and distribution lists
* Status page integrations (StatusPage, internal tools)
* PagerDuty/on-call systems
**Time Saved:** Automated notifications save 30 minutes per deployment
***
## Creating Your First Custom Skill
Let's walk through creating a **"Deploy to Staging Environment"** skill—one of the most common and valuable custom skills.
### Step 1: Plan Your Skill
Before writing anything, document your current manual process.
**What does this skill accomplish?**
Deploy the application to the staging environment with proper verification and team notification.
**What must be true before this skill can run?**
* Docker installed and authenticated to registry
* kubectl configured for staging cluster
* Staging namespace exists in Kubernetes
* Slack webhook URL configured in environment
* All tests passing locally
**What do you do manually today?**
1. Developer runs `npm test`
2. Developer runs `npm run build`
3. Developer runs `docker build`
4. Developer pushes to registry
5. Developer runs `kubectl apply`
6. Developer checks logs
7. Developer posts in #deployments Slack channel
**How do you verify it worked?**
* Deployment shows READY 3/3
* All pods in Running state
* Health endpoint returns 200 OK
* Smoke tests pass
* Slack notification posted
**What happens after this skill completes?**
* Monitor error tracking for 10-15 minutes
* Verify staging functionality with QA team
* Create production deployment PR if stable
* Use "Deploy to Production" skill when approved
### Step 2: Create Skill in ULPI Dashboard
Go to [app.ulpi.io/skills](https://app.ulpi.io/skills) → Click **Create Skill**
**Name**: `Deploy to Staging Environment`
**Slug**: `deploy-to-staging` (auto-generated, URL-friendly)
**Description**: `Deploy application to staging environment with health checks and team notification`
**Tech Stack Filters**: Select technologies this skill applies to
* `docker`
* `kubernetes`
* `nodejs` (or your primary language)
* Add more as needed
**Tags**: Categorize for organization
* `deployment`
* `devops`
* `staging`
**Status**: ✅ Active (makes skill available to AI immediately)
Write your skill content in the ULPI dashboard editor using Markdown format.
**Skill Structure:**
1. Title and description
2. Prerequisites section (required tools, knowledge, environment)
3. Steps section (numbered, actionable steps with code examples)
4. Testing section (verification commands and expected results)
5. Next Steps section (follow-up actions)
**Example: Deploy to Staging Environment**
* Prerequisites: Docker, kubectl, Slack webhook, tests passing
* Steps: Run tests → Build assets → Build Docker image → Push to registry → Deploy to Kubernetes → Run health checks → Notify team (8 steps total)
* Testing: Check deployment status, pod status, health endpoint, smoke tests
* Next Steps: Monitor 10-15 minutes, verify with QA, create prod PR if stable
See the "Skill Template Structure" section below for detailed formatting guidelines.
Click **Save** to create the skill.
Toggle **Active** status to make it available to your AI assistant immediately.
### Step 3: Use Your Custom Skill
In your AI coding assistant:
```
"Use our 'Deploy to Staging Environment' skill to deploy the latest changes"
```
Your AI will:
1. ✅ Fetch the skill from ULPI via MCP
2. ✅ Follow all 8 steps sequentially
3. ✅ Execute commands (with your permission if configured)
4. ✅ Run health checks and verify deployment
5. ✅ Notify your team in Slack
6. ✅ Report completion with next steps
**Time to first deployment with skill:** \~2 minutes (vs 30-45 minutes manually with potential errors)
***
## Skill Anatomy & Best Practices
Every great skill follows a consistent structure. Here's what makes a skill effective:
### Skill Template Structure
````text theme={null}
# [Skill Name]
[Brief description of what this skill accomplishes]
## Prerequisites
- [Required tool or knowledge 1]
- [Required tool or knowledge 2]
- [Environment setup needed]
## Steps
1. **[Step 1 Title]**
[Explanation of what this step does and why]
```bash
[command to execute]
```
[Additional context or notes]
2. **[Step 2 Title]**
[More instructions]
```language
[code example]
```
## Testing
[How to verify the implementation works]
```bash
[test commands]
```
[Expected results]
## Next Steps
- [Suggested follow-up task 1]
- [Suggested follow-up task 2]
- [Related skills to use next]
````
### Component Breakdown
**Best Practices:**
* Use clear, action-oriented title (starts with verb)
* Keep description to 1-2 sentences
* Focus on outcome, not process
**Examples:**
* ✅ Good: "Deploy to Production" / "Deploy application to production with zero-downtime rollout"
* ❌ Bad: "Production Deployment Thing" / "This skill handles various deployment scenarios"
**Best Practices:**
* List tools that must be installed
* Specify knowledge developer should have
* Note environment configuration needed
* AI checks these before executing
**Examples:**
* ✅ Good: "Docker 20+ installed and authenticated to registry"
* ❌ Bad: "Docker setup"
**Best Practices:**
* Number steps sequentially (AI follows in order)
* Each step has a clear, actionable title
* Include code examples for every step
* Explain the "why," not just the "what"
* Make steps atomic (one clear action per step)
**Examples:**
* ✅ Good: "**Run test suite** — Ensure all tests pass before deploying. This prevents deploying broken code to staging."
* ❌ Bad: "**Step 3** — Do the tests"
**Best Practices:**
* Provide commands to verify it worked
* Specify expected output
* Include what to do if tests fail
* AI can execute tests automatically
**Examples:**
* ✅ Good: "Run `curl https://staging.myapp.com/health`. Expected: HTTP 200 with `{\"status\": \"ok\"}`. If fails: Check pod logs."
* ❌ Bad: "Make sure it works"
**Best Practices:**
* Suggest follow-up actions
* Link to related skills
* Provide documentation references
* Help AI continue the workflow
**Examples:**
* ✅ Good: "Monitor error tracking for 10 minutes. If stable, use 'Deploy to Production' skill."
* ❌ Bad: "You're done"
### Writing Best Practices
❌ Bad: "Do deployment stuff"
✅ Good: "Deploy to Kubernetes staging namespace"
❌ Bad: "Step 3"
✅ Good: "Build Docker image with commit SHA tag"
❌ Bad:
````text theme={null}
1. **Run tests**
```bash
npm test
````
````
✅ Good:
```text
1. **Run test suite**
Ensure all tests pass before deploying.
This prevents deploying broken code.
```bash
npm test
````
All tests must pass. If any fail,
stop and fix them first.
````
Every step should have:
- The actual command to run
- Expected output or result
- What to do if it fails
✅ Example:
```text
1. **Check database connection**
```bash
php artisan tinker --execute="DB::connection()->getPdo();"
````
**Expected**: Returns PDO object
**If fails**: Check .env database credentials
````
Each step = one clear action
❌ Bad (too much in one step):
```text
1. **Build and deploy**
Build app, create Docker image,
push to registry, and deploy.
````
✅ Good (atomic steps):
```text theme={null}
1. **Build production assets**
2. **Create Docker image**
3. **Push to container registry**
4. **Deploy to staging**
```
Tell AI what to do when things go wrong:
```bash theme={null}
php artisan migrate --force
```
**If migrations fail**:
* Check for syntax errors
* Verify database connectivity
* Ensure migrations haven't run yet
* Check user has ALTER permission
* Roll back if needed
Always include testing/verification:
**Check health endpoint:**
```bash theme={null}
curl -f https://staging.myapp.com/health
# Should return HTTP 200 with {"status": "ok"}
```
**Test critical endpoints:**
```bash theme={null}
curl https://staging.myapp.com/api/users | jq
# Should return valid JSON user list
```
**Check error logs:**
```bash theme={null}
tail -f storage/logs/laravel.log
# Should show no ERROR entries
```
**Run smoke tests:**
```bash theme={null}
npm run test:smoke -- --env=staging
# All smoke tests should pass
```
***
## Common Custom Skill Templates
### 1. Deployment Skill Template
Use this template structure for deployment skills:
**Skill Structure:**
* Title: `# Deploy to [Environment]`
* Description: Deploy application to \[environment] environment
* Prerequisites: List required tools and credentials
* Steps: Numbered deployment steps with bash commands
* Testing: Health checks and verification steps
* Next Steps: Post-deployment actions
**Example Template:**
```
Title: Deploy to Production
Prerequisites: Docker, kubectl, registry auth, tests passing
Steps: Run tests → Build artifacts → Deploy → Verify → Notify team
Testing: Health endpoint, features functional, no errors, smoke tests pass
Next Steps: Monitor for [duration], document issues, proceed if stable
```
### 2. Code Review Checklist Skill
````text theme={null}
# Run Code Review Checklist
Complete code review checklist for pull request.
## Prerequisites
- Pull request created
- CI passing
- No merge conflicts
## Steps
1. **Check code style**
Verify code follows team standards.
```bash
npm run lint
./vendor/bin/pint --test
````
2. **Review test coverage**
Ensure new code is tested.
```bash theme={null}
npm run test:coverage
```
Coverage should be greater than 80% for new files.
3. **Check for security issues**
Run security scanners.
```bash theme={null}
npm audit
composer audit
```
4. **Verify documentation**
* Are public methods documented?
* Is README updated if needed?
* Are breaking changes noted?
5. **Review database changes**
* Do migrations have down() methods?
* Are indexes added for foreign keys?
* Is data migration tested?
6. **Check performance**
* Are there N+1 queries?
* Are expensive operations queued?
* Are large datasets chunked?
7. **Leave review comment**
Summarize findings in PR comment.
## Testing
* All checks passed
* No security vulnerabilities
* Adequate test coverage
## Next Steps
* Approve PR if all checks pass
* Request changes if issues found
* Tag relevant team members for additional review
````
### 3. Environment Setup Skill
```text
# Setup Local Development Environment
Configure local development environment for new team members.
## Prerequisites
- macOS, Linux, or Windows WSL2
- Administrative access
- 10GB free disk space
## Steps
1. **Install Homebrew** (macOS/Linux)
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
````
2. **Install required tools**
```bash theme={null}
brew install php@8.2 composer node mysql redis
```
3. **Clone repository**
```bash theme={null}
git clone git@github.com:company/repo.git
cd repo
```
4. **Copy environment file**
```bash theme={null}
cp .env.example .env
```
Edit `.env` with your local database credentials.
5. **Install dependencies**
```bash theme={null}
composer install
npm install
```
6. **Generate application key**
```bash theme={null}
php artisan key:generate
```
7. **Start services**
```bash theme={null}
brew services start mysql
brew services start redis
```
8. **Run migrations**
```bash theme={null}
php artisan migrate --seed
```
9. **Start development server**
```bash theme={null}
php artisan serve
npm run dev # In separate terminal
```
## Testing
* Visit [http://localhost:8000](http://localhost:8000)
* Login with seeded user ([user@example.com](mailto:user@example.com) / password)
* Verify all features work locally
## Next Steps
* Read team documentation in `docs/`
* Ask for code walkthrough from mentor
* Complete "Hello World" task to verify setup
````
---
## Managing Custom Skills
### Organizing Skills
**Naming Conventions:**
- Use clear, action-oriented names
- Include environment: "Deploy to Staging", "Deploy to Production"
- Be specific: "Run Security Scan" not "Check Stuff"
**Tagging Strategy:**
- `deployment`: All deployment-related skills
- `testing`: Testing and QA procedures
- `security`: Security scanning and compliance
- `onboarding`: New team member tasks
- `documentation`: Doc generation and updates
- `devops`: Infrastructure and operations
**Folders** (via tags):
Use consistent tag prefixes for logical grouping:
- `deploy-staging`, `deploy-production`, `deploy-rollback`
- `test-unit`, `test-integration`, `test-e2e`
### Active vs Inactive Skills
**Active Skills:**
- ✅ Visible to AI assistant
- ✅ Count against plan limit (5/25/unlimited)
- ✅ Immediately available via MCP
- ✅ Cached for fast access
**Inactive Skills:**
- ❌ Hidden from AI
- ✅ Don't count against limit
- ✅ Stored for future use
- ✅ Can be reactivated anytime
**When to Deactivate:**
- Seasonal workflows (tax season, year-end closing)
- Deprecated procedures
- Testing new skill versions
- Approaching plan skill limit
### Versioning Skills
Track skill changes for team awareness:
**Version Format**: `v1.0`, `v1.1`, `v2.0`
- **Major** (v2.0): Complete workflow change
- **Minor** (v1.1): New steps added
- **Patch** (v1.0.1): Fixes and clarifications
**Version in Skill Description** (recommended):
```text
# Deploy to Production
**Version 2.0** — Updated October 2024
**Changelog:**
- Now uses GitHub Actions instead of Jenkins
- Added automated rollback on failure
- Improved health check coverage
````
### Sharing Skills
**Within Your Team:**
* All team members see custom skills automatically
* Changes propagate to all AI assistants (1 hour cache)
* Collaborative skill improvement
**With Other Teams** (same organization):
* Custom skills visible across entire organization
* Use tags to organize by team if needed
**With Public** (future feature):
* Submit custom skills to ULPI for review
* If approved, becomes public skill available to all users
* Your team gets credit and recognition
***
## Advanced Techniques
### Skill Composition
Reference other skills within a skill:
```text theme={null}
# Complete Feature Development
End-to-end feature development workflow.
## Steps
1. **Create feature branch**
Use the "Git Branch Strategy" skill
2. **Implement feature**
Follow our coding standards using the "Implement Feature (Company Style)" skill
3. **Write tests**
Use the "Write Tests for Feature" skill
4. **Create pull request**
Use the "Create Pull Request" skill
5. **Deploy to staging**
Use the "Deploy to Staging" skill
6. **Run QA tests**
Use the "Run QA Test Suite" skill
```
AI will fetch and execute referenced skills automatically.
### Conditional Logic
Guide AI through conditional paths:
````text theme={null}
1. **Check if database migration needed**
```bash
git diff main HEAD -- database/migrations/
````
**If migrations changed**:
* Review each migration carefully
* Test migrations on staging first
* Prepare rollback plan
* Continue to step 2
**If no migrations**:
* Skip to step 3 (no database changes needed)
````
### Environment Variables
Use placeholders for dynamic values:
```text
1. **Deploy to {environment}**
```bash
kubectl apply -f k8s/{environment}/ -n {environment}
````
Replace {environment} with: `staging`, `production`, `development`
````
AI automatically asks for or infers these values from context.
### Multi-Step Validation
Build in verification at each step:
```text
1. **Build Docker image**
```bash
docker build -t myapp:latest .
````
✅ **Verify**: `docker images | grep myapp`
Should show image created just now.
2. **Push to registry**
```bash theme={null}
docker push myapp:latest
```
✅ **Verify**: `docker pull myapp:latest`
Should download without errors.
3. **Deploy to Kubernetes**
```bash theme={null}
kubectl apply -f k8s/production/
```
✅ **Verify**: `kubectl get deployment myapp`
Should show READY 3/3.
```
---
## Troubleshooting Custom Skills
**Possible Causes:**
- Steps unclear or ambiguous
- Missing prerequisites
- Code examples have errors
- Skill too complex (too many steps)
**Solutions:**
1. **Make steps more explicit:**
- Add more detail to step descriptions
- Include expected outcomes
- Explain why each step is necessary
2. **Add more code examples:**
- Every step should have runnable code
- Show exact commands, not just concepts
3. **Break complex skill into smaller skills:**
- Skills with >10 steps are hard to follow
- Create separate skills and use skill composition
4. **Test skill with AI before saving:**
- Ask AI to read through the skill
- Check if AI understands each step
**Possible Causes:**
- Skill not marked "Active"
- Tech stack filters exclude repository
- MCP server cache not refreshed
**Solutions:**
1. **Check "Active" toggle:**
- Go to Skills dashboard
- Verify skill shows green "Active" badge
- Toggle off and on if needed
2. **Review tech stack filters:**
- Check skill's tech stack filters
- Ensure repository has at least one matching technology
- Consider making skill "Universal" (no filters)
3. **Restart IDE to clear cache:**
- Quit IDE completely
- Restart
- Wait 10 seconds for MCP connection
- Ask AI to list skills again
4. **Verify MCP connection:**
- Check MCP server status in IDE
- Look for 🔌 connection icon
- Review MCP logs for errors
**Cause:** MCP cache (1 hour TTL)
**Solutions:**
1. **Restart IDE immediately:**
- Fastest way to clear cache
- MCP server fetches latest skill content
2. **Wait 1 hour for auto-refresh:**
- Cache expires automatically
- No action needed
3. **Update skill version in name:**
- Change name from "Deploy to Staging" to "Deploy to Staging v2"
- Forces cache refresh
4. **Disable cache during development:**
- Set ULPI_CACHE_ENABLED to false in env
- Re-enable in production for performance
**Possible Causes:**
- Different MCP cache states
- Different repository configurations
- Skills toggled active/inactive
**Solutions:**
1. **Verify all team members use same repository ID:**
- Check `ULPI_REPOSITORY_ID` in MCP config
- Ensure everyone points to same repo
2. **Ask all team members to restart IDE:**
- Syncs cache state across team
3. **Check skill active status:**
- Verify skill is "Active" in dashboard
- Inactive skills hidden from all users
4. **Confirm tech stack detection:**
- Skills filter by detected technologies
- Ensure repository tech stack detected correctly
---
## Next Steps
View all 10 public skills for inspiration
Understand skill execution internals
Learn how ULPI filters skills by technology
Set up Skills from scratch in 10 minutes
Advanced MCP configuration for 40+ AI tools
Common questions and answers
---
**Need help creating custom skills?** Contact support@ulpi.io or [join our Discord](https://discord.gg/ulpi) for examples and templates.
```