knot knot

Skills

Skills are knowledge base content for AI assistants. They are markdown documents with YAML or TOML frontmatter that follow the Agent Skills Specification.

Overview

Skills provide context and instructions to AI assistants, helping them understand how to perform specific tasks. Skills can be used by:

  • The built-in knot web assistant
  • External AI tools that connect via MCP
  • Any AI system that supports the Agent Skills format

Knot supports two types of skills:

  • Global Skills: Available to all users (with optional group restrictions)
  • User Skills: Personal skills owned by individual users

User skills with the same name override (shadow) global skills, allowing users to customize behavior.

Managing Skills

Via Web Interface

Skills can be created and managed through the web interface under the Skills section. The editor supports:

  • Markdown content with syntax highlighting
  • YAML frontmatter editing
  • Zone and group access control

Via CLI

# List skills
knot skills list

# Create a skill
knot skills create my-skill.md

# Get a skill
knot skills get my-skill

# Update a skill
knot skills update my-skill --file updated.md

# Delete a skill
knot skills delete my-skill

Via Scripts

import knot.skill as skill

# Create a skill
skill.create("""---
name: "python-best-practices"
description: "Python coding best practices"
---

# Python Best Practices

- Follow PEP 8
- Use meaningful variable names
""")

# List skills
skills = skill.list()

# Search skills
results = skill.search("python")

Skill Format

Skills are markdown documents with YAML frontmatter:

---
name: "my-skill"
description: "Brief description of what this skill does"
---

# Skill Content

Your markdown content here...

Frontmatter Fields

Field Required Description
name Yes Skill name (1-64 chars, lowercase letters/numbers/hyphens)
description Yes Brief description (1-1024 chars)

Access Control

Zone Restrictions

Skills can be limited to specific zones:

  • If no zones are specified, the skill is available in all zones
  • Zones prefixed with ! are exclusions (e.g., !us-west-1 excludes that zone)
skill.create(content, zones=["us-east-1", "eu-west-1"])

Group Restrictions

Global skills can be restricted to specific user groups. Only users in those groups can access the skill.

skill.create(content, global=True, groups=["dev-team", "ops-team"])

Permissions

Permission Description
MANAGE_OWN_SKILLS Create, update, and delete your own skills
MANAGE_GLOBAL_SKILLS Create, update, and delete global skills

Example Skills

Team Conventions

---
name: "team-conventions"
description: "Coding conventions and best practices for our team"
---

# Team Conventions

## Branch Naming
- Feature: `feature/<ticket-id>-<description>`
- Bugfix: `fix/<ticket-id>-<description>`
- Hotfix: `hotfix/<ticket-id>-<description>`

## Commit Messages
- Use conventional commits format
- Reference ticket numbers in commit messages

## Code Review
- All changes require at least one approval
- Reviewers should check for test coverage

Deployment Guide

---
name: "deployment-guide"
description: "How to deploy applications to our environments"
---

# Deployment Guide

## Environments
- **dev**: Automatic deployment on merge to develop
- **staging**: Manual approval required
- **production**: Requires two approvals and change ticket

## Deployment Process
1. Create a release branch from main
2. Update version numbers
3. Run full test suite
4. Create pull request
5. After approval, merge to main
6. Tag the release

How Skills Work with the AI Assistant

When a user interacts with the web assistant, Knot dynamically builds the system prompt to include skill awareness:

  1. Skill summaries: The names and descriptions of all active, accessible skills (both global and user-owned) are appended to the system prompt. The full skill content is NOT included — only the name and description.

  2. On-demand retrieval: The assistant uses the get_skill tool to fetch full skill content when needed. This keeps the system prompt compact while still making all skill knowledge available.

  3. Platform-first behaviour: The system prompt instructs the assistant to check for relevant skills before performing platform tasks (nomad, docker, podman), ensuring it follows documented procedures.

For external MCP clients, skills are accessible via the get_skill tool (discoverable via tool_search). External clients are responsible for their own prompt engineering and skill retrieval logic.

What’s Next