Creating Custom Skills

This guide walks you through creating a custom Agent Skill from scratch, following the Anthropic Agent Skills specification.

Prerequisites

• A MeetLoyd instance (local or staging)
• Familiarity with Markdown and YAML frontmatter

Quick Start

1. Create the Skill Directory

Skills live in the skills/ directory at the project root. Each skill is a directory containing at minimum a SKILL.md file.

mkdir -p skills/my-custom-skill/references
mkdir -p skills/my-custom-skill/scripts
mkdir -p skills/my-custom-skill/assets

important

The directory name must match the name field in your SKILL.md frontmatter.

2. Write SKILL.md

Create skills/my-custom-skill/SKILL.md:

---
name: my-custom-skill
description: One-paragraph description of what this skill does and when to use it. Include keywords that help agents discover it. Max 1024 characters.
license: MIT
compatibility: MeetLoyd agents, Claude Code
metadata:
  author: your-company
  version: "1.0.0"
  category: engineering
  tags:
    - keyword1
    - keyword2
---

# My Custom Skill

Brief introduction to the skill.

## When to Use This Skill

Activate this skill when:
- Condition 1
- Condition 2
- Condition 3

Do NOT activate for:
- Irrelevant scenario 1
- Irrelevant scenario 2

## Core Framework

Your main methodology, decision tree, or process.

## Quick Reference

Key facts, tables, or templates the agent needs immediately.

## Reference Files

For detailed guidance:
- [DETAILED-GUIDE.md](references/DETAILED-GUIDE.md) - Extended documentation
- [TEMPLATES.md](references/TEMPLATES.md) - Response templates

## Scripts

- [helper-script.py](scripts/helper-script.py) - Automation helper

3. Validate Your Skill

MeetLoyd includes a built-in validator that checks your skill against the Anthropic spec:

import { parseSkillMd, validateSkill } from './src/skills/parser'
import { readFileSync } from 'fs'

const content = readFileSync('skills/my-custom-skill/SKILL.md', 'utf-8')
const parsed = parseSkillMd(content)
const result = validateSkill(parsed, 'my-custom-skill')

console.log(result)
// { valid: true, errors: [], warnings: [] }

You can also use the reference library from the spec:

npx skills-ref validate ./skills/my-custom-skill

4. Register and Assign

Once your skill directory is in place, the skill registry picks it up automatically on startup. Assign it to an agent via the dashboard or API:

// Via API
await fetch('/api/skills/my-skill-db-id/assign', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 'agent-123',
    priority: 1,
  }),
})

Or use the dashboard: Agent Settings → Skills → Assign Skill.

Frontmatter Reference

Field	Required	Constraints
name	Yes	1-64 chars. Lowercase a-z, 0-9, -. No consecutive hyphens. Must match directory name.
description	Yes	1-1024 chars. Describe what + when. Include discovery keywords.
license	No	License name or reference to bundled file.
compatibility	No	1-500 chars. Environment requirements.
metadata	No	Arbitrary key-value map.
metadata.author	No	Organization or individual name.
metadata.version	No	Semver string (e.g., "1.0.0").
metadata.category	No	One of: sales, support, hr, finance, legal, marketing, product, engineering, operations, compliance, general.
metadata.tags	No	Array of lowercase keywords for search.
allowed-tools	No	Space-delimited pre-approved tools (experimental).

Name Validation Rules

✅ Valid: pdf-processing, data-analysis, code-review, my-skill-v2
❌ Invalid: PDF-Processing (uppercase), -pdf (starts with hyphen),
           pdf--processing (consecutive hyphens), my skill (spaces)

Directory Structure

skills/my-custom-skill/
├── SKILL.md              # Required — frontmatter + instructions
├── references/           # Optional — detailed docs (loaded on demand)
│   ├── GUIDE.md
│   ├── EXAMPLES.md
│   └── FAQ.md
├── scripts/              # Optional — executable automation
│   ├── classify.py
│   └── extract.sh
└── assets/               # Optional — static resources
    ├── templates.json
    ├── flowchart.png
    └── schema.yaml

Reference Files

Reference files provide depth without bloating the main instructions. They're loaded on demand when the agent needs them.

Good candidates for references:

• Detailed playbooks (e.g., ESCALATION-MATRIX.md)
• Response template libraries (e.g., TEMPLATES.md)
• Domain-specific lookup tables (e.g., TAX-RATES-2025.md)
• Competitor battlecards, FAQ collections

Link them from SKILL.md:

For complete SLA definitions, see [SLA-DEFINITIONS.md](references/SLA-DEFINITIONS.md).

Scripts

Scripts are executable code agents can run. They should be:

• Self-contained (document dependencies)
• Include error messages
• Handle edge cases

Supported languages: Python, Bash, JavaScript, TypeScript.

Assets

Static resources like templates, images, data files, or schemas. These are loaded by path when referenced.

Progressive Disclosure

Skills use a 3-level loading strategy to minimize context usage:

