Each time, the agent follows the instruction perfectly. And each time, it's forgotten by the next session.
Skills solve this. You write the instruction once, as a markdown file, and the agent loads it automatically whenever the task matches.
A skill is a folder with a SKILL.md file inside. The file has YAML frontmatter that tells the agent when to use it, and a markdown body that tells it what to do.
.elyra/skills/api-conventions/SKILL.md
---
name: api-conventions
description: API response formatting and error handling conventions. Use when building or modifying API endpoints, writing controllers, or handling API errors.
---
# API Conventions
## Response Format
All API responses use this structure:
```json
{
"data": { ... },
"meta": { "current_page": 1, "last_page": 5, "total": 47 }
}
```
## Error Responses
Use standard HTTP status codes. Always return:
```json
{
"message": "Human-readable error",
"errors": { "field": ["Validation message"] }
}
```
## Rules
- Always validate requests with Form Requests
- Always return JSON, never views
- Use API Resources for response transformation
- Paginate collections by default (15 per page)
When someone asks the agent to build an API endpoint, it sees this skill's description, recognizes the task matches, loads the full instructions, and follows them. Every endpoint comes out consistent. No re-explaining.
Elyra's skill format is now fully compatible with Anthropic's Agent Skills specification. If you've built skills for Claude.ai, they work in Elyra without modification. And skills you build in Elyra work in Claude.ai.
The frontmatter supports all standard fields:
---
name: my-skill
description: What it does. Use when user asks to...
license: MIT
compatibility: Requires Node.js 20+
allowed-tools: "Bash(python:*) WebFetch"
metadata:
author: Your Name
version: 1.0.0
category: workflow
---
allowed-tools restricts which tools the agent can use when the skill is active. compatibility documents requirements. metadata holds arbitrary key-value pairs for organization and discovery.
Skills can now include executable scripts and reference documents:
my-skill/
├── SKILL.md
├── scripts/
│ ├── validate.py
│ └── generate-report.sh
└── references/
├── api-guide.md
└── style-guide.md
The scripts/ directory contains code the agent can execute. The references/ directory contains documentation the agent can read when it needs deeper context.
Both are auto-discovered and exposed to the agent in the system prompt. When a skill has scripts, the agent knows they exist and can call them:
# In your SKILL.md:
Before submitting, run the validation script:
```bash
python scripts/validate.py --input {filename}
```
If validation fails, check `references/api-guide.md` for the correct format.
This is powerful for skills that encode complex workflows. Instead of describing a validation algorithm in natural language (where the agent might interpret it loosely), you write the actual validation in Python (where it's deterministic) and let the agent execute it.
/skills
Lists every loaded skill with its name, description, script and reference counts, and where it came from (which extension or local directory). Useful for understanding what knowledge the agent currently has access to.
Skills use progressive disclosure to minimize token usage:
Level 1: Frontmatter. Always in the system prompt. Just the name and description — enough for the agent to know when the skill is relevant. This costs a few tokens per skill.
Level 2: SKILL.md body. Loaded only when the agent decides the skill matches the current task. Contains the full instructions. Only costs tokens when actually used.
Level 3: References. Read on demand. The agent navigates to references/ files only when it needs specific details. Keeps the main instructions lean.
A project with 20 skills loaded doesn't burn 20x the tokens. The frontmatter for all 20 might be 500 tokens total. The body of the one that's relevant is maybe 1000. And references are loaded only if needed.
.elyra/skills/code-review/SKILL.md
---
name: code-review
description: Code review checklist and standards. Use when reviewing code, pull requests, or when asked to check code quality.
---
# Code Review Standards
Check in this order:
1. **Security**: SQL injection, XSS, auth bypasses, data exposure
2. **Correctness**: Logic errors, edge cases, null handling
3. **Tests**: Coverage, meaningful assertions, edge case tests
4. **Performance**: N+1 queries, missing indexes, expensive loops
5. **Conventions**: Naming, structure, patterns per project rules
Flag issues as:
- CRITICAL: Must fix before merge
- WARNING: Should fix, but not blocking
- SUGGESTION: Nice to have
.elyra/skills/migration-workflow/SKILL.md
---
name: migration-workflow
description: Database migration creation and safety checks. Use when creating migrations, modifying schema, or adding database columns.
---
# Migration Workflow
## Before Creating
1. Check existing schema with `get_database_schema`
2. Verify the table exists (or doesn't, for new tables)
3. Check for existing indexes that might conflict
## Rules
- Never modify existing migration files
- Always add `->after('column_name')` for column ordering
- Foreign keys need explicit index names
- Add `->index()` on all foreign key columns
- Use `nullOnDelete()` for optional relationships
- Large tables: use `--step` flag for reversible migrations
## After Creating
1. Run `php artisan migrate` to verify
2. Run `php artisan migrate:rollback` to verify reversibility
3. Check that seeders still work
.elyra/skills/deploy/SKILL.md
---
name: deploy
description: Pre-deployment verification checklist. Use when preparing to deploy, release, or push to production.
---
# Pre-Deploy Checklist
1. All tests pass (`npm run test` or `php artisan test`)
2. No uncommitted changes (`git status` is clean)
3. Changelog updated with new entries
4. Version bumped in package.json
5. Documentation reflects recent changes
6. No TODO/FIXME in changed files
7. Environment variables documented if new ones added
8. Migration tested (up and rollback)
Do NOT proceed with deploy if any check fails.
Report which checks passed and which failed.
Project-local (.elyra/skills/): Shared with the team via git. Everyone gets the same conventions.
Global (~/.elyra/agent/skills/): Personal to you. Workflows and preferences that follow you across projects.
Extensions: Each installed extension can bundle skills. @elyracode/swarm comes with a skill that teaches the agent when to use multi-agent pipelines. @elyracode/docker comes with a skill for container-awareness.
Project-local skills take priority if names conflict. Your project's conventions override global defaults.
Write for the next developer. Your skill will be read by an AI, but the audience is the human who comes after you. If a new team member reads your SKILL.md and understands the workflow, the AI will too.
Be specific about triggers. The description field determines when the skill loads. "Helps with code" won't trigger. "Use when building API endpoints, creating controllers, or modifying route files" will.
Put deterministic logic in scripts. If your workflow has a validation step, a calculation, or a format check, write it as code in scripts/ rather than describing it in natural language. Code doesn't hallucinate.
Keep SKILL.md focused. Move deep documentation to references/. The main instructions should be scannable — numbered steps, bullet points, clear rules. Save the explanations for reference files that the agent reads on demand.