Skills

What are skills?

A skill is a markdown file that contains instructions for the Salmex I/O agent. Drop a .md file into your workspace's .skills/ directory and the agent learns it immediately — no restart required.

Skills are the simplest way to extend your agent. They are:

• Just text — plain markdown with an optional YAML frontmatter header
• Portable — copy them between workspaces, share them with others, or version them in git
• Live-reloading — the agent detects changes on disk and picks them up automatically
• No code required — anyone who can write clear instructions can create a skill

Your first skill

Create a file at .skills/code-review.md in your workspace:

---
description: Review code for quality, bugs, and best practices
---

# Code Review

When asked to review code, follow this process:

1. **Read the full diff** before commenting on individual lines.
2. **Check for bugs** — logic errors, off-by-one mistakes, null/nil handling, race conditions.
3. **Check for security issues** — injection, hardcoded secrets, missing validation at boundaries.
4. **Check for clarity** — naming, structure, comments where non-obvious.
5. **Be specific** — reference line numbers and suggest concrete fixes, not vague advice.
6. **Be proportional** — a one-line typo fix does not need an essay. Match depth to complexity.

Finish with a summary: what's good, what needs fixing, and whether the change is ready to merge.

That's it. The agent will discover this skill within seconds and can use it immediately.

How skills work

Discovery

Salmex I/O scans the .skills/ directory in your workspace for .md files. The scan runs automatically at a configurable interval (default: every 30 seconds) and also when you trigger it manually via the CLI or UI. Subdirectories are scanned recursively — you can organise skills into folders.

.skills/
├── code-review.md
├── writing/
│   ├── blog-post.md
│   └── changelog.md
└── ops/
    ├── incident-response.md
    └── deploy-checklist.md

Skill names are derived from their file path relative to .skills/. The file above produces skills named code-review, writing/blog-post, writing/changelog, ops/incident-response, and ops/deploy-checklist.

Activation modes

Skills operate in one of two modes:

By default, skills are on-demand. The agent sees a catalogue of available skills and loads the ones it needs for the current task. Set always_active: true in the frontmatter to make a skill always-active.

Frontmatter

The YAML frontmatter at the top of the file is optional but recommended. It supports two fields:

---
description: One-line summary shown in the skill catalogue
always_active: false   # default; set to true to inject into every conversation
---

Files without frontmatter are treated as on-demand skills with no description. Adding a description helps the agent decide when to load the skill.

Content hashing

Every skill file is SHA-256 hashed on scan. When the content changes, the agent picks up the new version automatically. Metadata changes (like renaming or moving a file) are also detected. If a file is deleted, the skill is marked as removed and no longer offered to the agent.

Examples

Always-active: coding standards

---
description: Enforce project coding standards in all code changes
always_active: true
---

# Coding Standards

When writing or reviewing code in this project:

- Use Go 1.23+ idioms. Prefer errors.Join over multi-error libraries.
- All exported functions must have a doc comment.
- Table-driven tests with t.Run subtests. No testify — use standard library.
- Errors wrap with fmt.Errorf and %w. Never discard errors silently.
- Imports grouped: stdlib, external, internal. Sorted alphabetically within each group.
- No init() functions. No global mutable state. Explicit dependency injection.

Because always_active is true, these instructions are part of every conversation. The agent follows them without being asked.

On-demand: incident response

---
description: Step-by-step incident response procedure
---

# Incident Response

When an incident is reported:

1. **Acknowledge** — confirm you are investigating. State the time.
2. **Assess severity** — P1 (user-facing outage), P2 (degraded), P3 (internal only).
3. **Gather signals** — check logs, metrics, and recent deployments. List what you find.
4. **Identify root cause** — narrow down to the specific change or failure.
5. **Mitigate** — propose the smallest change that restores service. Prefer rollback over forward-fix.
6. **Communicate** — draft a status update for stakeholders with: what happened, current state, ETA.
7. **Post-mortem** — after resolution, list timeline, root cause, and action items.

Never guess. If you are unsure, say so and ask for more information.

This skill is loaded only when the agent determines it is relevant — for example, when you say "we have an incident" or "the API is down".

On-demand: blog post writing

---
description: Write a structured blog post with clear sections and a consistent voice
---

# Blog Post Writing

When asked to write a blog post:

**Structure:**
- Title: concise, specific, no clickbait
- Opening paragraph: state the problem or topic in 2-3 sentences
- Body: 3-5 sections with H2 headings, each making one point
- Closing: summary and a single call-to-action

**Voice:**
- First person plural ("we") for company blogs, first person singular for personal
- Short sentences. Active voice. No jargon without explanation.
- Technical accuracy over marketing polish

**Length:** 800-1200 words unless told otherwise.

Managing skills

Acceptance modes

Salmex I/O supports two modes for handling newly discovered skills:

• Auto-accept (default) — new workspace skills are activated immediately on discovery.
• Controlled — new skills start in a pending state and must be explicitly enabled. This is useful in shared workspaces or when you want to review skills before they take effect.

Configuration

Skills from plugins

Plugins can also provide skills. When a plugin declares "skills": true in its manifest, the host scans the plugin's .skills/ directory for markdown files. Plugin skills are automatically namespaced with the plugin name — a skill called forecast from the weather plugin becomes weather/forecast.

Plugin skills are always on-demand (never always-active) and are only available when the plugin is approved. If a workspace skill and a plugin skill share the same name, the workspace skill takes priority.

Writing good skills

• Be specific — "Check for SQL injection in user input" is better than "Look for security issues".
• Use numbered steps — the agent follows ordered lists more reliably than unstructured prose.
• State what not to do — explicit boundaries prevent drift. "Never commit directly to main" is clearer than hoping the agent infers it.
• Keep it focused — one skill per task. A 200-line skill that covers everything is worse than five focused skills the agent loads as needed.
• Write a good description — the description line is what the agent sees in the skill catalogue. Make it specific enough that the agent can decide whether to load it.
• Prefer on-demand — always-active skills consume part of the agent's context window in every conversation. Reserve always-active for instructions that genuinely apply everywhere.

What's next

• Plugins — when you need typed tools, secrets, and structured APIs beyond what markdown can express
• Architecture — how skills fit into the 8-layer system