Skills

▶

Skills — walkthrough

Video walkthrough coming soon.

What is a skill

A skill is a plain-markdown file that describes how the agent should handle a specific kind of task. When the user sends a message, the agent picks the top-scoring skills by keyword overlap and injects their body into the system prompt for that turn. No code, no execution — skills are pure text.

Skills let you codify the way you want something done and have Hypex follow it without repeating yourself every chat.

Where they live

• Workspace-scoped: .hypex/skills/<slug>/SKILL.md — version-controlled alongside your project
• User-scoped: ~/.hypex/skills/<slug>/SKILL.md — follows you across workspaces

Both are loaded on startup. Workspace wins on slug conflict.

File format

A SKILL.md file is a markdown document with YAML frontmatter:

---
name: add-pytest-tests
description: Scaffold pytest tests for a Python module
when_to_use: The user asks to "add tests", "test this", "write pytest" or edits a .py file
allowed_tools: [read_file, write_file, run_command]
---

# Add pytest tests

When the user asks you to add tests for a Python module:

1. Read the target file with `read_file`.
2. Identify public functions and classes to cover.
3. For each public API, write a parametrized test case:
   - Happy path
   - One edge / boundary case
   - One error path (with `pytest.raises`)
4. Place tests in `tests/test_<module>.py` (create the dir if needed).
5. Run `pytest -x --tb=short` via `run_command` and iterate until green.

Use `pytest.mark.parametrize` to keep cases compact. Prefer fixtures over setUp/tearDown.

Frontmatter fields

Field	Required	Purpose
name	yes	Short slug, must match the directory name
description	yes	One-line summary shown in the skills tree
when_to_use	yes	Natural-language trigger — the matcher uses this + name + description for keyword scoring
allowed_tools	no	Optional array restricting which tools the agent can call while this skill is active

How matching works

Tiny TF-style keyword overlap. For each user message the skills manager:

1. Tokenizes the message
2. Scores each skill by count of tokens that appear in its when_to_use / name / description
3. Injects the top-N skills (default 3) whose score exceeds a threshold

No embeddings, no network, no external deps — the match runs in microseconds on-device.

Commands

• Hypex: List Skills — browse installed skills
• Hypex: Create Skill — scaffolds a new SKILL.md from a template
• Hypex: Reload Skills — re-scans the disk (also auto-fires on file save)
• Hypex: Delete Skill — removes the folder after a confirm

Skills tree in the sidebar

The Hypex sidebar shows a Skills section with Workspace + User sub-trees. Click a skill to preview its body in an editor tab; right-click for rename / delete.

Security

Skills are pure text. Hypex never executes scripts shipped inside a skill folder — if a skill folder contains setup.sh or run.py, those are references the agent may point at, not code we'll run on your behalf.

allowed_tools is an extra guardrail: even if the agent decides to call a tool outside the skill's allowed list, the call is refused.

Sharing skills

Drop a .hypex/skills/ folder in a public repo — collaborators clone the repo and every skill is instantly available. We'll ship a central marketplace later.

Examples shipped by default

• add-pytest-tests
• create-react-component
• dockerize-project
• generate-crud-api
• godot-gdscript-patterns
• pygame-basics
• setup-github-actions-ci

Browse them in ~/.hypex/skills/ and feel free to edit / delete.