# Kelyra Skills

Kelyra skills are local `SKILL.md` rule packs. They let a repo or developer define the operating rules Kelyra should follow before it edits files: architecture notes, files to read first, security boundaries, review expectations, and verification habits.

They are not runtime plugins and they do not execute code. A skill is plain Markdown with small YAML frontmatter, loaded into the system prompt when you pass `-s <name>`.

## Why Use Skills?

Good skills turn repeated project context into a reusable contract:

- Repo maintainers can commit `.kelyra/skills/repo/SKILL.md` so every Kelyra run follows the same project rules.
- Individual developers can keep global skills in `~/.kelyra/skills/<name>/SKILL.md` for personal workflows across repos.
- Reviewers can inspect SWD receipts to see which skill id and version were active during a verified edit.

This is useful when the same rules matter across many tasks: public API stability, command-surface safety, security review, docs style, release discipline, or project-specific architecture.

## Resolution Order

For named skills, Kelyra resolves in this order:

1. Project-local: `.kelyra/skills/<name>/SKILL.md`
2. User-global: `~/.kelyra/skills/<name>/SKILL.md`
3. Official bundled: `skills/official/<name>/SKILL.md`

Project skills intentionally win over global and official skills with the same name. A repo can therefore define its own `repo` skill without relying on every developer's home directory or the bundled default.

You can also pass an explicit file or directory path:

```bash
kelyra run --file TASK.md -s ./docs/examples/skills/repo
kelyra chat -s ./my-skill/SKILL.md
```

## Commands

```bash
kelyra learn
kelyra learn --dry-run
kelyra skills
kelyra skills new repo
kelyra skills new security-review --global
kelyra skills show repo
kelyra skills show frontend-polish
kelyra skills check
kelyra skills check repo
```

`kelyra skills new <name>` creates a project-local skill by default. Use `--global` only for personal cross-repo skills.

`kelyra learn` generates `.kelyra/skills/repo/SKILL.md` from deterministic local repo signals. It looks at docs, package metadata, source directories, CI workflows, config files, tests, command surfaces, and security-sensitive paths. It does not call a model and it does not run project commands. Treat the output as a strong first draft that should be reviewed and edited by the maintainer.

The quality guard is simple: `learn` only writes rules derived from files it can see locally, validates the generated skill format before writing, refuses to overwrite an existing skill unless `--force` is passed, and supports `--dry-run` for review.

## Official Skills

Kelyra ships with official skills for common high-signal workflows. They are bundled with the npm package and appear under the `Official skills` group in `kelyra skills`.

| Skill | Use it for |
| --- | --- |
| `repo` | General repository rules and scoped implementation work |
| `security-review` | Auth, secrets, command execution, CI, deploy, and writable path risk |
| `frontend-polish` | UI polish, responsive QA, copy fit, and interaction quality |
| `protocol-audit` | SWD, receipts, proof bundles, policy gates, MCP, and trust assumptions |
| `ci-hardening` | GitHub Actions, package scripts, release checks, and automation safety |
| `docs-release` | README, docs, launch copy, install paths, and changelog quality |
| `agent-proof` | External-agent handoff, model-free SWD applies, and receipt proof |
| `token-launch` | Token-gated access, wallet login, quotas, tiers, and public launch copy |
| `smart-contract-review` | Solidity, token contracts, ABIs, viem/ethers calls, and onchain reads |
| `console-product-review` | Hosted console, proof workflow UX, preview states, and clean routes |

Examples:

```bash
kelyra run --file TASK.md -s repo -s security-review
kelyra chat -s frontend-polish -s console-product-review
kelyra run "review token gate copy" -s token-launch -s docs-release
```

Official skills are defaults, not lock-in. Add `.kelyra/skills/<name>/SKILL.md` to a repo to override any official skill with project-specific rules.

## Skill Format

```markdown
---
name: repo
version: 0.1.0
description: Project operating rules for verified Kelyra runs.
priority: 70
budget-multiplier: 1.0
allow-fallback: true
---

# repo Skill

## Purpose
Explain the project context Kelyra must understand before editing files.

## Read First
- package.json
- README.md
- src/cli.ts

## Rules
- Preserve public CLI behavior unless the task explicitly asks for a breaking change.
- Keep edits scoped to the requested behavior.
- Do not change CI, install, deploy, or secret-handling files unless the task requires it.

## Verification
- Prefer the narrowest relevant check.
- If a check cannot be run safely, say exactly what the human should run.
```

### Frontmatter

| Field | Required | Purpose |
|-------|----------|---------|
| `name` | recommended | Human-readable skill name shown in CLI output and receipts |
| `version` | recommended | Skill version recorded in receipts |
| `description` | recommended | Short description for `kelyra skills` |
| `priority` | optional | Higher priority skills appear earlier in the active prompt |
| `budget-multiplier` | optional | Multiplies the session token cap for work that needs more context |
| `allow-fallback` | optional | Set `false` if the skill should disable provider fallback |
| `force-provider` | optional | Force a provider for this skill, if configured |
| `max-output-tokens` | optional | Cap output tokens for runs using this skill |
| `timeout-ms` | optional | Request timeout cap for runs using this skill |
| `requires-tools` | optional | Reserved for future tool-aware providers |
| `incompatible-with` | optional | Skill names or ids that should not be used together |

Example array fields:

```yaml
requires-tools:
  - filesystem
incompatible-with:
  - fast-docs
```

## Receipts

When a non-dry-run SWD operation writes a receipt, Kelyra records the active skill ids, names, versions, and sources. Project-local skill paths are stored as project-relative paths. Global or outside-project paths are omitted from receipts to avoid leaking a user's home directory.

Use:

```bash
kelyra receipts show latest
kelyra receipts show latest --markdown
```

This gives reviewers a lightweight audit trail:

- What task was requested.
- What files SWD verified.
- Which provider/model ran.
- Which skill rule packs were active.
- Whether the current files still match the receipt.

## Recommended Patterns

Use a project `repo` skill for durable rules:

- important architecture files
- public API boundaries
- release/versioning expectations
- files Kelyra should avoid unless asked
- preferred verification commands

Use global skills for reusable personal workflows:

- security review checklist
- docs editing style
- strict minimal-diff mode
- frontend accessibility review

Keep skills short and specific. A good skill feels like a senior maintainer leaving durable instructions, not a second README.

## Examples

Example skill files live in:

- `docs/examples/skills/repo/SKILL.md`
- `docs/examples/skills/security-review/SKILL.md`

Official bundled skills live in:

- `skills/official/<name>/SKILL.md`