ZacharyZhang-NY
6f31415ed6
The PRD's first acceptance gate now holds: grep -RinE '\bx\.ai\b|grok' crates/ --include='*.rs' → 0 matches (exempt: NOTICE and third-party license archives, README provenance, and the required 'Based on Grok Build Open Source' attribution, now sourced from version_attribution.txt). Wire-visible renames (both sides in this repo, changed in lockstep): - Auth method id 'grok.com' → 'kimi-code' (AuthMethodKind::KimiCode). - Every x.ai/* and _x.ai/* ACP ext method and meta key → kigi/* / _kigi/* (~200 names; grokShell → kigiShell). Session-file replay keeps a read-side alias for the legacy '_x.ai/session/update' method so existing updates.jsonl histories load; writes emit only the new name (both directions test-pinned). - Agent types grok-build* → kigi* with a documented legacy-prefix alias at resolution time so persisted sessions keep resolving. - ToolNamespace/BuiltinAgentName GrokBuild* → Kigi* (wire snake_case kigi/kigi_concise/kigi_hashline; schema regenerated); grok_build implementation dirs renamed to kigi*. - x-grok-* headers → x-kigi-*, __GROK_* sentinels → __KIGI_*, themes grokday/groknight → kigiday/kiginight (old persisted values fall back to the default theme), web_fetch allowlist xAI hosts → kimi.com + moonshot platforms, changelog CDN → this repo, grok-build changelog archives deleted. - BYOK default endpoint removed: [endpoints] api_base_url is now truly optional with NO default — consumers fail fast with the flag name when unset (no silent x.ai egress). Mock harnesses inject it explicitly. - System-prompt identity fixed: 'released by xAI' → 'an unofficial community CLI for Kimi' (template + regenerated encrypted form). Also repaired pre-existing grok-era test debt found by the sweep: the stale trace_classify default-model pin, the grok-pager UA label test, pty-harness stale-binary reuse and non-hermetic moonshot routing (a PTY test could previously reach the real api.moonshot.cn), and the outdated oauth fixture scope key. Gates: §9 grep 0; fmt clean; workspace check/clippy 0/0 (-D warnings); FULL cargo test --workspace: 234 suites, 21,961 passed, 0 failed; deny advisories ok.
223 lines
12 KiB
Markdown
223 lines
12 KiB
Markdown
# Skills
|
||
|
||
Skills are reusable prompt packages that extend Kigi with task-specific instructions. They let you capture a repeatable procedure once, instead of re-explaining it each session.
|
||
|
||
---
|
||
|
||
## What Are Skills?
|
||
|
||
A skill is a directory that contains a `SKILL.md` file. Its markdown body tells Kigi how to handle a specific type of task: step-by-step instructions, conventions, and tool-usage patterns.
|
||
|
||
Use a skill for a repeatable procedure that's too specific for AGENTS.md but too long to retype. Kigi activates a skill only when it applies to your current task.
|
||
|
||
---
|
||
|
||
## Skill Locations
|
||
|
||
Kigi discovers skills from these directories, in priority order:
|
||
|
||
| Location | Scope | Priority | Notes |
|
||
|----------|-------|----------|-------|
|
||
| `./.kigi/skills/`, `./.kigi/commands/` | Local (CWD) | Highest | Current directory skills / legacy command markdown |
|
||
| `<repo_root>/.kigi/skills/`, `…/commands/` | Repo | Medium | Shared across the repo |
|
||
| `~/.kigi/skills/`, `~/.kigi/commands/` | User | Lowest | Personal skills for all projects |
|
||
| `~/.claude/skills/`, `~/.claude/commands/` | User | Lowest | Claude Code compatibility (configurable) |
|
||
| `./.claude/skills/`, `./.claude/commands/` | Local / Repo | High | Project Claude skills and legacy custom slash commands |
|
||
| `~/.cursor/skills/` | User | Lowest | Cursor compatibility (configurable) |
|
||
| `./.cursor/skills/` | Local / Repo | High | Project Cursor skills (when cursor compat skills are enabled) |
|
||
|
||
Kigi deduplicates skills by name -- a higher-priority location overrides a lower one. Kigi also scans `.agents/skills/` (and `commands/`) at each tier (alongside `.kigi/`) and walks every directory between your working directory and the repo root.
|
||
|
||
Flat `*.md` files under a `commands/` directory become user-invocable slash commands (filename stem = command name), matching Claude Code's legacy custom-command layout.
|
||
|
||
Skill and command discovery does **not** use `.gitignore`. Paths under known skill roots (`.kigi/`, `.agents/`, `.claude/`, `.cursor/`) always load when present on disk — teams often ignore `.claude/**` as local-only config while still expecting `/frontend`-style project commands to work. To hide a skill, use `[skills] ignore` in config (not repo ignore rules).
|
||
|
||
Kigi scans the Claude and Cursor skill directories by default. To stop scanning a vendor, set its `skills` cell to `false` under `[compat.cursor]` or `[compat.claude]` in `~/.kigi/config.toml`, or set the `KIGI_CURSOR_SKILLS_ENABLED` or `KIGI_CLAUDE_SKILLS_ENABLED` environment variable to `false`. See [Configuration](05-configuration.md#harness-compatibility) for details. Kigi always filters out known vendor-shipped default skills (such as Cursor's `shell`, `canvas`, and `statusline`), regardless of these settings.
|
||
|
||
### Additional Skill Directories
|
||
|
||
Add directories, exclude paths, or disable individual skills via `[skills]` in `~/.kigi/config.toml`:
|
||
|
||
```toml
|
||
[skills]
|
||
paths = ["~/my-team-skills"] # Additional directories to scan
|
||
ignore = ["~/my-team-skills/wip"] # Paths to exclude (hidden entirely)
|
||
disabled = ["wip-skill"] # Skill names to keep listed but inactive
|
||
```
|
||
|
||
Each entry in `paths` is a `SKILL.md` file or a directory that Kigi walks recursively. `ignore` hides a skill completely; `disabled` keeps it in the list but excludes it from the system prompt and from invocation. `paths` and `ignore` take filesystem paths and support `~` expansion; `disabled` takes skill names.
|
||
|
||
---
|
||
|
||
## Creating a Skill
|
||
|
||
### Directory Structure
|
||
|
||
Each skill lives in its own directory with a `SKILL.md` file:
|
||
|
||
```
|
||
~/.kigi/skills/
|
||
commit/
|
||
SKILL.md
|
||
review-pr/
|
||
SKILL.md
|
||
deploy/
|
||
SKILL.md
|
||
```
|
||
|
||
### SKILL.md Format
|
||
|
||
A skill file has YAML frontmatter followed by markdown instructions:
|
||
|
||
```markdown
|
||
---
|
||
name: commit
|
||
description: Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit.
|
||
---
|
||
|
||
# Git Commit Skill
|
||
|
||
Review staged changes and create a commit with a clear, conventional message.
|
||
|
||
## Steps
|
||
|
||
1. Run `git diff --staged` to see changes
|
||
2. Summarize what changed and why
|
||
3. Create commit message following conventional commits format
|
||
4. Run `git commit -m "..."` with the message
|
||
```
|
||
|
||
### Core Frontmatter Fields
|
||
|
||
| Field | Description |
|
||
|-------|-------------|
|
||
| `name` | Skill identifier. Use lowercase letters, digits, and hyphens, up to 64 characters. Kigi normalizes spaces and underscores to hyphens. If you omit `name`, Kigi uses the skill's directory name. |
|
||
| `description` | What the skill does and when to use it. Kigi reads this to decide whether to invoke the skill. If you omit it, Kigi uses the first paragraph of the body. |
|
||
|
||
Write a specific `description`. It determines when Kigi invokes the skill automatically. Name the trigger phrases and use cases.
|
||
|
||
### Optional Frontmatter Fields
|
||
|
||
Multi-word frontmatter keys use kebab-case (single-word keys like `model` are written as-is).
|
||
|
||
| Field | Description |
|
||
|-------|-------------|
|
||
| `when-to-use` | Trigger phrases for automatic invocation, kept separate from `description`. |
|
||
| `allowed-tools` | Tools the skill uses, as a YAML list or a comma- or space-separated string. |
|
||
| `argument-hint` | Hint text shown in the slash-command autocomplete (for example, `commit message`). |
|
||
| `user-invocable` | Whether you can run the skill as a slash command. Defaults to `true`; set `false` to hide it from slash commands. (To stop the model from invoking a skill, set `disable-model-invocation` instead.) |
|
||
| `disable-model-invocation` | When `true`, only your slash command runs the skill -- the model cannot invoke it automatically. Defaults to `false`. |
|
||
| `model` | Model override for running the skill. |
|
||
| `effort` | Reasoning-effort override. |
|
||
| `license` | License identifier (for example, `Apache-2.0`). |
|
||
| `compatibility` | Environment requirements (for example, `Requires git, docker, jq`). |
|
||
| `metadata` | Arbitrary string key-value pairs. Kigi promotes `metadata.author` and `metadata.short-description` for display. |
|
||
|
||
---
|
||
|
||
## Creating Skills with /create-skill
|
||
|
||
The `/create-skill` command walks you through building a new skill interactively. Kigi asks what you want, drafts the files, and writes them to disk.
|
||
|
||
### How It Works
|
||
|
||
When you run `/create-skill`, Kigi:
|
||
|
||
1. **Gathers requirements.** Kigi asks for the skill name, the scope to save it under, and a description of the workflow you want to capture. Use a name with lowercase letters, digits, and hyphens (2–64 characters, starting and ending with a letter or digit).
|
||
|
||
2. **Drafts the description.** Kigi writes a `description` that states what the skill does, the phrases that trigger it, and the slash command name. You approve or edit the draft before continuing.
|
||
|
||
3. **Creates the skill directory.** Kigi creates the `<scope>/.kigi/skills/<name>/` directory, plus `scripts/` or `references/` subdirectories when the skill needs them.
|
||
|
||
4. **Writes SKILL.md.** Kigi writes the frontmatter (`name` and `description`) and a markdown body of instructions, along with any supporting files.
|
||
|
||
5. **Verifies and confirms.** Kigi reads the file back, confirms it wrote correctly, and tells you how to run the skill.
|
||
|
||
### Choosing a Scope
|
||
|
||
Kigi asks where to save the skill:
|
||
|
||
- **Project** (`<repo_root>/.kigi/skills/<name>/`) -- available only in this repository and shareable with teammates through version control. Kigi recommends this scope inside a git repository.
|
||
- **User** (`~/.kigi/skills/<name>/`) -- available across all your projects.
|
||
|
||
The new skill appears in the slash menu within a few seconds, because Kigi reloads skills when files change on disk.
|
||
|
||
---
|
||
|
||
## Using Skills
|
||
|
||
### Run a Skill by Name
|
||
|
||
Each skill is a slash command named after the skill. Run one by typing its name:
|
||
|
||
```
|
||
/commit # Runs the "commit" skill
|
||
/review-pr # Runs the "review-pr" skill
|
||
```
|
||
|
||
Running a skill loads its instructions into the conversation and directs the model to follow them. To pass arguments, type them after the name:
|
||
|
||
```
|
||
/commit fix the build
|
||
```
|
||
|
||
To browse your skills, type `/` to open the slash-command menu. Kigi lists every built-in command and skill and filters them as you type. To list skills from the command line instead, run `kigi inspect` (see [Viewing Skill Details](#viewing-skill-details)).
|
||
|
||
### Qualified Names
|
||
|
||
When a skill's name collides with another skill or a built-in command, Kigi advertises a qualified name prefixed by the skill's scope -- `local:`, `repo:`, `user:`, or the plugin name. Use the qualified form to choose a specific skill:
|
||
|
||
```
|
||
/local:commit # The "commit" skill from ./.kigi/skills/
|
||
/user:commit # The "commit" skill from ~/.kigi/skills/
|
||
```
|
||
|
||
### Automatic Invocation
|
||
|
||
Kigi can invoke a skill on its own when it recognizes a relevant task. Kigi matches your prompt against the skill's `description` and `when-to-use` fields, so write both to describe the triggering situation.
|
||
|
||
For example, if a skill's description says "Use when the user wants to commit changes," then saying "commit my changes" can trigger that skill automatically. To require an explicit slash command and prevent automatic invocation, set `disable-model-invocation: true` in the frontmatter.
|
||
|
||
---
|
||
|
||
## Viewing Skill Details
|
||
|
||
Run `kigi inspect` to see every skill Kigi discovers, along with the rest of your configuration:
|
||
|
||
```bash
|
||
kigi inspect # Human-readable summary
|
||
kigi inspect --json # Machine-readable report
|
||
```
|
||
|
||
In the human-readable output, the Skills section lists each skill's name and its source -- `project`, `user`, `bundled`, `config` (a `[skills].paths` entry), `server` (skills synced from the skill store in managed workspaces), or `plugin: <name>`. Kigi tags any skill disabled via `[skills].disabled` or from a disabled vendor surface with `[disabled]`.
|
||
|
||
The report honors your `[skills]` config the same way a live session does: skills from `paths` are listed, skills under an `ignore` prefix are hidden, and skills named in `disabled` stay listed but tagged `[disabled]`.
|
||
|
||
The `--json` report includes the full detail for each skill: its `name`, `description`, `source` (with the path to the SKILL.md file), and `userInvocable` flag.
|
||
|
||
---
|
||
|
||
## Bundled and Plugin Skills
|
||
|
||
Kigi ships with built-in skills and extracts them to `~/.kigi/skills/` on startup -- among them `/create-skill`, `/help`, and `/check-work`. Bundled skills behave like user skills, and a same-named skill in a higher-priority location (local or repo) overrides the bundled copy; `kigi inspect` labels the extracted copies `bundled` so they stay distinguishable from skills you authored yourself. (A plugin skill of the same name does not override it; it stays available under its qualified `plugin:name` form.)
|
||
|
||
Skills can also come from plugins. When you install a plugin that includes skills, they appear alongside your user and project skills. `kigi inspect` labels each plugin-provided skill with its source as `plugin: <name>`.
|
||
|
||
See the [Plugins guide](09-plugins.md) for more on installing plugins that provide skills.
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
1. **Write specific descriptions.** The description drives automatic invocation. "Create git commits" is too vague; "Create well-formatted git commits following conventional commit standards. Use when the user wants to commit changes or asks for /commit." works better.
|
||
|
||
2. **Include concrete steps.** Skills work best when they give Kigi a clear, ordered procedure to follow.
|
||
|
||
3. **Reference tools by name.** When a skill relies on specific tools (such as `run_terminal_command` or `search_replace`), name them so the model knows what to use.
|
||
|
||
4. **Keep skills focused.** Write one skill per workflow. A "deploy" skill and a "rollback" skill work better than a single "deploy-and-rollback" skill.
|
||
|
||
5. **Version-control project skills.** Commit `.kigi/skills/` to your repository so the whole team benefits. User skills in `~/.kigi/skills/` stay personal and unshared.
|
||
|
||
6. **Test by running it.** Invoke `/name` and confirm the skill works before you rely on automatic invocation.
|