Level	What's Loaded	When	Token Budget
1. Metadata	name + description	At startup, for all skills	~100 tokens
2. Instructions	Full SKILL.md body	When skill is activated	< 5,000 tokens
3. Resources	references/, scripts/, assets/	When specifically needed	As needed

Key rule: Keep SKILL.md under 500 lines. Move detailed content to reference files.

Agent starts → sees all skill summaries (Level 1)
Agent encounters sales objection → loads full instructions (Level 2)
Agent needs competitor-specific response → loads battlecard reference (Level 3)

Writing Effective Skills

1. Strong Trigger Conditions

Tell the agent exactly when to use the skill:

## When to Use This Skill

Activate when:
- Customer mentions "pricing", "cost", or "budget"
- Prospect says "too expensive" or "over budget"
- Discussion involves competitor comparison

Do NOT activate for:
- General product questions
- Technical support issues
- Feature requests

2. Decision Trees

Agents work well with structured decision logic:

## Priority Decision Tree

NEW TICKET
    │
    ▼
Is system completely down? ──YES──→ P1 Critical
    │ NO
    ▼
Is core feature broken? ──YES──→ P2 High
    │ NO
    ▼
Workaround available? ──NO──→ P3 Medium
    │ YES
    ▼
P4 Low

3. Copy-Paste Templates

Provide ready-to-use templates the agent can adapt:

## Response Template

Hi [NAME],

I understand [CONCERN]. Let me address that directly:

[RESPONSE USING FRAMEWORK]

Does that help clarify things? Happy to dig deeper.

[AGENT NAME]

4. Concrete Examples

Show input/output pairs:

## Example

**Customer says:** "Your competitor offers the same thing for half the price"

**Agent response:**
"Smart to compare options. What specifically appeals to you about
[Competitor]? [wait for response]

The main things our customers found when comparing:
1. [Differentiator 1]
2. [Differentiator 2]

Which of those matters most to your team?"

5. Anti-Patterns

Tell the agent what NOT to do:

## What NOT to Do

- Don't discount immediately — explore the concern first
- Don't badmouth competitors — focus on your value
- Don't overwhelm with features — address the specific concern
- Don't skip the exploration phase — ask before answering

Real-World Example: MFO Tax Optimization

Here's a production skill from the MFO vertical that demonstrates best practices:

---
name: tax-optimization
description: Expert French tax advisor for wealth management. Analyzes fiscal profiles, calculates IFI/CDHR exposure, optimizes life insurance and asset sale timing. Use when client asks about tax planning, optimization, or fiscal impact.
license: proprietary
compatibility: MeetLoyd agents
metadata:
  author: meetloyd
  version: "1.0.0"
  category: finance
  tags:
    - tax
    - france
    - wealth-management
    - ifi
    - cdhr
---

# Tax Optimization Advisor

## When to Use This Skill

Activate when:
- Client asks about **tax planning** or fiscal optimization
- Analyzing **IFI** (Impôt sur la Fortune Immobilière) exposure
- Evaluating **CDHR** (Contribution sur les Hauts Revenus) impact
- Optimizing **life insurance** (assurance-vie) allocations
- Timing **asset sales** for minimal tax impact

## Workflow

1. **Fiscal Profile** → Gather household composition, TMI, residency
2. **Asset Mapping** → Inventory with current values and tax basis
3. **Income Tax Analysis** → Calculate marginal rate and optimization levers
4. **IFI Exposure** → Real estate > 1.3M EUR threshold
5. **CDHR Exposure** → High revenue contribution (250k/500k thresholds)
6. **Life Insurance** → Compare contract options and fiscal advantages
7. **Asset Sale Timing** → Capital gains optimization
8. **Report** → Structured recommendations with calculations

## MCP Tools Available

| Tool | Purpose |
|------|---------|
| `mfo_income_tax_calculate` | Calculate income tax by bracket |
| `mfo_marginal_rate_get` | Get TMI for given household |
| `mfo_ifi_calculate` | Calculate IFI liability |
| `mfo_cdhr_calculate` | Calculate CDHR contribution |
| `mfo_av_compare_options` | Compare life insurance options |

This skill works because it:

• Has clear activation triggers (when to use)
• Defines a structured workflow (8 steps)
• Lists available MCP tools the agent can call
• Includes concrete parameters (tax thresholds, rates)

Testing Skills

Manual Testing

1. Assign the skill to a test agent
2. Start a conversation that should trigger the skill
3. Verify the agent loads the skill via skill_query tool call
4. Check that references load correctly when needed

Validation Checklist

• name matches directory name
• description is under 1024 characters and includes keywords
• SKILL.md is under 500 lines
• All referenced files exist (references/, scripts/)
• No broken markdown links
• Frontmatter passes validateSkill() with no errors
• Skill loads correctly via loadSkill() without errors

Publishing to the Store

Custom skills can be published to the MeetLoyd Store for other tenants:

1. Ensure your skill passes all validation
2. Go to Store → Publish
3. Upload skill directory
4. Set pricing (free or subscription)
5. Submit for review

See Store Publishing for details.

---

Next: Learn about the Skills Architecture to understand how skills are loaded and served internally.