Skills

Skills are reusable markdown files that encode domain-specific guidance and repeatable workflows. Instead of repeating the same instructions across sessions, package them as a skill and load them on demand.

How Skills Work

1. You create a .md file in your skills directory
2. Nyzhi shows a skill index in its system prompt (names and descriptions only)
3. When the agent needs a skill, it loads the full content with load_skill

This keeps the base context lightweight while making specialized knowledge available.

Creating a Skill

Create a markdown file in .nyzhi/skills/:

---
description: Deploy to production with zero downtime
---

# Production Deploy

## Pre-deploy Checklist

1. All tests pass (`npm test`)
2. No lint errors (`npm run lint`)
3. Changelog updated
4. Version bumped in package.json

## Deploy Steps

1. Build production bundle: `npm run build`
2. Run smoke tests against staging
3. Deploy to production: `npm run deploy:prod`
4. Verify health endpoint: `curl https://api.example.com/health`
5. Monitor error rates for 15 minutes

## Rollback

If error rate exceeds 1%:

\`\`\`bash
npm run deploy:rollback
\`\`\`

Save this as .nyzhi/skills/production-deploy.md. The filename stem (production-deploy) becomes the skill name.

Skill Directories

Nyzhi looks for skills in two locations (checked in order):

1. <project>/.nyzhi/skills/ — primary
2. <project>/.claude/skills/ — fallback for compatibility

If both directories contain a file with the same name, the .nyzhi/skills/ version wins.

Skill File Format

• Extension: .md
• Name: derived from filename (e.g., deploy.md → skill name deploy)
• Description: extracted from:
  1. description: frontmatter line (preferred)
  2. First non-empty, non-heading line (fallback)

Using Skills

In the TUI

The agent sees a list of available skills in its context. When it needs one, it calls load_skill:

load_skill(name: "production-deploy")

You can also reference skills when giving instructions:

“Deploy using the production-deploy skill”

From the CLI

List all available skills:

nyz skills

Learning New Skills

From the TUI, use the /learn command to create new skills interactively.

Generating Skills

Use the template helper to scaffold a new skill:

# The agent can create skills for you
"Create a skill for our database migration workflow"

The template generates a structured markdown file with sections for description, steps, examples, and notes.

Example Skills

Code Review Checklist

---
description: Standard code review checklist for PRs
---

# Code Review

## Must Check
- [ ] No hardcoded secrets or credentials
- [ ] Error handling covers edge cases
- [ ] Tests cover the happy path and at least one failure case
- [ ] No N+1 queries or unbounded loops
- [ ] API changes are backward-compatible

## Style
- [ ] Functions do one thing
- [ ] Names are descriptive
- [ ] No commented-out code

API Design Standards

---
description: REST API conventions for this project
---

# API Design Standards

## Endpoints
- Use plural nouns: `/users`, not `/user`
- Nest sub-resources: `/users/{id}/orders`
- Use query params for filtering: `/users?role=admin`

## Responses
- Always return JSON
- Wrap collections: `{ "data": [...], "meta": { "total": 42 } }`
- Use HTTP status codes correctly (201 for creation, 204 for deletion)

## Errors
- Consistent error format:
  ```json
  { "error": { "code": "VALIDATION_ERROR", "message": "..." } }

## Best Practices

- **One skill, one responsibility** — keep skills focused
- **Include concrete examples** — code snippets and commands
- **Keep descriptions crisp** — they appear in the skill index
- **Use project-local skills** for team conventions
- **Use `.claude/skills/`** for shared baseline content across tools

## Next Steps

- [Memory](/docs/memory) — persistent knowledge across sessions
- [Configuration](/docs/configuration) — customize agent behavior
- [Hooks](/docs/hooks) — automate workflows