Creating New Skills

This skill explains how to create new skills that follow the agentskills.io specification.

🤖 Automatic Skill Identification (For Agent)

During any work, I should actively monitor for these signals:

• Repetition: I'm explaining the same process for the 3rd time

• Complexity: Workflow involves >5 sequential steps

• Project-specific: Process is unique to this codebase (not generic programming)

• Pattern discovery: Similar logic appears in 3+ different files

• Manual toil: Repetitive task that could be documented/automated

Action: If 2 or more are true → PROPOSE creating a skill to the user

When to Create a Skill

Create a new skill when you have:

• Repeatable workflows that are used frequently

• Domain-specific expertise that needs to be documented

• Multi-step processes that require consistent execution

• Best practices for a specific area of the codebase

Examples:

• ✅ Email notification process

• ✅ Reporting and analytics workflow

• ✅ Authentication patterns

• ❌ One-time fixes (document in docs/ instead)

• ❌ Temporary workarounds

Directory Structure

Basic Skill (most common)

.agent/skills/ └── skill-name/ └── SKILL.md # Required

Complex Skill (with additional resources)

.agent/skills/ └── skill-name/ ├── SKILL.md # Required ├── scripts/ # Helper scripts │ └── helper.sh ├── references/ # Reference documentation │ └── REFERENCE.md └── assets/ # Templates, diagrams, data files └── template.json

Naming Rules

Skill names must follow these rules:

• 1-64 characters

• Lowercase only (a-z)

• Use hyphens (-) to separate words

• No consecutive hyphens (--)

• Cannot start or end with hyphen

• Must match directory name

✅ Valid Names

name: api-testing name: user-authentication name: email-notifications name: create-skill

❌ Invalid Names

name: API-Testing # No uppercase name: api_testing # No underscores name: -api-testing # Cannot start with hyphen name: api--testing # No consecutive hyphens

SKILL.md Template

name: skill-name description: A clear, specific description of what this skill does and when to use it. Include keywords that help identify when this skill is relevant.

Skill Title

Brief introduction explaining the purpose of this skill.

Section 1: Overview

Explain the core concept or workflow.

Section 2: Step-by-Step Guide

Provide detailed instructions with code examples.

Subsection Example

// Code example

Common Pitfalls

List common mistakes and how to avoid them.

Examples

Provide real-world examples of using this skill.

---

## Frontmatter Fields

### Required Fields

#### `name`
- Must match the directory name
- Follow naming rules above

```yaml
name: database-migrations

description

- 1-1024 characters

- Describe what the skill does

- Describe when to use it

- Include specific keywords for discoverability

description: How to create and run database migrations using Prisma. Use when adding new tables, modifying schemas, or updating database structure in development and production.

Optional Fields

license

license: MIT

compatibility

Use if skill has specific requirements:

compatibility: Requires Prisma, PostgreSQL, and Node.js 18+

metadata

Key-value pairs for additional info:

metadata:
  author: project-team
  version: "1.0"
  last-updated: "2026-01-17"

Writing Good Descriptions

✅ Good Descriptions

description: How to deploy changes to production using PM2 and GitHub auto-deploy. Use when pushing code updates, database migrations, or configuration changes to the Hetzner server.

Why: Specific, mentions tools, explains when to use it.

description: Guidelines for creating React components following the component-first architecture. Use when building new UI elements or refactoring inline code into reusable components.

Why: Clear purpose, mentions architectural pattern, explains context.

❌ Bad Descriptions

description: Helps with deployment

Why: Too vague, no context, missing keywords.

description: This skill is for components

Why: Doesn't explain what aspect or when to use it.

Optional Directories

scripts/

Use for helper scripts that:

- Automate repetitive tasks

- Validate configurations

- Transform data

Example:

scripts/
├── validate-schema.sh
└── generate-migration.js

Scripts should:

- Be self-contained or document dependencies

- Include helpful error messages

- Handle edge cases gracefully

references/

Use for detailed technical documentation:

- API specifications

- Form templates

- Domain-specific guides

Example:

references/
├── REFERENCE.md      # Detailed API reference
├── FORMS.md          # Form templates
└── best-practices.md # Extended guidelines

assets/

Use for supporting files:

- Configuration templates

- Diagrams and images

- Lookup tables or schemas

Example:

assets/
├── api-flow.png
├── config-template.json
└── migration-template.sql

Checklist for New Skills

Before creating a skill, verify:

-  The workflow is used more than once

-  The skill has a clear, specific purpose

-  The name follows naming rules

-  Description includes what, when, and keywords

-  Directory name matches skill name

-  SKILL.md has proper frontmatter

-  Content is organized with headers

-  Examples are provided

-  Common pitfalls are documented

Example: Creating "email-notifications" Skill

1. Create Directory

mkdir -p .agent/skills/email-notifications

2. Create SKILL.md

---
name: email-notifications
description: How to send email notifications using the project's email service. Use when implementing user confirmations, admin alerts, or scheduled reports.
---

# Email Notifications

This skill explains how to send emails in the Digital Befaring application.

---

## Email Templates

All templates are in `src/lib/email/templates/`.

### Available Templates
- `customer-confirmation.tsx` - Customer form submission
- `admin-alert.tsx` - Admin notifications
- `technician-assignment.tsx` - Job assignment

---

## Sending an Email

```typescript
import { sendEmail } from '@/lib/email';

await sendEmail({
    to: customer.email,
    subject: 'Skjema mottatt',
    template: 'customer-confirmation',
    data: { customerName: customer.name }
});

Testing

Test emails in development using Ethereal.

### 3. Update GEMINI.md (Optional)
If this is a major skill, mention it in the project documentation.

---

## Validation

After creating a skill, verify:

```bash
# Check structure
ls -la .agent/skills/skill-name/

# Verify frontmatter format
head -n 5 .agent/skills/skill-name/SKILL.md

# Test that agent can read it
# (In conversation, reference the skill and see if agent finds it)

Maintenance

Keep skills up-to-date:

- Update when workflows change

- Add new examples as patterns emerge

- Remove outdated information

- Version metadata if needed

metadata:
  last-updated: "2026-01-17"
  version: "1.1"