Skills

Skills are reusable AI instructions that can be loaded on demand. They provide consistent guidance for specific tasks like code review, testing, or working with particular technologies.

What are Skills?

A skill is a markdown file containing instructions that an AI agent can load when performing a specific task. Unlike knowledge notes (which capture information), skills capture how to do things.

Examples of skills:

• Code Review — Consistent review criteria and checklist
• TypeScript Patterns — Coding conventions for TypeScript projects
• API Design — Guidelines for designing REST APIs
• Testing Strategy — How to approach writing tests

Skill Structure

Skills are stored in the skills/ directory, each in its own folder:

skills/
├── index.md                    # Auto-generated index
├── code-review/
│   ├── SKILL.md               # Main skill file
│   ├── examples/              # Optional examples
│   └── templates/             # Optional templates
└── typescript-patterns/
    └── SKILL.md

SKILL.md Format

Each skill uses YAML frontmatter followed by markdown instructions:

---
name: code-review
title: Code Review Guide
version: 1.0.0
description: Comprehensive code review checklist and guidelines
tags: [quality, review, process]
triggers: [/code-review, /review]
applyTo: ["*.ts", "*.tsx", "*.js"]
related: [typescript-patterns, testing-strategy]
---

# Code Review Guide

When reviewing code, follow these guidelines...

## Checklist

- [ ] Code follows project conventions
- [ ] Tests are included
- [ ] Error handling is appropriate
      ...

Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier in kebab-case
title	Yes	Human-readable title
version	No	Semantic version (default: 1.0.0)
description	No	Brief description of the skill
tags	No	Tags for categorization and search
triggers	No	Patterns that activate this skill (e.g., /code-review)
applyTo	No	File patterns where this skill is relevant
related	No	Names of related skills

Working with Skills via CLI

List Skills

# List all skills
gyrus skill list

# Filter by tags
gyrus skill list --tags typescript,quality

# List in a specific workspace
gyrus skill list --workspace work

Read a Skill

# Read by name
gyrus skill read code-review

# Read from specific workspace
gyrus skill read typescript-patterns --workspace work

Search Skills

# Search by text
gyrus skill search "testing"

# Search with filters
gyrus skill search "review" --tags quality

# Search by trigger
gyrus skill search --trigger "/review"

Create a Skill

# Create with flags
gyrus skill create \
  --name code-review \
  --title "Code Review Guide" \
  --content "# Code Review\n\nWhen reviewing code..." \
  --tags quality,review \
  --triggers /code-review,/review

# Create from file
gyrus skill create \
  --name api-design \
  --title "API Design Guidelines" \
  --file ./api-guidelines.md

Update a Skill

# Update content
gyrus skill update code-review --content "# Updated content..."

# Update tags
gyrus skill update code-review --tags quality,review,process

# Update triggers
gyrus skill update code-review --triggers /code-review,/review,/cr

Working with Skills via MCP

AI agents can interact with skills through MCP tools:

skill_list

List skills with optional filtering:

{
  "tags": ["typescript", "quality"]
}

skill_read

Read a specific skill:

{
  "name": "code-review"
}

skill_search

Search across skills:

{
  "query": "testing",
  "tags": ["quality"]
}

Or search by trigger:

{
  "trigger": "/code-review"
}

skill_create

Create a new skill:

{
  "name": "testing-strategy",
  "title": "Testing Strategy Guide",
  "content": "# Testing Strategy\n\nWhen writing tests...",
  "tags": ["testing", "quality"],
  "triggers": ["/test", "/testing"],
  "applyTo": ["*.test.ts", "*.spec.ts"]
}

skill_update

Update an existing skill:

{
  "name": "code-review",
  "tags": ["quality", "review", "process"],
  "triggers": ["/code-review", "/review", "/cr"]
}

Example Workflow

Loading a Skill for Code Review

User: Review this pull request.

Agent: Let me load the code review skill first.
[calls skill_read with name="code-review"]

Agent: I'll review using our code review guidelines:
- Checking code conventions...
- Verifying test coverage...
- Reviewing error handling...

Creating a Project-Specific Skill

User: We need consistent guidelines for our GraphQL resolvers.

Agent: I'll create a skill for that.
[calls skill_create]
  name: "graphql-resolvers"
  title: "GraphQL Resolver Guidelines"
  content: "..."
  tags: ["graphql", "api"]
  applyTo: ["*.resolver.ts"]

Agent: Created the skill. It will be available whenever
you're working on resolver files.

Best Practices

Keep Skills Focused

Each skill should cover a single, well-defined task or domain. If a skill grows too complex, split it into related skills.

Use Descriptive Triggers

Triggers make skills discoverable. Use intuitive names:

triggers: [/code-review, /review, /cr]

Include Examples

When possible, add an examples/ directory with concrete examples that demonstrate the skill in action.

Version Your Skills

Use semantic versioning to track changes:

version: 1.2.0

Tag for Discovery

Use consistent tags across skills:

• Domain: typescript, python, graphql
• Purpose: quality, testing, documentation
• Process: review, deployment, debugging

Link Related Skills

Use the related field to connect complementary skills:

related: [typescript-patterns, testing-strategy]

Skills vs Knowledge Notes

Aspect	Skills	Knowledge Notes
Purpose	How to do things	What to remember
Structure	Instructions, checklists	Information, context
Usage	Load on demand	Search and reference
Example	"How to review code"	"Gotchas in our API"

Use skills for reusable procedures and knowledge notes for captured information.

Next Steps

• Knowledge Notes — Capture information
• ADRs — Track architectural decisions
• MCP Integration — See all available AI tools